Workaround for dokka bug: https://github.com/Kotlin/dokka/issues/4001

Move last projects from JVM to MPP.
Update changelog.

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+@altavir
+
+/kmath-trajectory @ESchouten

.github/workflows/build.yml

@@ -2,41 +2,33 @@ name: Gradle build
 
 on:
   push:
+    branches: [ dev, master ]
   pull_request:
-    types: [opened, edited]
 
 jobs:
   build:
-    strategy:
-      matrix:
-        os: [ macOS-latest, windows-latest ]
-    runs-on: ${{matrix.os}}
-    timeout-minutes: 30
+    runs-on: windows-latest
+    timeout-minutes: 20
     steps:
-      - name: Checkout the repo
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: DeLaGuardo/setup-graalvm@4.0
+      - uses: actions/checkout@v6
+      - uses: actions/setup-java@v5
         with:
-          graalvm: 21.1.0
-          java: java11
-          arch: amd64
-      - name: Add msys to path
-        if: matrix.os == 'windows-latest'
-        run: SETX PATH "%PATH%;C:\msys64\mingw64\bin"
-      - name: Cache gradle
-        uses: actions/cache@v2
+          java-version: '21'
+          distribution: 'liberica'
+          cache: 'gradle'
+      - name: Gradle Wrapper Validation
+        uses: gradle/wrapper-validation-action@v1.0.4
+      - name: Gradle Build
+        uses: gradle/gradle-build-action@v3
         with:
-          path: ~/.gradle/caches
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-      - name: Cache konan
-        uses: actions/cache@v2
+          arguments: test jvmTest
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v6
+        if: ${{ !cancelled() }} # always run even if the previous step fails
         with:
-          path: ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-      - name: Build
-        run: ./gradlew build --no-daemon --stacktrace
+          report_paths: '**/test-results/**/TEST-*.xml'
+          annotate_only: true
+          detailed_summary: true
+          flaky_summary: true
+          include_empty_in_summary: false
+          skip_success_summary: true

.github/workflows/pages.yml

@@ -1,24 +1,26 @@
 name: Dokka publication
 
 on:
-  push:
-    branches:
-      - master
+  workflow_dispatch:
+  release:
+    types: [ created ]
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
     steps:
-      - name: Checkout the repo
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: actions/setup-java@v1
+      - uses: actions/checkout@v6
+      - uses: actions/setup-java@v5
         with:
-          java-version: 11
-      - name: Build
-        run: ./gradlew dokkaHtmlMultiModule --no-daemon --no-parallel --stacktrace
-      - name: Deploy to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@4.1.0
+          java-version: 21
+          distribution: liberica
+      - name: Gradle Wrapper Validation
+        uses: gradle/wrapper-validation-action@v1.0.4
+      - uses: gradle/gradle-build-action@v3
+        with:
+          arguments: dokkaGenerate --no-parallel
+      - uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
-          folder: build/dokka/htmlMultiModule
+          folder: build/dokka/html

.github/workflows/publish.yml

@@ -1,61 +0,0 @@
-name: Gradle publish
-
-on:
-  workflow_dispatch:
-  release:
-    types:
-      - created
-
-jobs:
-  publish:
-    environment:
-      name: publish
-    strategy:
-      matrix:
-        os: [ macOS-latest, windows-latest ]
-    runs-on: ${{matrix.os}}
-    steps:
-      - name: Checkout the repo
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: DeLaGuardo/setup-graalvm@4.0
-        with:
-          graalvm: 21.1.0
-          java: java11
-          arch: amd64
-      - name: Add msys to path
-        if: matrix.os == 'windows-latest'
-        run: SETX PATH "%PATH%;C:\msys64\mingw64\bin"
-      - name: Cache gradle
-        uses: actions/cache@v2
-        with:
-          path: ~/.gradle/caches
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-      - name: Cache konan
-        uses: actions/cache@v2
-        with:
-          path: ~/.konan
-          key: ${{ runner.os }}-gradle-${{ hashFiles('*.gradle.kts') }}
-          restore-keys: |
-            ${{ runner.os }}-gradle-
-      - name: Publish Windows Artifacts
-        if: matrix.os == 'windows-latest'
-        run: >
-          ./gradlew release --no-daemon
-          -Ppublishing.enabled=true
-          -Ppublishing.github.user=${{ secrets.PUBLISHING_GITHUB_USER }}
-          -Ppublishing.github.token=${{ secrets.PUBLISHING_GITHUB_TOKEN }}
-          -Ppublishing.space.user=${{ secrets.PUBLISHING_SPACE_USER }}
-          -Ppublishing.space.token=${{ secrets.PUBLISHING_SPACE_TOKEN }}
-      - name: Publish Mac Artifacts
-        if: matrix.os == 'macOS-latest'
-        run: >
-          ./gradlew release --no-daemon
-          -Ppublishing.enabled=true
-          -Ppublishing.platform=macosX64
-          -Ppublishing.github.user=${{ secrets.PUBLISHING_GITHUB_USER }}
-          -Ppublishing.github.token=${{ secrets.PUBLISHING_GITHUB_TOKEN }}
-          -Ppublishing.space.user=${{ secrets.PUBLISHING_SPACE_USER }}
-          -Ppublishing.space.token=${{ secrets.PUBLISHING_SPACE_TOKEN }}

.gitignore

@@ -3,11 +3,10 @@ build/
 out/
 
 .idea/
-
-!.idea/copyright/
-!.idea/scopes/
-
 .vscode/
+.fleet/
+.kotlin/
+
 
 # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
 !gradle-wrapper.jar
@@ -18,3 +17,8 @@ out/
 # Generated by javac -h and runtime
 *.class
 *.log
+
+!/.idea/copyright/
+!/.idea/scopes/
+/gradle/yarn.lock
+

.idea/copyright/kmath.xml

@@ -1,6 +1,7 @@
 <component name="CopyrightManager">
-    <copyright>
-        <option name="notice" value="Copyright 2018-2021 KMath contributors.&#10;Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file." />
-        <option name="myName" value="kmath" />
-    </copyright>
-</component>
+  <copyright>
+    <option name="allowReplaceRegexp" value="Copyright \d{4}-\d{4} KMath" />
+    <option name="notice" value="Copyright 2018-&amp;#36;today.year KMath contributors.&#10;Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file." />
+    <option name="myName" value="kmath" />
+  </copyright>
+</component>

.idea/copyright/profiles_settings.xml

@@ -1,5 +1,5 @@
 <component name="CopyrightManager">
-  <settings default="kmath">
+  <settings>
     <module2copyright>
       <element module="Apply copyright" copyright="kmath" />
     </module2copyright>

.idea/scopes/Apply_copyright.xml

@@ -1,4 +1,3 @@
 <component name="DependencyValidationManager">
-    <scope name="Apply copyright"
-           pattern="!file[*]:*//testData//*&amp;&amp;!file[*]:testData//*&amp;&amp;!file[*]:*.gradle.kts&amp;&amp;!file[*]:*.gradle&amp;&amp;!file[group:kotlin-ultimate]:*/&amp;&amp;!file[kotlin.libraries]:stdlib/api//*"/>
-</component>
+    <scope name="Apply copyright" pattern="!file[*]:*//testData//*&amp;&amp;!file[*]:testData//*&amp;&amp;!file[*]:*.gradle.kts&amp;&amp;!file[*]:*.gradle&amp;&amp;!file[group:kotlin-ultimate]:*/&amp;&amp;!file[kotlin.libraries]:stdlib/api//*" />
+</component>

.space.kts

@@ -1,3 +0,0 @@
-job("Build") {
-    gradlew("openjdk:11", "build")
-}

CHANGELOG.md

@@ -1,7 +1,140 @@
 # KMath
 
-## [Unreleased]
+## Unreleased
+
 ### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## 0.5.0 - 2026-01-09
+
+### Added
+
+- More statistics functions by @qwazer
+- Fit accessors with Attribute
+
+### Changed
+
+- Flag attributes are replaced with boolean attributes to properly support missing values
+- Upgrade tensorflow version to 1.0.0
+
+### Removed
+
+- Support for ND4J
+
+## 0.4.2 - 2025-01-27
+
+### Added
+
+- Convenient matrix builders for rows, columns, vstacks and hstacks
+- Sparse matrix builder
+
+### Fixed
+
+- Ojalgo conversion bug which made all converted matrices be zero.
+
+## 0.4.1 - 2025-01-12
+
+### Added
+
+- Metropolis-Hastings sampler
+- Ojalgo `LinearSpace` implementation.
+
+### Changed
+
+- attributes-kt moved to a separate project, and the version used is 0.3.0
+- Kotlin 2.1. Now use cross-compilation to deploy macOS targets.
+- Changed `origin` to `cmMatrix` in kmath-commons to avoid property name clash. Expose bidirectional conversion in `CMLinearSpace`
+- (BREAKING CHANGE) Changed implementations in `kmath-ejml` to match CM and ojalgo style. Specifically, provide bidirectional conversion for library types.
+
+### Fixed
+
+- (BREAKING CHANGE) Fix EJML to properly treat vectors as columns
+
+## 0.4.0 - 2024-02-18
+
+### Added
+
+- Reification. Explicit `SafeType` for algebras.
+- Integer division algebras.
+- Float32 geometries.
+- New Attributes-kt module that could be used as stand-alone. It declares. type-safe attributes containers.
+- Explicit `mutableStructureND` builders for mutable structures.
+- `Buffer.asList()` zero-copy transformation.
+- Wasm support.
+- Parallel implementation of `LinearSpace` for Float64
+- Parallel buffer factories
+
+### Changed
+
+- Buffer copy removed from API (added as an extension).
+- Default naming for algebra and buffers now uses IntXX/FloatXX notation instead of Java types.
+- Remove unnecessary inlines in basic algebras.
+- QuaternionField -> QuaternionAlgebra and does not implement `Field` anymore since it is non-commutative
+- kmath-geometry is split into `euclidean2d` and `euclidean3d`
+- Features replaced with Attributes.
+- Transposed refactored.
+- Kmath-memory is moved on top of core.
+
+### Deprecated
+
+- ND4J engine
+
+### Removed
+
+- `asPolynomial` function due to scope pollution
+- Codegend for ejml (450 lines of codegen for 1000 lines of code is too much)
+
+### Fixed
+
+- Median statistics
+- Complex power of negative real numbers
+- Add proper mutability for MutableBufferND rows and columns
+- Generic Float32 and Float64 vectors are used in geometry algebras.
+
+## 0.3.1 - 2023-04-09
+
+### Added
+
+- Wasm support for `memory`, `core`, `complex` and `functions` modules.
+- Generic builders for `BufferND` and `MutableBufferND`
+- `NamedMatrix` - matrix with symbol-based indexing
+- `Expression` with default arguments
+- Type-aliases for numbers like `Float64`
+- Autodiff for generic algebra elements in core!
+- Algebra now has an obligatory `bufferFactory` (#477).
+
+### Changed
+
+- Removed marker `Vector` type for geometry
+- Geometry uses type-safe angles
+- Tensor operations switched to prefix notation
+- Row-wise and column-wise ND shapes in the core
+- Shape is read-only
+- Major refactor of tensors (only minor API changes)
+- Kotlin 1.8.20
+- `LazyStructure` `deffered` -> `async` to comply with coroutines code style
+- Default `dot` operation in tensor algebra no longer support broadcasting. Instead `matmul` operation is added
+  to `DoubleTensorAlgebra`.
+- Multik went MPP
+
+### Removed
+
+- Trajectory moved to https://github.com/SciProgCentre/maps-kt
+- Polynomials moved to https://github.com/SciProgCentre/kmath-polynomial
+
+## 0.3.0
+
+### Added
+
 - `ScaleOperations` interface
 - `Field` extends `ScaleOperations`
 - Basic integration API
@@ -13,10 +146,21 @@
 - Extended operations for ND4J fields
 - Jupyter Notebook integration module (kmath-jupyter)
 - `@PerformancePitfall` annotation to mark possibly slow API
+- Unified architecture for Integration and Optimization using features.
 - `BigInt` operation performance improvement and fixes by @zhelenskiy (#328)
 - Integration between `MST` and Symja `IExpr`
+- Complex power
+- Separate methods for UInt, Int and Number powers. NaN safety.
+- Tensorflow prototype
+- `ValueAndErrorField`
+- MST compilation to WASM: #286
+- Jafama integration: #176
+- `contentEquals` with tolerance: #364
+- Compilation to TeX for MST: #254
 
 ### Changed
+
+- Annotations moved to `space.kscience.kmath`
 - Exponential operations merged with hyperbolic functions
 - Space is replaced by Group. Space is reserved for vector spaces.
 - VectorSpace is now a vector space
@@ -36,10 +180,24 @@
 - Remove Any restriction on polynomials
 - Add `out` variance to type parameters of `StructureND` and its implementations where possible
 - Rename `DifferentiableMstExpression` to `KotlingradExpression`
+- `FeatureSet` now accepts only `Feature`. It is possible to override keys and use interfaces.
+- Use `Symbol` factory function instead of `StringSymbol`
+- New discoverability pattern: `<Type>.algebra.<nd/etc>`
+- Adjusted commons-math API for linear solvers to match conventions.
+- Buffer algebra does not require size anymore
+- Operations -> Ops
+- Default Buffer and ND algebras are now Ops and lack neutral elements (0, 1) as well as algebra-level shapes.
+- Tensor algebra takes read-only structures as input and inherits AlgebraND
+- `UnivariateDistribution` renamed to `Distribution1D`
+- Rework of histograms.
+- `UnivariateFunction` -> `Function1D`, `MultivariateFunction` -> `FunctionND`
 
 ### Deprecated
 
+- Specialized `DoubleBufferAlgebra`
+
 ### Removed
+
 - Nearest in Domain. To be implemented in geometry package.
 - Number multiplication and division in main Algebra chain
 - `contentEquals` from Buffer. It moved to the companion.
@@ -47,15 +205,17 @@
 - Expression algebra builders
 - Complex and Quaternion no longer are elements.
 - Second generic from DifferentiableExpression
+- Algebra elements are completely removed. Use algebra contexts instead.
 
 ### Fixed
+
 - Ring inherits RingOperations, not GroupOperations
 - Univariate histogram filling
 
-### Security
+## 0.2.0
 
-## [0.2.0]
 ### Added
+
 - `fun` annotation for SAM interfaces in library
 - Explicit `public` visibility for all public APIs
 - Better trigonometric and hyperbolic functions for `AutoDiffField` (https://github.com/mipt-npm/kmath/pull/140)
@@ -75,6 +235,7 @@
 - Basic Quaternion vector support in `kmath-complex`.
 
 ### Changed
+
 - Package changed from `scientifik` to `space.kscience`
 - Gradle version: 6.6 -> 6.8.2
 - Minor exceptions refactor (throwing `IllegalArgumentException` by argument checks instead of `IllegalStateException`)
@@ -84,7 +245,7 @@
 - Full autodiff refactoring based on `Symbol`
 - `kmath-prob` renamed to `kmath-stat`
 - Grid generators moved to `kmath-for-real`
-- Use `Point<Double>` instead of specialized type in `kmath-for-real`
+- Use `Point<Float64>` instead of specialized type in `kmath-for-real`
 - Optimized dot product for buffer matrices moved to `kmath-for-real`
 - EjmlMatrix context is an object
 - Matrix LUP `inverse` renamed to `inverseWithLup`
@@ -98,9 +259,8 @@
 - `symbol` method in `Algebra` renamed to `bindSymbol` to avoid ambiguity
 - Add `out` projection to `Buffer` generic
 
-### Deprecated
-
 ### Removed
+
 - `kmath-koma` module because it doesn't support Kotlin 1.4.
 - Support of `legacy` JS backend (we will support only IR)
 - `toGrid` method.
@@ -109,22 +269,24 @@
 - StructureND identity and equals
 
 ### Fixed
+
 - `symbol` method in `MstExtendedField` (https://github.com/mipt-npm/kmath/pull/140)
 
-### Security
-
-## [0.1.4]
+## 0.1.4
 
 ### Added
+
 - Functional Expressions API
 - Mathematical Syntax Tree, its interpreter and API
 - String to MST parser (https://github.com/mipt-npm/kmath/pull/120)
 - MST to JVM bytecode translator (https://github.com/mipt-npm/kmath/pull/94)
 - FloatBuffer (specialized MutableBuffer over FloatArray)
 - FlaggedBuffer to associate primitive numbers buffer with flags (to mark values infinite or missing, etc.)
-- Specialized builder functions for all primitive buffers like `IntBuffer(25) { it + 1 }` (https://github.com/mipt-npm/kmath/pull/125)
+- Specialized builder functions for all primitive buffers
+  like `IntBuffer(25) { it + 1 }` (https://github.com/mipt-npm/kmath/pull/125)
 - Interface `NumericAlgebra` where `number` operation is available to convert numbers to algebraic elements
-- Inverse trigonometric functions support in ExtendedField (`asin`, `acos`, `atan`) (https://github.com/mipt-npm/kmath/pull/114)
+- Inverse trigonometric functions support in
+  ExtendedField (`asin`, `acos`, `atan`) (https://github.com/mipt-npm/kmath/pull/114)
 - New space extensions: `average` and `averageWith`
 - Local coding conventions
 - Geometric Domains API in `kmath-core`
@@ -133,10 +295,12 @@
 - Norm support for `Complex`
 
 ### Changed
+
 - `readAsMemory` now has `throws IOException` in JVM signature.
 - Several functions taking functional types were made `inline`.
 - Several functions taking functional types now have `callsInPlace` contracts.
-- BigInteger and BigDecimal algebra: JBigDecimalField has companion object with default math context; minor optimizations
+- BigInteger and BigDecimal algebra: JBigDecimalField has companion object with default math context; minor
+  optimizations
 - `power(T, Int)` extension function has preconditions and supports `Field<T>`
 - Memory objects have more preconditions (overflow checking)
 - `tg` function is renamed to `tan` (https://github.com/mipt-npm/kmath/pull/114)
@@ -144,6 +308,7 @@
 - Moved probability distributions to commons-rng and to `kmath-prob`
 
 ### Fixed
+
 - Missing copy method in Memory implementation on JS (https://github.com/mipt-npm/kmath/pull/106)
 - D3.dim value in `kmath-dimensions`
 - Multiplication in integer rings in `kmath-core` (https://github.com/mipt-npm/kmath/pull/101)

README.md

@@ -1,95 +1,65 @@
 [![JetBrains Research](https://jb.gg/badges/research.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
 [![DOI](https://zenodo.org/badge/129486382.svg)](https://zenodo.org/badge/latestdoi/129486382)
-![Gradle build](https://github.com/mipt-npm/kmath/workflows/Gradle%20build/badge.svg)
+![Gradle build](https://github.com/SciProgCentre/kmath/workflows/Gradle%20build/badge.svg)
 [![Maven Central](https://img.shields.io/maven-central/v/space.kscience/kmath-core.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22space.kscience%22)
-[![Space](https://img.shields.io/badge/dynamic/xml?color=orange&label=Space&query=//metadata/versioning/latest&url=https%3A%2F%2Fmaven.pkg.jetbrains.space%2Fmipt-npm%2Fp%2Fsci%2Fmaven%2Fspace%2Fkscience%2Fkmath-core%2Fmaven-metadata.xml)](https://maven.pkg.jetbrains.space/mipt-npm/p/sci/maven/space/kscience/)
 
 # KMath
 
-Could be pronounced as `key-math`. The **K**otlin **Math**ematics library was initially intended as a Kotlin-based analog to
-Python's NumPy library. Later we found that kotlin is much more flexible language and allows superior architecture 
-designs. In contrast to `numpy` and `scipy` it is modular and has a lightweight core. The `numpy`-like experience could 
-be achieved with [kmath-for-real](/kmath-for-real) extension module.
+Could be pronounced as `key-math`. The **K**otlin **Math**ematics library was initially intended as a Kotlin-based analog to Python's NumPy library. Later we found that kotlin is a much more flexible language and allows superior architecture designs. In contrast to `numpy` and `scipy` it is modular and has a lightweight core. The `numpy`-like experience could be achieved with [kmath-for-real](kmath-for-real) extension module.
 
-[Documentation site (**WIP**)](https://mipt-npm.github.io/kmath/)
+[Documentation site](https://SciProgCentre.github.io/kmath/)
 
 ## Publications and talks
 
 * [A conceptual article about context-oriented design](https://proandroiddev.com/an-introduction-context-oriented-programming-in-kotlin-2e79d316b0a2)
 * [Another article about context-oriented design](https://proandroiddev.com/diving-deeper-into-context-oriented-programming-in-kotlin-3ecb4ec38814)
 * [ACAT 2019 conference paper](https://aip.scitation.org/doi/abs/10.1063/1.5130103)
+* [A talk at KotlinConf 2019 about using kotlin for science](https://youtu.be/LI_5TZ7tnOE?si=4LknX41gl_YeUbIe)
+* [A talk on architecture at Joker-2021 (in Russian)](https://youtu.be/1bZ2doHiRRM?si=9w953ro9yu98X_KJ)
+* [The same talk in English](https://youtu.be/yP5DIc2fVwQ?si=louZzQ1dcXV6gP10)
+* [A seminar on tensor API](https://youtu.be/0H99wUs0xTM?si=6c__04jrByFQtVpo)
 
 # Goal
 
-* Provide a flexible and powerful API to work with mathematics abstractions in Kotlin-multiplatform (JVM, JS and Native). 
+* Provide a flexible and powerful API to work with mathematics abstractions in Kotlin-multiplatform (JVM, JS, Native and
+  Wasm).
 * Provide basic multiplatform implementations for those abstractions (without significant performance optimization).
 * Provide bindings and wrappers with those abstractions for popular optimized platform libraries.
 
 ## Non-goals
 
-* Be like NumPy. It was the idea at the beginning, but we decided that we can do better in terms of API.
+* Be like NumPy. It was the idea at the beginning, but we decided that we can do better in API.
 * Provide the best performance out of the box. We have specialized libraries for that. Need only API wrappers for them.
 * Cover all cases as immediately and in one bundle. We will modularize everything and add new features gradually.
-* Provide specialized behavior in the core. API is made generic on purpose, so one needs to specialize for types, like 
-for `Double` in the core. For that we will have specialization modules like `kmath-for-real`, which will give better
-experience for those, who want to work with specific types.
+* Provide specialized behavior in the core. API is made generic on purpose, so one needs to specialize for types, like for `Float64` in the core. For that we will have specialization modules like [kmath-for-real](kmath-for-real), which will give a better experience for those who want to work with specific types.
+
+## Contributing
+
+The project requires a lot of additional work. The most important thing we need is feedback about what features are required the most. Feel free to create feature requests. We are also welcome to code contributions, especially in issues marked with [good first issue](https://github.com/SciProgCentre/kmath/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label.
+
+Project roadmap will be available at [GitHub Projects](https://github.com/orgs/SciProgCentre/projects/3).
 
 ## Features and stability
 
-KMath is a modular library. Different modules provide different features with different API stability guarantees. All core modules are released with the same version, but with different API change policy. The features are described in module definitions below. The module stability could have following levels:
+KMath is a modular library. Different modules provide different features with different API stability guarantees. All core modules are released with the same version, but with different API change policy. The features are described in module definitions below. The module stability could have the following levels:
 
-* **PROTOTYPE**. On this level there are no compatibility guarantees. All methods and classes form those modules could break any moment. You can still use it, but be sure to fix the specific version.
-* **EXPERIMENTAL**. The general API is decided, but some changes could be made. Volatile API is marked with `@UnstableKmathAPI` or other stability warning annotations.
-* **DEVELOPMENT**. API breaking generally follows semantic versioning ideology. There could be changes in minor versions, but not in patch versions. API is protected with [binary-compatibility-validator](https://github.com/Kotlin/binary-compatibility-validator) tool.
+* **PROTOTYPE**. On this level there are no compatibility guarantees. All methods and classes form those modules could
+  break any moment. You can still use it, but be sure to fix the specific version.
+* **EXPERIMENTAL**. The general API is decided, but some changes could be made. Volatile API is marked
+  with `@UnstableKMathAPI` or other stability warning annotations.
+* **DEVELOPMENT**. API breaking generally follows semantic versioning ideology. There could be changes in minor
+  versions, but not in patch versions. API is protected
+  with [binary-compatibility-validator](https://kotlinlang.org/docs/gradle-binary-compatibility-validation.html) tool.
 * **STABLE**. The API stabilized. Breaking changes are allowed only in major releases.
 
-<!--Current feature list is [here](/docs/features.md)-->
-
-
-<!--* **Array-like structures** Full support of many-dimensional array-like structures -->
-<!--including mixed arithmetic operations and function operations over arrays and numbers (with the added benefit of static type checking).-->
-
-<!--* **Histograms** Fast multi-dimensional histograms.-->
-
-<!--* **Streaming** Streaming operations on mathematical objects and objects buffers.-->
-
-<!--* **Type-safe dimensions** Type-safe dimensions for matrix operations.-->
-
-<!--* **Commons-math wrapper** It is planned to gradually wrap most parts of -->
-<!--[Apache commons-math](http://commons.apache.org/proper/commons-math/) library in Kotlin code and maybe rewrite some -->
-<!--parts to better suit the Kotlin programming paradigm, however there is no established roadmap for that. Feel free to -->
-<!--submit a feature request if you want something to be implemented first.-->
-<!--                           -->
-<!--## Planned features-->
-
-<!--* **Messaging** A mathematical notation to support multi-language and multi-node communication for mathematical tasks.-->
-
-<!--* **Array statistics** -->
-
-<!--* **Integration** Univariate and multivariate integration framework.-->
-
-<!--* **Probability and distributions**-->
-
-<!--* **Fitting** Non-linear curve fitting facilities-->
-
 ## Modules
 
-<hr/>
 
-* ### [benchmarks](benchmarks)
-> 
+### [benchmarks](benchmarks)
 >
 > **Maturity**: EXPERIMENTAL
-<hr/>
 
-* ### [examples](examples)
-> 
->
-> **Maturity**: EXPERIMENTAL
-<hr/>
-
-* ### [kmath-ast](kmath-ast)
-> 
+### [kmath-ast](kmath-ast)
 >
 > **Maturity**: EXPERIMENTAL
 >
@@ -99,26 +69,23 @@ KMath is a modular library. Different modules provide different features with di
 > - [mst-js-codegen](kmath-ast/src/jsMain/kotlin/space/kscience/kmath/estree/estree.kt) : Dynamic MST to JS compiler
 > - [rendering](kmath-ast/src/commonMain/kotlin/space/kscience/kmath/ast/rendering/MathRenderer.kt) : Extendable MST rendering
 
-<hr/>
 
-* ### [kmath-commons](kmath-commons)
-> 
+### [kmath-commons](kmath-commons)
+> Commons math binding for kmath
 >
 > **Maturity**: EXPERIMENTAL
-<hr/>
 
-* ### [kmath-complex](kmath-complex)
+### [kmath-complex](kmath-complex)
 > Complex numbers and quaternions.
 >
 > **Maturity**: PROTOTYPE
 >
 > **Features:**
-> - [complex](kmath-complex/src/commonMain/kotlin/space/kscience/kmath/complex/Complex.kt) : Complex Numbers
-> - [quaternion](kmath-complex/src/commonMain/kotlin/space/kscience/kmath/complex/Quaternion.kt) : Quaternions
+> - [complex](kmath-complex/src/commonMain/kotlin/space/kscience/kmath/complex/Complex.kt) : Complex numbers operations
+> - [quaternion](kmath-complex/src/commonMain/kotlin/space/kscience/kmath/complex/Quaternion.kt) : Quaternions and their composition
 
-<hr/>
 
-* ### [kmath-core](kmath-core)
+### [kmath-core](kmath-core)
 > Core classes, algebra definitions, basic linear algebra
 >
 > **Maturity**: DEVELOPMENT
@@ -126,30 +93,24 @@ KMath is a modular library. Different modules provide different features with di
 > **Features:**
 > - [algebras](kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Algebraic structures like rings, spaces and fields.
 > - [nd](kmath-core/src/commonMain/kotlin/space/kscience/kmath/structures/StructureND.kt) : Many-dimensional structures and operations on them.
-> - [linear](kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Basic linear algebra operations (sums, products, etc.), backed by the `Space` API. Advanced linear algebra operations like matrix inversion and LU decomposition.
+> - [linear](kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt) : Basic linear algebra operations (sums, products, etc.), backed by the `Space` API. 
 > - [buffers](kmath-core/src/commonMain/kotlin/space/kscience/kmath/structures/Buffers.kt) : One-dimensional structure
-> - [expressions](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of 
-objects to the expression by providing a context. Expressions can be used for a wide variety of purposes from high 
-performance calculations to code generation.
+> - [expressions](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions) : By writing a single mathematical expression once, users will be able to apply different types of
 > - [domains](kmath-core/src/commonMain/kotlin/space/kscience/kmath/domains) : Domains
-> - [autodif](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions/SimpleAutoDiff.kt) : Automatic differentiation
+> - [autodiff](kmath-core/src/commonMain/kotlin/space/kscience/kmath/expressions/SimpleAutoDiff.kt) : Automatic differentiation
+> - [Parallel linear algebra](kmath-core/#) : Parallel implementation for `LinearAlgebra`
 
-<hr/>
 
-* ### [kmath-coroutines](kmath-coroutines)
-> 
+### [kmath-coroutines](kmath-coroutines)
 >
 > **Maturity**: EXPERIMENTAL
-<hr/>
 
-* ### [kmath-dimensions](kmath-dimensions)
-> 
+### [kmath-dimensions](kmath-dimensions)
+> A proof of concept module for adding type-safe dimensions to structures
 >
 > **Maturity**: PROTOTYPE
-<hr/>
 
-* ### [kmath-ejml](kmath-ejml)
-> 
+### [kmath-ejml](kmath-ejml)
 >
 > **Maturity**: PROTOTYPE
 >
@@ -158,10 +119,9 @@ performance calculations to code generation.
 > - [ejml-matrix](kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlMatrix.kt) : Matrix implementation.
 > - [ejml-linear-space](kmath-ejml/src/main/kotlin/space/kscience/kmath/ejml/EjmlLinearSpace.kt) : LinearSpace implementations.
 
-<hr/>
 
-* ### [kmath-for-real](kmath-for-real)
-> Extension module that should be used to achieve numpy-like behavior. 
+### [kmath-for-real](kmath-for-real)
+> Extension module that should be used to achieve numpy-like behavior.
 All operations are specialized to work with `Double` numbers without declaring algebraic contexts.
 One can still use generic algebras though.
 >
@@ -172,10 +132,9 @@ One can still use generic algebras though.
 > - [DoubleMatrix](kmath-for-real/src/commonMain/kotlin/space/kscience/kmath/real/DoubleMatrix.kt) : Numpy-like operations for 2d real structures
 > - [grids](kmath-for-real/src/commonMain/kotlin/space/kscience/kmath/structures/grids.kt) : Uniform grid generators
 
-<hr/>
 
-* ### [kmath-functions](kmath-functions)
-> 
+### [kmath-functions](kmath-functions)
+> Functions, integration and interpolation
 >
 > **Maturity**: EXPERIMENTAL
 >
@@ -186,122 +145,99 @@ One can still use generic algebras though.
 > - [spline interpolation](kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt) : Cubic spline XY interpolator.
 > - [integration](kmath-functions/#) : Univariate and multivariate quadratures
 
-<hr/>
 
-* ### [kmath-geometry](kmath-geometry)
-> 
+### [kmath-geometry](kmath-geometry)
 >
 > **Maturity**: PROTOTYPE
-<hr/>
 
-* ### [kmath-histograms](kmath-histograms)
-> 
+### [kmath-histograms](kmath-histograms)
 >
 > **Maturity**: PROTOTYPE
-<hr/>
 
-* ### [kmath-jafama](kmath-jafama)
-> 
+### [kmath-jupyter](kmath-jupyter)
 >
 > **Maturity**: PROTOTYPE
->
-> **Features:**
-> - [jafama-double](kmath-jafama/src/main/kotlin/space/kscience/kmath/jafama/) : Double ExtendedField implementations based on Jafama
 
-<hr/>
-
-* ### [kmath-jupyter](kmath-jupyter)
-> 
->
-> **Maturity**: PROTOTYPE
-<hr/>
-
-* ### [kmath-kotlingrad](kmath-kotlingrad)
-> 
+### [kmath-kotlingrad](kmath-kotlingrad)
+> Kotlin∇ integration module
 >
 > **Maturity**: EXPERIMENTAL
 >
 > **Features:**
-> - [differentiable-mst-expression](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : MST based DifferentiableExpression.
-> - [differentiable-mst-expression](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/DifferentiableMstExpression.kt) : Conversions between Kotlin∇'s SFun and MST
+> - [differentiable-mst-expression](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/KotlingradExpression.kt) : MST based DifferentiableExpression.
+> - [scalars-adapters](kmath-kotlingrad/src/main/kotlin/space/kscience/kmath/kotlingrad/scalarsAdapters.kt) : Conversions between Kotlin∇'s SFun and MST
 
-<hr/>
 
-* ### [kmath-memory](kmath-memory)
+### [kmath-memory](kmath-memory)
 > An API and basic implementation for arranging objects in a continuous memory block.
 >
 > **Maturity**: DEVELOPMENT
-<hr/>
 
-* ### [kmath-nd4j](kmath-nd4j)
-> 
->
-> **Maturity**: EXPERIMENTAL
->
-> **Features:**
-> - [nd4jarraystructure](kmath-nd4j/#) : NDStructure wrapper for INDArray
-> - [nd4jarrayrings](kmath-nd4j/#) : Rings over Nd4jArrayStructure of Int and Long
-> - [nd4jarrayfields](kmath-nd4j/#) : Fields over Nd4jArrayStructure of Float and Double
-
-<hr/>
-
-* ### [kmath-stat](kmath-stat)
-> 
->
-> **Maturity**: EXPERIMENTAL
-<hr/>
-
-* ### [kmath-symja](kmath-symja)
-> 
+### [kmath-multik](kmath-multik)
+> JetBrains Multik connector
 >
 > **Maturity**: PROTOTYPE
-<hr/>
 
-* ### [kmath-tensors](kmath-tensors)
-> 
+### [kmath-ojalgo](kmath-ojalgo)
+> Ojalgo bindings for kmath
+>
+> **Maturity**: PROTOTYPE
+
+### [kmath-optimization](kmath-optimization)
+>
+> **Maturity**: EXPERIMENTAL
+
+### [kmath-stat](kmath-stat)
+>
+> **Maturity**: EXPERIMENTAL
+
+### [kmath-symja](kmath-symja)
+> Symja integration module
+>
+> **Maturity**: PROTOTYPE
+
+### [kmath-tensorflow](kmath-tensorflow)
+> Google tensorflow connector
+>
+> **Maturity**: PROTOTYPE
+
+### [kmath-tensors](kmath-tensors)
 >
 > **Maturity**: PROTOTYPE
 >
 > **Features:**
 > - [tensor algebra](kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/TensorAlgebra.kt) : Basic linear algebra operations on tensors (plus, dot, etc.)
-> - [tensor algebra with broadcasting](kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/core/algebras/BroadcastDoubleTensorAlgebra.kt) : Basic linear algebra operations implemented with broadcasting.
+> - [tensor algebra with broadcasting](kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/core/BroadcastDoubleTensorAlgebra.kt) : Basic linear algebra operations implemented with broadcasting.
 > - [linear algebra operations](kmath-tensors/src/commonMain/kotlin/space/kscience/kmath/tensors/api/LinearOpsTensorAlgebra.kt) : Advanced linear algebra operations like LU decomposition, SVD, etc.
 
-<hr/>
 
-* ### [kmath-viktor](kmath-viktor)
-> 
+### [kmath-viktor](kmath-viktor)
+> Binding for https://github.com/JetBrains-Research/viktor
 >
-> **Maturity**: DEVELOPMENT
-<hr/>
+> **Maturity**: DEPRECATED
+
+### [test-utils](test-utils)
+>
+> **Maturity**: EXPERIMENTAL
 
 
 ## Multi-platform support
 
-KMath is developed as a multi-platform library, which means that most of the interfaces are declared in the 
-[common source sets](/kmath-core/src/commonMain) and implemented there wherever it is possible. In some cases, features 
-are delegated to platform-specific implementations even if they could be provided in the common module for performance 
-reasons. Currently, the Kotlin/JVM is the primary platform, however Kotlin/Native and Kotlin/JS contributions and 
-feedback are also welcome.
+KMath is developed as a multi-platform library, which means that most of the interfaces are declared in common source sets like [common source sets](kmath-core/src/commonMain) and implemented there wherever it is possible. In some cases, features are delegated to platform-specific implementations even if they could be provided in the common module for performance reasons. Currently, Kotlin/JVM is the primary platform, however, Kotlin/Native, Kotlin/JS and Kotlin/Wasm contributions and feedback are also welcome.
 
 ## Performance
 
-Calculation performance is one of major goals of KMath in the future, but in some cases it is impossible to achieve 
-both performance and flexibility. 
+Performance of mathematical operations is hard to achieve without a lot of effort. KMath focus is to provide a reasonable performance for common cases, out of the box and good interoperability with optimized libraries for edge cases. For example, one could prototype an algorithm using KMath core implementations and then use Multik or Ojalgo for performance-critical parts just by adding a dependency and algebra context switch.
 
-We expect to focus on creating convenient universal API first and then work on increasing performance for specific 
-cases. We expect the worst KMath benchmarks will perform better than native Python, but worse than optimized 
-native/SciPy (mostly due to boxing operations on primitive numbers). The best performance of optimized parts could be 
-better than SciPy.
+As for core implementations, we expect to focus on creating a convenient universal API first and then work on increasing performance for specific cases. We expect the worst KMath benchmarks will perform better than native Python, but worse than optimized native/SciPy (mostly due to boxing operations on primitive numbers). The best performance of optimized parts could be better than SciPy.
 
 ## Requirements
 
-KMath currently relies on JDK 11 for compilation and execution of Kotlin-JVM part. We recommend to use GraalVM-CE 11 for execution in order to get better performance.
+KMath currently relies on JDK 21 for compilation and execution of Kotlin-JVM part. 
 
 ### Repositories
 
-Release and development artifacts are accessible from mipt-npm [Space](https://www.jetbrains.com/space/) repository `https://maven.pkg.jetbrains.space/mipt-npm/p/sci/maven` (see documentation of
-[Kotlin Multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html) for more details). The repository could be reached through [repo.kotlin.link](https://repo.kotlin.link) proxy:
+Intermediate releases are published to [Kotlin.Link](https://repo.kotlin.link) repository.
 
 ```kotlin
 repositories {
@@ -309,16 +245,7 @@ repositories {
 }
 
 dependencies {
-    api("space.kscience:kmath-core:0.3.0-dev-14")
-    // api("space.kscience:kmath-core-jvm:0.3.0-dev-14") for jvm-specific version
+    api("space.kscience:kmath-core:$version")
+    // api("space.kscience:kmath-core-jvm:$version") for jvm-specific version
 }
 ```
-
-Gradle `6.0+` is required for multiplatform artifacts.
-
-## Contributing
-
-The project requires a lot of additional work. The most important thing we need is a feedback about what features are 
-required the most. Feel free to create feature requests. We are also welcome to code contributions, 
-especially in issues marked with 
-[waiting for a hero](https://github.com/mipt-npm/kmath/labels/waiting%20for%20a%20hero) label.

benchmarks/README.md

@@ -0,0 +1,122 @@
+# Module KMath-Benchmarks
+
+# BenchmarksResult
+
+## Report for benchmark configuration <code>main</code>
+
+* Run on OpenJDK 64-Bit Server VM (build 21.0.9+10-LTS) with Java process:
+
+```
+C:\Users\altavir\.gradle\jdks\eclipse_adoptium-21-amd64-windows.2\bin\java.exe -Dfile.encoding=UTF-8 -Duser.country=US -Duser.language=en -Duser.variant
+```
+* JMH 1.37 was used in `thrpt` mode with 5 warmup iterations by 10 s and 5 measurement iterations by 10 s.
+### [ArrayBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ArrayBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`benchmarkArrayRead`|3.9E+06 &plusmn; 1.1E+06 ops/s|
+|`benchmarkBufferRead`|4.0E+06 &plusmn; 2.2E+05 ops/s|
+|`nativeBufferRead`|4.0E+06 &plusmn; 1.7E+05 ops/s|
+### [BigIntBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/BigIntBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`jvmAdd`|2.9E+07 &plusmn; 2.8E+06 ops/s|
+|`jvmAddLarge`|3.8E+04 &plusmn; 6.4E+03 ops/s|
+|`jvmMultiply`|5.3E+07 &plusmn; 6.1E+06 ops/s|
+|`jvmMultiplyLarge`|2.2E+02 &plusmn; 1.9 ops/s|
+|`jvmParsing10`|3.9E+06 &plusmn; 4.7E+05 ops/s|
+|`jvmParsing16`|3.1E+06 &plusmn; 4.6E+05 ops/s|
+|`jvmPower`|24 &plusmn; 1.7 ops/s|
+|`jvmSmallAdd`|4.7E+07 &plusmn; 4.6E+06 ops/s|
+|`kmAdd`|2.3E+07 &plusmn; 5.1E+06 ops/s|
+|`kmAddLarge`|2.6E+04 &plusmn; 3.0E+02 ops/s|
+|`kmMultiply`|3.7E+07 &plusmn; 2.9E+06 ops/s|
+|`kmMultiplyLarge`|34 &plusmn; 2.8 ops/s|
+|`kmParsing10`|2.5E+06 &plusmn; 1.5E+05 ops/s|
+|`kmParsing16`|4.0E+06 &plusmn; 2.4E+05 ops/s|
+|`kmPower`|6.5 &plusmn; 0.69 ops/s|
+|`kmSmallAdd`|1.6E+07 &plusmn; 8.0E+05 ops/s|
+### [BufferBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/BufferBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`bufferViewReadWrite`|5.4E+06 &plusmn; 3.8E+05 ops/s|
+|`bufferViewReadWriteSpecialized`|5.0E+06 &plusmn; 1.2E+06 ops/s|
+|`complexBufferReadWrite`|2.2E+06 &plusmn; 5.7E+04 ops/s|
+|`doubleArrayReadWrite`|6.9E+06 &plusmn; 1.2E+06 ops/s|
+|`doubleBufferReadWrite`|6.6E+06 &plusmn; 1.1E+06 ops/s|
+### [DotBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/DotBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`bufferedDot`|1.2 &plusmn; 0.20 ops/s|
+|`cmDot`|0.36 &plusmn; 0.14 ops/s|
+|`cmDotWithConversion`|0.80 &plusmn; 0.092 ops/s|
+|`ejmlDot`|2.9 &plusmn; 0.61 ops/s|
+|`ejmlDotWithConversion`|2.7 &plusmn; 0.15 ops/s|
+|`multikDot`|23 &plusmn; 2.4 ops/s|
+|`ojalgoDot`|11 &plusmn; 0.79 ops/s|
+|`parallelDot`|9.4 &plusmn; 1.3 ops/s|
+|`tensorDot`|1.0 &plusmn; 0.15 ops/s|
+|`tfDot`|3.9 &plusmn; 0.90 ops/s|
+### [ExpressionsInterpretersBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ExpressionsInterpretersBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`asmGenericExpression`|15 &plusmn; 1.8 ops/s|
+|`asmPrimitiveExpression`|27 &plusmn; 0.98 ops/s|
+|`asmPrimitiveExpressionArray`|78 &plusmn; 14 ops/s|
+|`functionalExpression`|4.4 &plusmn; 0.25 ops/s|
+|`justCalculate`|79 &plusmn; 5.4 ops/s|
+|`mstExpression`|4.2 &plusmn; 0.93 ops/s|
+|`rawExpression`|25 &plusmn; 5.0 ops/s|
+### [IntegrationBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/IntegrationBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`complexIntegration`|2.2E+03 &plusmn; 3.0E+02 ops/s|
+|`doubleIntegration`|2.3E+03 &plusmn; 6.4E+02 ops/s|
+### [MatrixInverseBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/MatrixInverseBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`cmLUPInversion`|2.0E+03 &plusmn; 1.1E+02 ops/s|
+|`ejmlInverse`|1.2E+03 &plusmn; 29 ops/s|
+|`kmathLupInversion`|3.9E+02 &plusmn; 92 ops/s|
+|`kmathParallelLupInversion`|55 &plusmn; 5.0 ops/s|
+|`ojalgoInverse`|1.7E+03 &plusmn; 35 ops/s|
+### [MinStatisticBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/MinStatisticBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`kotlinArrayMin`|1.6E+03 &plusmn; 3.0E+02 ops/s|
+|`minBlocking`|1.2E+03 &plusmn; 1.2E+02 ops/s|
+### [NDFieldBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/NDFieldBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`boxingFieldAdd`|1.9 &plusmn; 0.089 ops/s|
+|`multikAdd`|6.8 &plusmn; 1.0 ops/s|
+|`multikInPlaceAdd`|32 &plusmn; 4.7 ops/s|
+|`specializedFieldAdd`|6.7 &plusmn; 0.98 ops/s|
+|`tensorAdd`|7.9 &plusmn; 1.1 ops/s|
+|`tensorInPlaceAdd`|11 &plusmn; 3.4 ops/s|
+|`viktorAdd`|6.4 &plusmn; 0.41 ops/s|
+### [ViktorBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ViktorBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`doubleFieldAddition`|7.3 &plusmn; 1.1 ops/s|
+|`rawViktor`|6.0 &plusmn; 0.88 ops/s|
+|`viktorFieldAddition`|6.7 &plusmn; 0.47 ops/s|
+### [ViktorLogBenchmark](src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ViktorLogBenchmark.kt)
+
+| Benchmark | Score |
+|:---------:|:-----:|
+|`rawViktorLog`|1.3 &plusmn; 0.40 ops/s|
+|`realFieldLog`|1.2 &plusmn; 0.34 ops/s|
+|`viktorFieldLog`|1.3 &plusmn; 0.0073 ops/s|
+
+
+

benchmarks/build.gradle.kts

@@ -1,62 +1,83 @@
-@file:Suppress("UNUSED_VARIABLE")
 
-import space.kscience.kmath.benchmarks.addBenchmarkProperties
+
+import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import com.fasterxml.jackson.module.kotlin.readValue
+import kotlinx.benchmark.gradle.BenchmarksExtension
+import java.util.*
 
 plugins {
-    kotlin("multiplatform")
-    kotlin("plugin.allopen")
-    id("org.jetbrains.kotlinx.benchmark")
+    id("space.kscience.gradle.mpp")
+    alias(spclibs.plugins.kotlin.plugin.allopen)
+    alias(spclibs.plugins.kotlinx.benchmark)
 }
 
 allOpen.annotation("org.openjdk.jmh.annotations.State")
-sourceSets.register("benchmarks")
+//sourceSets.register("benchmarks")
 
 repositories {
     mavenCentral()
-    maven("https://repo.kotlin.link")
-    maven("https://clojars.org/repo")
-    maven("https://jitpack.io")
+}
 
-    maven("http://logicrunch.research.it.uu.se/maven") {
-        isAllowInsecureProtocol = true
+kscience {
+    maturity = space.kscience.gradle.Maturity.EXPERIMENTAL
+
+    jvm()
+
+    js {
+        nodejs()
+    }
+
+    commonMain{
+        implementation(project(":kmath-ast"))
+        implementation(project(":kmath-core"))
+        implementation(project(":kmath-coroutines"))
+        implementation(project(":kmath-complex"))
+        implementation(project(":kmath-stat"))
+        implementation(project(":kmath-dimensions"))
+        implementation(project(":kmath-for-real"))
+        implementation(project(":kmath-tensors"))
+        implementation(libs.multik.default)
+        implementation(spclibs.kotlinx.benchmark.runtime)
+    }
+
+    jvmMain {
+        implementation(projects.kmathCommons)
+        implementation(projects.kmathEjml)
+        implementation(projects.kmathKotlingrad)
+        implementation(projects.kmathViktor)
+        implementation(projects.kmathOjalgo)
+        implementation(projects.kmath.kmathTensorflow)
+        implementation(projects.kmathMultik)
+        implementation(libs.tensorflow.core.platform)
+//                implementation(projects.kmathNd4j)
+
+//                implementation(libs.nd4j.native.platform)
+        //    uncomment if your system supports AVX2
+        //    val os = System.getProperty("os.name")
+        //
+        //    if (System.getProperty("os.arch") in arrayOf("x86_64", "amd64")) when {
+        //        os.startsWith("Windows") -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:windows-x86_64-avx2")
+        //        os == "Linux" -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:linux-x86_64-avx2")
+        //        os == "Mac OS X" -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:macosx-x86_64-avx2")
+        //    } else
+        //    implementation("org.nd4j:nd4j-native-platform:1.0.0-beta7")
     }
 }
 
 kotlin {
-    jvm()
+    compilerOptions {
+        optIn.addAll(
+            "space.kscience.kmath.UnstableKMathAPI"
+        )
+    }
 
     sourceSets {
-        val commonMain by getting {
-            dependencies {
-                implementation(project(":kmath-ast"))
-                implementation(project(":kmath-core"))
-                implementation(project(":kmath-coroutines"))
-                implementation(project(":kmath-complex"))
-                implementation(project(":kmath-stat"))
-                implementation(project(":kmath-dimensions"))
-                implementation(project(":kmath-for-real"))
-                implementation(project(":kmath-jafama"))
-                implementation("org.jetbrains.kotlinx:kotlinx-benchmark-runtime:0.3.1")
-            }
-        }
-
-        val jvmMain by getting {
-            dependencies {
-                implementation(project(":kmath-commons"))
-                implementation(project(":kmath-ejml"))
-                implementation(project(":kmath-nd4j"))
-                implementation(project(":kmath-kotlingrad"))
-                implementation(project(":kmath-viktor"))
-                implementation("org.nd4j:nd4j-native:1.0.0-M1")
-                //    uncomment if your system supports AVX2
-                //    val os = System.getProperty("os.name")
-                //
-                //    if (System.getProperty("os.arch") in arrayOf("x86_64", "amd64")) when {
-                //        os.startsWith("Windows") -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:windows-x86_64-avx2")
-                //        os == "Linux" -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:linux-x86_64-avx2")
-                //        os == "Mac OS X" -> implementation("org.nd4j:nd4j-native:1.0.0-beta7:macosx-x86_64-avx2")
-                //    } else
-                //    implementation("org.nd4j:nd4j-native-platform:1.0.0-beta7")
+        all {
+            languageSettings {
+                progressiveMode = true
+                optIn("kotlin.contracts.ExperimentalContracts")
+                optIn("kotlin.ExperimentalUnsignedTypes")
+                optIn("space.kscience.kmath.UnstableKMathAPI")
             }
         }
     }
@@ -67,12 +88,13 @@ benchmark {
     // Setup configurations
     targets {
         register("jvm")
+        register("js")
     }
 
     fun kotlinx.benchmark.gradle.BenchmarkConfiguration.commonConfiguration() {
-        warmups = 1
+        warmups = 2
         iterations = 5
-        iterationTime = 1000
+        iterationTime = 2000
         iterationTimeUnit = "ms"
     }
 
@@ -81,13 +103,28 @@ benchmark {
         include("BufferBenchmark")
     }
 
+    configurations.register("minStatistic") {
+        commonConfiguration()
+        include("MinStatisticBenchmark")
+    }
+
+    configurations.register("nd") {
+        commonConfiguration()
+        include("NDFieldBenchmark")
+    }
+
     configurations.register("dot") {
         commonConfiguration()
         include("DotBenchmark")
     }
 
     configurations.register("expressions") {
-        commonConfiguration()
+        // Some extra precision
+        warmups = 2
+        iterations = 10
+        iterationTime = 10
+        iterationTimeUnit = "s"
+        outputTimeUnit = "s"
         include("ExpressionsInterpretersBenchmark")
     }
 
@@ -105,34 +142,144 @@ benchmark {
         commonConfiguration()
         include("JafamaBenchmark")
     }
-}
 
-// Fix kotlinx-benchmarks bug
-afterEvaluate {
-    val jvmBenchmarkJar by tasks.getting(org.gradle.jvm.tasks.Jar::class) {
-        duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+    configurations.register("tensorAlgebra") {
+        commonConfiguration()
+        include("TensorAlgebraBenchmark")
+    }
+
+    configurations.register("viktor") {
+        commonConfiguration()
+        include("ViktorBenchmark")
+    }
+
+    configurations.register("viktorLog") {
+        commonConfiguration()
+        include("ViktorLogBenchmark")
+    }
+
+    configurations.register("integration") {
+        commonConfiguration()
+        include("IntegrationBenchmark")
     }
 }
 
 
-kotlin.sourceSets.all {
-    with(languageSettings) {
-        useExperimentalAnnotation("kotlin.contracts.ExperimentalContracts")
-        useExperimentalAnnotation("kotlin.ExperimentalUnsignedTypes")
-        useExperimentalAnnotation("space.kscience.kmath.misc.UnstableKMathAPI")
+private data class JmhReport(
+    val jmhVersion: String,
+    val benchmark: String,
+    val mode: String,
+    val threads: Int,
+    val forks: Int,
+    val jvm: String,
+    val jvmArgs: List<String>,
+    val jdkVersion: String,
+    val vmName: String,
+    val vmVersion: String,
+    val warmupIterations: Int,
+    val warmupTime: String,
+    val warmupBatchSize: Int,
+    val measurementIterations: Int,
+    val measurementTime: String,
+    val measurementBatchSize: Int,
+    val params: Map<String, String> = emptyMap(),
+    val primaryMetric: PrimaryMetric,
+    val secondaryMetrics: Map<String, SecondaryMetric>,
+) {
+    interface Metric {
+        val score: Double
+        val scoreError: Double
+        val scoreConfidence: List<Double>
+        val scorePercentiles: Map<Double, Double>
+        val scoreUnit: String
     }
-}
 
-tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
-    kotlinOptions {
-        jvmTarget = "11"
-        freeCompilerArgs = freeCompilerArgs + "-Xjvm-default=all"
-    }
-}
+    data class PrimaryMetric(
+        override val score: Double,
+        override val scoreError: Double,
+        override val scoreConfidence: List<Double>,
+        override val scorePercentiles: Map<Double, Double>,
+        override val scoreUnit: String,
+        val rawDataHistogram: List<List<List<List<Double>>>>? = null,
+        val rawData: List<List<Double>>? = null,
+    ) : Metric
 
+    data class SecondaryMetric(
+        override val score: Double,
+        override val scoreError: Double,
+        override val scoreConfidence: List<Double>,
+        override val scorePercentiles: Map<Double, Double>,
+        override val scoreUnit: String,
+        val rawData: List<List<Double>>,
+    ) : Metric
+}
 
 readme {
-    maturity = ru.mipt.npm.gradle.Maturity.EXPERIMENTAL
+
+    val jsonMapper = jacksonObjectMapper()
+
+    fun noun(number: Number, singular: String, plural: String) = if (number.toLong() == 1L) singular else plural
+
+    extensions.findByType(BenchmarksExtension::class.java)?.configurations?.forEach { cfg ->
+        val propertyName =
+            "benchmark${cfg.name.replaceFirstChar { if (it.isLowerCase()) it.titlecase(Locale.getDefault()) else it.toString() }}"
+
+        logger.info("Processing benchmark data from benchmark ${cfg.name} into readme property $propertyName")
+
+        val launches = layout.buildDirectory.dir("reports/benchmarks/${cfg.name}").get().asFile
+        if (!launches.exists()) return@forEach
+
+        property(propertyName) {
+            val resDirectory = launches.listFiles()?.maxByOrNull {
+                it.nameWithoutExtension
+            }
+
+            if (resDirectory == null || !(resDirectory.resolve("jvm.json")).exists()) {
+                "> **Can't find appropriate benchmark data. Try generating readme files after running benchmarks**."
+            } else {
+                val reports: List<JmhReport> =
+                    jsonMapper.readValue<List<JmhReport>>(resDirectory.resolve("jvm.json"))
+
+                buildString {
+                    appendLine("## Report for benchmark configuration <code>${cfg.name}</code>")
+                    appendLine()
+                    val first = reports.first()
+
+                    appendLine("* Run on ${first.vmName} (build ${first.vmVersion}) with Java process:")
+                    appendLine()
+                    appendLine("```")
+                    appendLine(
+                        "${first.jvm} ${
+                            first.jvmArgs.joinToString(" ")
+                        }"
+                    )
+                    appendLine("```")
+
+                    appendLine(
+                        "* JMH ${first.jmhVersion} was used in `${first.mode}` mode with ${first.warmupIterations} warmup ${
+                            noun(first.warmupIterations, "iteration", "iterations")
+                        } by ${first.warmupTime} and ${first.measurementIterations} measurement ${
+                            noun(first.measurementIterations, "iteration", "iterations")
+                        } by ${first.measurementTime}."
+                    )
+
+                    reports.groupBy { it.benchmark.substringBeforeLast(".") }.forEach { (cl, compare) ->
+                        appendLine("### [${cl.substringAfterLast(".")}](src/jvmMain/kotlin/${cl.replace(".", "/")}.kt)")
+                        appendLine()
+                        appendLine("| Benchmark | Score |")
+                        appendLine("|:---------:|:-----:|")
+                        compare.forEach { report ->
+                            val benchmarkName = report.benchmark.substringAfterLast(".")
+                            val score = String.format("%.2G", report.primaryMetric.score)
+                            val error = String.format("%.2G", report.primaryMetric.scoreError)
+
+                            appendLine("|`$benchmarkName`|$score &plusmn; $error ${report.primaryMetric.scoreUnit}|")
+                        }
+                    }
+                }
+            }
+        }
+    }
 }
 
-addBenchmarkProperties()
+kotlin.explicitApi = org.jetbrains.kotlin.gradle.dsl.ExplicitApiMode.Disabled

benchmarks/docs/README-TEMPLATE.md

@@ -0,0 +1,7 @@
+# Module KMath-Benchmarks
+
+# BenchmarksResult
+
+${benchmarkMain}
+
+

benchmarks/src/jsMain/kotlin/space/kscience/kmath/benchmarks/ExpressionsInterpretersBenchmark.kt

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2018-2024 KMath contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package space.kscience.kmath.benchmarks
+
+import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Blackhole
+import kotlinx.benchmark.Scope
+import kotlinx.benchmark.State
+import space.kscience.kmath.UnstableKMathAPI
+import space.kscience.kmath.expressions.*
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.operations.bindSymbol
+import space.kscience.kmath.operations.invoke
+import space.kscience.kmath.structures.Float64
+import kotlin.math.sin
+import kotlin.random.Random
+import space.kscience.kmath.estree.compileToExpression as estreeCompileToExpression
+import space.kscience.kmath.wasm.compileToExpression as wasmCompileToExpression
+
+@State(Scope.Benchmark)
+class ExpressionsInterpretersBenchmark {
+    /**
+     * Benchmark case for [Expression] created with [expressionInExtendedField].
+     */
+    @Benchmark
+    fun functionalExpression(blackhole: Blackhole) = invokeAndSum(functional, blackhole)
+
+    /**
+     * Benchmark case for [Expression] created with [toExpression].
+     */
+    @Benchmark
+    fun mstExpression(blackhole: Blackhole) = invokeAndSum(mst, blackhole)
+
+    /**
+     * Benchmark case for [Expression] created with [space.kscience.kmath.estree.compileToExpression].
+     */
+    @Benchmark
+    fun wasmExpression(blackhole: Blackhole) = invokeAndSum(wasm, blackhole)
+
+    /**
+     * Benchmark case for [Expression] created with [space.kscience.kmath.estree.compileToExpression].
+     */
+    @Benchmark
+    fun estreeExpression(blackhole: Blackhole) = invokeAndSum(estree, blackhole)
+
+    /**
+     * Benchmark case for [Expression] implemented manually with `kotlin.math` functions.
+     */
+    @Benchmark
+    fun rawExpression(blackhole: Blackhole) = invokeAndSum(raw, blackhole)
+
+    /**
+     * Benchmark case for direct computation w/o [Expression].
+     */
+    @Benchmark
+    fun justCalculate(blackhole: Blackhole) {
+        val random = Random(0)
+        var sum = 0.0
+
+        repeat(times) {
+            val x = random.nextDouble()
+            sum += x * 2.0 + 2.0 / x - 16.0 / sin(x)
+        }
+
+        blackhole.consume(sum)
+    }
+
+    private fun invokeAndSum(expr: Expression<Float64>, blackhole: Blackhole) {
+        val random = Random(0)
+        var sum = 0.0
+        val m = HashMap<Symbol, Double>()
+
+        repeat(times) {
+            m[x] = random.nextDouble()
+            sum += expr(m)
+        }
+
+        blackhole.consume(sum)
+    }
+
+    private companion object {
+        private val x by symbol
+        private const val times = 1_000_000
+
+        private val functional = Float64Field.expression {
+            val x = bindSymbol(Symbol.x)
+            x * number(2.0) + 2.0 / x - 16.0 / sin(x)
+        }
+
+        private val node = MstExtendedField {
+            x * 2.0 + number(2.0) / x - number(16.0) / sin(x)
+        }
+
+        private val mst = node.toExpression(Float64Field)
+
+        @OptIn(UnstableKMathAPI::class)
+        private val wasm = node.wasmCompileToExpression(Float64Field)
+        private val estree = node.estreeCompileToExpression(Float64Field)
+
+        private val raw = Expression<Float64> { args ->
+            val x = args.getValue(x)
+            x * 2.0 + 2.0 / x - 16.0 / sin(x)
+        }
+    }
+}

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ArrayBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/BigIntBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -10,8 +10,11 @@ import kotlinx.benchmark.Blackhole
 import org.openjdk.jmh.annotations.Benchmark
 import org.openjdk.jmh.annotations.Scope
 import org.openjdk.jmh.annotations.State
-import space.kscience.kmath.misc.UnstableKMathAPI
-import space.kscience.kmath.operations.*
+import space.kscience.kmath.UnstableKMathAPI
+import space.kscience.kmath.operations.BigIntField
+import space.kscience.kmath.operations.JBigIntegerField
+import space.kscience.kmath.operations.invoke
+import space.kscience.kmath.operations.parseBigInteger
 import java.math.BigInteger
 
 
@@ -19,12 +22,24 @@ import java.math.BigInteger
 @State(Scope.Benchmark)
 internal class BigIntBenchmark {
 
+    val kmSmallNumber = BigIntField.number(100)
+    val jvmSmallNumber = JBigIntegerField.number(100)
     val kmNumber = BigIntField.number(Int.MAX_VALUE)
     val jvmNumber = JBigIntegerField.number(Int.MAX_VALUE)
-    val largeKmNumber = BigIntField { number(11).pow(100_000U) }
-    val largeJvmNumber: BigInteger = JBigIntegerField { number(11).pow(100_000) }
+    val kmLargeNumber = BigIntField { number(11).pow(100_000U) }
+    val jvmLargeNumber: BigInteger = JBigIntegerField { number(11).pow(100_000) }
     val bigExponent = 50_000
 
+    @Benchmark
+    fun kmSmallAdd(blackhole: Blackhole) = BigIntField {
+        blackhole.consume(kmSmallNumber + kmSmallNumber + kmSmallNumber)
+    }
+
+    @Benchmark
+    fun jvmSmallAdd(blackhole: Blackhole) = JBigIntegerField {
+        blackhole.consume(jvmSmallNumber + jvmSmallNumber + jvmSmallNumber)
+    }
+
     @Benchmark
     fun kmAdd(blackhole: Blackhole) = BigIntField {
         blackhole.consume(kmNumber + kmNumber + kmNumber)
@@ -37,12 +52,12 @@ internal class BigIntBenchmark {
 
     @Benchmark
     fun kmAddLarge(blackhole: Blackhole) = BigIntField {
-        blackhole.consume(largeKmNumber + largeKmNumber + largeKmNumber)
+        blackhole.consume(kmLargeNumber + kmLargeNumber + kmLargeNumber)
     }
 
     @Benchmark
     fun jvmAddLarge(blackhole: Blackhole) = JBigIntegerField {
-        blackhole.consume(largeJvmNumber + largeJvmNumber + largeJvmNumber)
+        blackhole.consume(jvmLargeNumber + jvmLargeNumber + jvmLargeNumber)
     }
 
     @Benchmark
@@ -52,7 +67,7 @@ internal class BigIntBenchmark {
 
     @Benchmark
     fun kmMultiplyLarge(blackhole: Blackhole) = BigIntField {
-        blackhole.consume(largeKmNumber*largeKmNumber)
+        blackhole.consume(kmLargeNumber * kmLargeNumber)
     }
 
     @Benchmark
@@ -62,7 +77,7 @@ internal class BigIntBenchmark {
 
     @Benchmark
     fun jvmMultiplyLarge(blackhole: Blackhole) = JBigIntegerField {
-        blackhole.consume(largeJvmNumber*largeJvmNumber)
+        blackhole.consume(jvmLargeNumber * jvmLargeNumber)
     }
 
     @Benchmark

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/BufferBenchmark.kt

@@ -1,39 +1,80 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
 package space.kscience.kmath.benchmarks
 
 import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Blackhole
 import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import space.kscience.kmath.complex.Complex
+import space.kscience.kmath.complex.ComplexField
 import space.kscience.kmath.complex.complex
-import space.kscience.kmath.structures.DoubleBuffer
-import space.kscience.kmath.structures.MutableBuffer
+import space.kscience.kmath.operations.invoke
+import space.kscience.kmath.structures.Buffer
+import space.kscience.kmath.structures.Float64Buffer
+import space.kscience.kmath.structures.getDouble
+import space.kscience.kmath.structures.permute
 
 @State(Scope.Benchmark)
 internal class BufferBenchmark {
-    @Benchmark
-    fun genericDoubleBufferReadWrite() {
-        val buffer = DoubleBuffer(size) { it.toDouble() }
 
+    @Benchmark
+    fun doubleArrayReadWrite(blackhole: Blackhole) {
+        val buffer = DoubleArray(size) { it.toDouble() }
+        var res = 0.0
         (0 until size).forEach {
-            buffer[it]
+            res += buffer[it]
         }
+        blackhole.consume(res)
     }
 
     @Benchmark
-    fun complexBufferReadWrite() {
-        val buffer = MutableBuffer.complex(size / 2) { Complex(it.toDouble(), -it.toDouble()) }
-
-        (0 until size / 2).forEach {
-            buffer[it]
+    fun doubleBufferReadWrite(blackhole: Blackhole) {
+        val buffer = Float64Buffer(size) { it.toDouble() }
+        var res = 0.0
+        (0 until size).forEach {
+            res += buffer[it]
         }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun bufferViewReadWrite(blackhole: Blackhole) {
+        val buffer = Float64Buffer(size) { it.toDouble() }.permute(reversedIndices)
+        var res = 0.0
+        (0 until size).forEach {
+            res += buffer[it]
+        }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun bufferViewReadWriteSpecialized(blackhole: Blackhole) {
+        val buffer = Float64Buffer(size) { it.toDouble() }.permute(reversedIndices)
+        var res = 0.0
+        (0 until size).forEach {
+            res += buffer.getDouble(it)
+        }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun complexBufferReadWrite(blackhole: Blackhole) = ComplexField {
+        val buffer = Buffer.complex(size / 2) { Complex(it.toDouble(), -it.toDouble()) }
+
+        var res = zero
+        (0 until size / 2).forEach {
+            res += buffer[it]
+        }
+
+        blackhole.consume(res)
     }
 
     private companion object {
         private const val size = 100
+        private val reversedIndices = IntArray(size) { it }.apply { reverse() }
     }
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/DotBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -11,9 +11,14 @@ import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import space.kscience.kmath.commons.linear.CMLinearSpace
 import space.kscience.kmath.ejml.EjmlLinearSpaceDDRM
-import space.kscience.kmath.linear.LinearSpace
+import space.kscience.kmath.linear.Float64ParallelLinearSpace
 import space.kscience.kmath.linear.invoke
-import space.kscience.kmath.operations.DoubleField
+import space.kscience.kmath.linear.linearSpace
+import space.kscience.kmath.ojalgo.Ojalgo
+import space.kscience.kmath.ojalgo.linearSpace
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.tensorflow.produceWithTF
+import space.kscience.kmath.tensors.core.tensorAlgebra
 import kotlin.random.Random
 
 @State(Scope.Benchmark)
@@ -23,8 +28,12 @@ internal class DotBenchmark {
         const val dim = 1000
 
         //creating invertible matrix
-        val matrix1 = LinearSpace.real.buildMatrix(dim, dim) { i, j -> if (i <= j) random.nextDouble() else 0.0 }
-        val matrix2 = LinearSpace.real.buildMatrix(dim, dim) { i, j -> if (i <= j) random.nextDouble() else 0.0 }
+        val matrix1 = Float64Field.linearSpace.buildMatrix(dim, dim) { _, _ ->
+            random.nextDouble()
+        }
+        val matrix2 = Float64Field.linearSpace.buildMatrix(dim, dim) { _, _ ->
+            random.nextDouble()
+        }
 
         val cmMatrix1 = CMLinearSpace { matrix1.toCM() }
         val cmMatrix2 = CMLinearSpace { matrix2.toCM() }
@@ -33,38 +42,59 @@ internal class DotBenchmark {
         val ejmlMatrix2 = EjmlLinearSpaceDDRM { matrix2.toEjml() }
     }
 
+
     @Benchmark
-    fun cmDot(blackhole: Blackhole) {
-        CMLinearSpace.run {
-            blackhole.consume(cmMatrix1 dot cmMatrix2)
-        }
+    fun tfDot(blackhole: Blackhole) {
+        blackhole.consume(
+            Float64Field.produceWithTF {
+                matrix1 dot matrix1
+            }
+        )
     }
 
     @Benchmark
-    fun ejmlDot(blackhole: Blackhole) {
-        EjmlLinearSpaceDDRM {
-            blackhole.consume(ejmlMatrix1 dot ejmlMatrix2)
-        }
+    fun cmDotWithConversion(blackhole: Blackhole) = CMLinearSpace {
+        blackhole.consume(matrix1 dot matrix2)
     }
 
     @Benchmark
-    fun ejmlDotWithConversion(blackhole: Blackhole) {
-        EjmlLinearSpaceDDRM {
-            blackhole.consume(matrix1 dot matrix2)
-        }
+    fun cmDot(blackhole: Blackhole): Unit = CMLinearSpace {
+        blackhole.consume(cmMatrix1.asMatrix() dot cmMatrix2.asMatrix())
     }
 
     @Benchmark
-    fun bufferedDot(blackhole: Blackhole) {
-        LinearSpace.auto(DoubleField).invoke {
-            blackhole.consume(matrix1 dot matrix2)
-        }
+    fun ejmlDot(blackhole: Blackhole): Unit = EjmlLinearSpaceDDRM {
+        blackhole.consume(ejmlMatrix1.asMatrix() dot ejmlMatrix2.asMatrix())
     }
 
     @Benchmark
-    fun realDot(blackhole: Blackhole) {
-        LinearSpace.real {
-            blackhole.consume(matrix1 dot matrix2)
-        }
+    fun ejmlDotWithConversion(blackhole: Blackhole) = EjmlLinearSpaceDDRM {
+        blackhole.consume(matrix1 dot matrix2)
     }
+
+    @Benchmark
+    fun ojalgoDot(blackhole: Blackhole) = Ojalgo.R064.linearSpace {
+        blackhole.consume(matrix1 dot matrix2)
+    }
+
+    @Benchmark
+    fun multikDot(blackhole: Blackhole) = with(multikAlgebra) {
+        blackhole.consume(matrix1 dot matrix2)
+    }
+
+    @Benchmark
+    fun tensorDot(blackhole: Blackhole) = with(Float64Field.tensorAlgebra) {
+        blackhole.consume(matrix1 dot matrix2)
+    }
+
+    @Benchmark
+    fun bufferedDot(blackhole: Blackhole) = with(Float64Field.linearSpace) {
+        blackhole.consume(matrix1 dot matrix2)
+    }
+
+    @Benchmark
+    fun parallelDot(blackhole: Blackhole) = with(Float64ParallelLinearSpace) {
+        blackhole.consume(matrix1 dot matrix2)
+    }
+
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ExpressionsInterpretersBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -11,9 +11,11 @@ import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import space.kscience.kmath.asm.compileToExpression
 import space.kscience.kmath.expressions.*
-import space.kscience.kmath.operations.DoubleField
+import space.kscience.kmath.operations.Algebra
+import space.kscience.kmath.operations.Float64Field
 import space.kscience.kmath.operations.bindSymbol
 import space.kscience.kmath.operations.invoke
+import space.kscience.kmath.structures.Float64
 import kotlin.math.sin
 import kotlin.random.Random
 
@@ -35,7 +37,30 @@ internal class ExpressionsInterpretersBenchmark {
      * Benchmark case for [Expression] created with [compileToExpression].
      */
     @Benchmark
-    fun asmExpression(blackhole: Blackhole) = invokeAndSum(asm, blackhole)
+    fun asmGenericExpression(blackhole: Blackhole) = invokeAndSum(asmGeneric, blackhole)
+
+    /**
+     * Benchmark case for [Expression] created with [compileToExpression].
+     */
+    @Benchmark
+    fun asmPrimitiveExpressionArray(blackhole: Blackhole) {
+        val random = Random(0)
+        var sum = 0.0
+        val m = DoubleArray(1)
+
+        repeat(times) {
+            m[xIdx] = random.nextDouble()
+            sum += asmPrimitive(m)
+        }
+
+        blackhole.consume(sum)
+    }
+
+    /**
+     * Benchmark case for [Expression] created with [compileToExpression].
+     */
+    @Benchmark
+    fun asmPrimitiveExpression(blackhole: Blackhole) = invokeAndSum(asmPrimitive, blackhole)
 
     /**
      * Benchmark case for [Expression] implemented manually with `kotlin.math` functions.
@@ -59,12 +84,14 @@ internal class ExpressionsInterpretersBenchmark {
         blackhole.consume(sum)
     }
 
-    private fun invokeAndSum(expr: Expression<Double>, blackhole: Blackhole) {
+    private fun invokeAndSum(expr: Expression<Float64>, blackhole: Blackhole) {
         val random = Random(0)
         var sum = 0.0
+        val m = HashMap<Symbol, Double>()
 
         repeat(times) {
-            sum += expr(x to random.nextDouble())
+            m[x] = random.nextDouble()
+            sum += expr(m)
         }
 
         blackhole.consume(sum)
@@ -72,21 +99,25 @@ internal class ExpressionsInterpretersBenchmark {
 
     private companion object {
         private val x by symbol
-        private val algebra = DoubleField
         private const val times = 1_000_000
 
-        private val functional = DoubleField.expressionInExtendedField {
-            bindSymbol(x) * number(2.0) + number(2.0) / bindSymbol(x) - number(16.0) / sin(bindSymbol(x))
+        private val functional = Float64Field.expression {
+            val x = bindSymbol(Symbol.x)
+            x * number(2.0) + 2.0 / x - 16.0 / sin(x)
         }
 
         private val node = MstExtendedField {
             x * 2.0 + number(2.0) / x - number(16.0) / sin(x)
         }
 
-        private val mst = node.toExpression(DoubleField)
-        private val asm = node.compileToExpression(DoubleField)
+        private val mst = node.toExpression(Float64Field)
 
-        private val raw = Expression<Double> { args ->
+        private val asmPrimitive = node.compileToExpression(Float64Field)
+        private val xIdx = asmPrimitive.indexer.indexOf(x)
+
+        private val asmGeneric = node.compileToExpression(Float64Field as Algebra<Float64>)
+
+        private val raw = Expression<Float64> { args ->
             val x = args[x]!!
             x * 2.0 + 2.0 / x - 16.0 / sin(x)
         }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/IntegrationBenchmark.kt

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2018-2024 KMath contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package space.kscience.kmath.benchmarks
+
+import org.openjdk.jmh.annotations.Benchmark
+import org.openjdk.jmh.annotations.Scope
+import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.infra.Blackhole
+import space.kscience.kmath.complex.Complex
+import space.kscience.kmath.complex.algebra
+import space.kscience.kmath.integration.gaussIntegrator
+import space.kscience.kmath.integration.integrate
+import space.kscience.kmath.integration.value
+import space.kscience.kmath.operations.algebra
+
+
+@State(Scope.Benchmark)
+internal class IntegrationBenchmark {
+
+    @Benchmark
+    fun doubleIntegration(blackhole: Blackhole) {
+        val res = Double.algebra.gaussIntegrator.integrate(0.0..1.0, intervals = 1000) { x: Double ->
+            //sin(1 / x)
+            1 / x
+        }.value
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun complexIntegration(blackhole: Blackhole) = with(Complex.algebra) {
+        val res = gaussIntegrator.integrate(0.0..1.0, intervals = 1000) { x: Double ->
+//            sin(1 / x) + i * cos(1 / x)
+            1 / x - i / x
+        }.value
+        blackhole.consume(res)
+    }
+}

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/JafamaBenchmark.kt

@@ -1,39 +0,0 @@
-/*
- * Copyright 2018-2021 KMath contributors.
- * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
- */
-
-package space.kscience.kmath.benchmarks
-
-import kotlinx.benchmark.Blackhole
-import org.openjdk.jmh.annotations.Benchmark
-import org.openjdk.jmh.annotations.Scope
-import org.openjdk.jmh.annotations.State
-import space.kscience.kmath.jafama.JafamaDoubleField
-import space.kscience.kmath.jafama.StrictJafamaDoubleField
-import space.kscience.kmath.operations.DoubleField
-import space.kscience.kmath.operations.invoke
-import kotlin.random.Random
-
-@State(Scope.Benchmark)
-internal class JafamaBenchmark {
-    @Benchmark
-    fun jafama(blackhole: Blackhole) = invokeBenchmarks(blackhole) { x ->
-        JafamaDoubleField { x * power(x, 4) * exp(x) / cos(x) + sin(x) }
-    }
-
-    @Benchmark
-    fun core(blackhole: Blackhole) = invokeBenchmarks(blackhole) { x ->
-        DoubleField { x * power(x, 4) * exp(x) / cos(x) + sin(x) }
-    }
-
-    @Benchmark
-    fun strictJafama(blackhole: Blackhole) = invokeBenchmarks(blackhole) { x ->
-        StrictJafamaDoubleField { x * power(x, 4) * exp(x) / cos(x) + sin(x) }
-    }
-
-    private inline fun invokeBenchmarks(blackhole: Blackhole, expr: (Double) -> Double) {
-        val rng = Random(0)
-        repeat(1000000) { blackhole.consume(expr(rng.nextDouble())) }
-    }
-}

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/MatrixInverseBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -10,13 +10,12 @@ import kotlinx.benchmark.Blackhole
 import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import space.kscience.kmath.commons.linear.CMLinearSpace
-import space.kscience.kmath.commons.linear.inverse
+import space.kscience.kmath.commons.linear.lupSolver
 import space.kscience.kmath.ejml.EjmlLinearSpaceDDRM
-import space.kscience.kmath.linear.InverseMatrixFeature
-import space.kscience.kmath.linear.LinearSpace
-import space.kscience.kmath.linear.inverseWithLup
-import space.kscience.kmath.linear.invoke
-import space.kscience.kmath.nd.getFeature
+import space.kscience.kmath.linear.*
+import space.kscience.kmath.ojalgo.Ojalgo
+import space.kscience.kmath.ojalgo.linearSpace
+import space.kscience.kmath.operations.algebra
 import kotlin.random.Random
 
 @State(Scope.Benchmark)
@@ -25,7 +24,7 @@ internal class MatrixInverseBenchmark {
         private val random = Random(1224)
         private const val dim = 100
 
-        private val space = LinearSpace.real
+        private val space = Double.algebra.linearSpace
 
         //creating invertible matrix
         private val u = space.buildMatrix(dim, dim) { i, j -> if (i <= j) random.nextDouble() else 0.0 }
@@ -35,20 +34,27 @@ internal class MatrixInverseBenchmark {
 
     @Benchmark
     fun kmathLupInversion(blackhole: Blackhole) {
-        blackhole.consume(LinearSpace.real.inverseWithLup(matrix))
+        blackhole.consume(Double.algebra.linearSpace.lupSolver().inverse(matrix))
     }
 
     @Benchmark
-    fun cmLUPInversion(blackhole: Blackhole) {
-        with(CMLinearSpace) {
-            blackhole.consume(inverse(matrix))
-        }
+    fun kmathParallelLupInversion(blackhole: Blackhole) {
+        blackhole.consume(Double.algebra.linearSpace.parallel.lupSolver().inverse(matrix))
     }
 
     @Benchmark
-    fun ejmlInverse(blackhole: Blackhole) {
-        with(EjmlLinearSpaceDDRM) {
-            blackhole.consume(matrix.getFeature<InverseMatrixFeature<Double>>()?.inverse)
-        }
+    fun cmLUPInversion(blackhole: Blackhole) = CMLinearSpace {
+        blackhole.consume(lupSolver().inverse(matrix))
     }
+
+    @Benchmark
+    fun ejmlInverse(blackhole: Blackhole) = EjmlLinearSpaceDDRM {
+        blackhole.consume(matrix.inverted())
+    }
+
+    @Benchmark
+    fun ojalgoInverse(blackhole: Blackhole) = Ojalgo.R064.linearSpace {
+        blackhole.consume(matrix.getOrComputeAttribute(Inverted))
+    }
+
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/MinStatisticBenchmark.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2018-2025 KMath contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package space.kscience.kmath.benchmarks
+
+import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Blackhole
+import kotlinx.benchmark.Scope
+import kotlinx.benchmark.State
+import kotlinx.coroutines.runBlocking
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.stat.min
+import space.kscience.kmath.structures.*
+
+@State(Scope.Benchmark)
+internal class MinStatisticBenchmark {
+
+    @Benchmark
+    fun kotlinArrayMin(blackhole: Blackhole) {
+        val array = DoubleArray(size) { it.toDouble() }
+        var res = 0.0
+        (0 until size).forEach {
+            res += array.min()
+        }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun minBlocking(blackhole: Blackhole) {
+        val buffer = Float64Buffer(size) { it.toDouble() }
+        var res = 0.0
+        (0 until size).forEach {
+            res += Float64Field.min.evaluateBlocking(buffer)
+        }
+        blackhole.consume(res)
+    }
+
+
+    private companion object {
+        private const val size = 1000
+    }
+}

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/NDFieldBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -9,45 +9,87 @@ import kotlinx.benchmark.Benchmark
 import kotlinx.benchmark.Blackhole
 import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
+import org.jetbrains.kotlinx.multik.api.Multik
+import org.jetbrains.kotlinx.multik.api.ones
+import org.jetbrains.kotlinx.multik.ndarray.data.DN
+import org.jetbrains.kotlinx.multik.ndarray.data.DataType
+import space.kscience.kmath.UnsafeKMathAPI
 import space.kscience.kmath.nd.*
-import space.kscience.kmath.operations.DoubleField
-import space.kscience.kmath.structures.Buffer
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.structures.Float64
+import space.kscience.kmath.tensors.core.DoubleTensor
+import space.kscience.kmath.tensors.core.one
+import space.kscience.kmath.tensors.core.tensorAlgebra
+import space.kscience.kmath.viktor.viktorAlgebra
 
 @State(Scope.Benchmark)
 internal class NDFieldBenchmark {
-    @Benchmark
-    fun autoFieldAdd(blackhole: Blackhole) {
-        with(autoField) {
-            var res: StructureND<Double> = one
-            repeat(n) { res += one }
-            blackhole.consume(res)
-        }
-    }
-
-    @Benchmark
-    fun specializedFieldAdd(blackhole: Blackhole) {
-        with(specializedField) {
-            var res: StructureND<Double> = one
-            repeat(n) { res += 1.0 }
-            blackhole.consume(res)
-        }
-    }
-
-
-    @Benchmark
-    fun boxingFieldAdd(blackhole: Blackhole) {
-        with(genericField) {
-            var res: StructureND<Double> = one
-            repeat(n) { res += 1.0 }
-            blackhole.consume(res)
-        }
-    }
 
     private companion object {
         private const val dim = 1000
         private const val n = 100
-        private val autoField = AlgebraND.auto(DoubleField, dim, dim)
-        private val specializedField = AlgebraND.real(dim, dim)
-        private val genericField = AlgebraND.field(DoubleField, Buffer.Companion::boxing, dim, dim)
+        private val shape = ShapeND(dim, dim)
+        private val specializedField = Float64Field.ndAlgebra
+        private val genericField = BufferedFieldOpsND(Float64Field)
+        private val viktorField = Float64Field.viktorAlgebra
     }
+
+    @Benchmark
+    fun specializedFieldAdd(blackhole: Blackhole) = with(specializedField) {
+        var res: StructureND<Float64> = one(shape)
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun boxingFieldAdd(blackhole: Blackhole) = with(genericField) {
+        var res: StructureND<Float64> = one(shape)
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun multikAdd(blackhole: Blackhole) = with(multikAlgebra) {
+        var res: StructureND<Float64> = one(shape)
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun viktorAdd(blackhole: Blackhole) = with(viktorField) {
+        var res: StructureND<Float64> = one(shape)
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun tensorAdd(blackhole: Blackhole) = with(Double.tensorAlgebra) {
+        var res: DoubleTensor = one(shape)
+        repeat(n) { res = res + 1.0 }
+        blackhole.consume(res)
+    }
+
+    @Benchmark
+    fun tensorInPlaceAdd(blackhole: Blackhole) = with(Double.tensorAlgebra) {
+        val res: DoubleTensor = one(shape)
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+    @OptIn(UnsafeKMathAPI::class)
+    @Benchmark
+    fun multikInPlaceAdd(blackhole: Blackhole) = with(multikAlgebra) {
+        val res = Multik.ones<Double, DN>(shape.asArray(), DataType.DoubleDataType).wrap()
+        repeat(n) { res += 1.0 }
+        blackhole.consume(res)
+    }
+
+//    @Benchmark
+//    fun nd4jAdd(blackhole: Blackhole) = with(nd4jField) {
+//        var res: StructureND<Float64> = one(dim, dim)
+//        repeat(n) { res += 1.0 }
+//        blackhole.consume(res)
+//    }
+
+
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/TensorAlgebraBenchmark.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2018-2024 KMath contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package space.kscience.kmath.benchmarks
+
+import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Blackhole
+import kotlinx.benchmark.Scope
+import kotlinx.benchmark.State
+import space.kscience.kmath.linear.MatrixBuilder
+import space.kscience.kmath.linear.linearSpace
+import space.kscience.kmath.linear.symmetric
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.tensors.core.symEigJacobi
+import space.kscience.kmath.tensors.core.symEigSvd
+import space.kscience.kmath.tensors.core.tensorAlgebra
+import kotlin.random.Random
+
+@State(Scope.Benchmark)
+internal class TensorAlgebraBenchmark {
+    companion object {
+        private val random = Random(12224)
+        private const val dim = 30
+
+        private val matrix = Float64Field.linearSpace.MatrixBuilder(dim, dim).symmetric { _, _ -> random.nextDouble() }
+    }
+
+    @Benchmark
+    fun tensorSymEigSvd(blackhole: Blackhole) = with(Double.tensorAlgebra) {
+        blackhole.consume(symEigSvd(matrix, 1e-10))
+    }
+
+    @Benchmark
+    fun tensorSymEigJacobi(blackhole: Blackhole) = with(Double.tensorAlgebra) {
+        blackhole.consume(symEigJacobi(matrix, 50, 1e-10))
+    }
+}

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ViktorBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -10,28 +10,21 @@ import kotlinx.benchmark.Blackhole
 import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import org.jetbrains.bio.viktor.F64Array
-import space.kscience.kmath.nd.AlgebraND
+import space.kscience.kmath.nd.ShapeND
 import space.kscience.kmath.nd.StructureND
-import space.kscience.kmath.nd.auto
-import space.kscience.kmath.nd.real
-import space.kscience.kmath.operations.DoubleField
-import space.kscience.kmath.viktor.ViktorNDField
+import space.kscience.kmath.nd.ndAlgebra
+import space.kscience.kmath.nd.one
+import space.kscience.kmath.operations.Float64Field
+import space.kscience.kmath.structures.Float64
+import space.kscience.kmath.viktor.ViktorFieldND
 
 @State(Scope.Benchmark)
 internal class ViktorBenchmark {
-    @Benchmark
-    fun automaticFieldAddition(blackhole: Blackhole) {
-        with(autoField) {
-            var res: StructureND<Double> = one
-            repeat(n) { res += 1.0 }
-            blackhole.consume(res)
-        }
-    }
 
     @Benchmark
-    fun realFieldAddition(blackhole: Blackhole) {
-        with(realField) {
-            var res: StructureND<Double> = one
+    fun doubleFieldAddition(blackhole: Blackhole) {
+        with(doubleField) {
+            var res: StructureND<Float64> = one(shape)
             repeat(n) { res += 1.0 }
             blackhole.consume(res)
         }
@@ -40,7 +33,7 @@ internal class ViktorBenchmark {
     @Benchmark
     fun viktorFieldAddition(blackhole: Blackhole) {
         with(viktorField) {
-            var res = one
+            var res = one(shape)
             repeat(n) { res += 1.0 }
             blackhole.consume(res)
         }
@@ -57,10 +50,10 @@ internal class ViktorBenchmark {
     private companion object {
         private const val dim = 1000
         private const val n = 100
+        private val shape = ShapeND(dim, dim)
 
         // automatically build context most suited for given type.
-        private val autoField = AlgebraND.auto(DoubleField, dim, dim)
-        private val realField = AlgebraND.real(dim, dim)
-        private val viktorField = ViktorNDField(dim, dim)
+        private val doubleField = Float64Field.ndAlgebra
+        private val viktorField = ViktorFieldND(dim, dim)
     }
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/ViktorLogBenchmark.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018-2021 KMath contributors.
+ * Copyright 2018-2024 KMath contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -10,19 +10,19 @@ import kotlinx.benchmark.Blackhole
 import kotlinx.benchmark.Scope
 import kotlinx.benchmark.State
 import org.jetbrains.bio.viktor.F64Array
-import space.kscience.kmath.nd.AlgebraND
-import space.kscience.kmath.nd.auto
-import space.kscience.kmath.nd.real
-import space.kscience.kmath.operations.DoubleField
+import space.kscience.kmath.nd.ShapeND
+import space.kscience.kmath.nd.ndAlgebra
+import space.kscience.kmath.nd.one
+import space.kscience.kmath.operations.Float64Field
 import space.kscience.kmath.viktor.ViktorFieldND
 
 @State(Scope.Benchmark)
 internal class ViktorLogBenchmark {
     @Benchmark
     fun realFieldLog(blackhole: Blackhole) {
-        with(realNdField) {
-            val fortyTwo = produce { 42.0 }
-            var res = one
+        with(doubleField) {
+            val fortyTwo = structureND(shape) { 42.0 }
+            var res = one(shape)
             repeat(n) { res = ln(fortyTwo) }
             blackhole.consume(res)
         }
@@ -31,7 +31,7 @@ internal class ViktorLogBenchmark {
     @Benchmark
     fun viktorFieldLog(blackhole: Blackhole) {
         with(viktorField) {
-            val fortyTwo = produce { 42.0 }
+            val fortyTwo = structureND(shape) { 42.0 }
             var res = one
             repeat(n) { res = ln(fortyTwo) }
             blackhole.consume(res)
@@ -49,10 +49,10 @@ internal class ViktorLogBenchmark {
     private companion object {
         private const val dim = 1000
         private const val n = 100
+        private val shape = ShapeND(dim, dim)
 
         // automatically build context most suited for given type.
-        private val autoField = AlgebraND.auto(DoubleField, dim, dim)
-        private val realNdField = AlgebraND.real(dim, dim)
-        private val viktorField = ViktorFieldND(intArrayOf(dim, dim))
+        private val doubleField = Float64Field.ndAlgebra
+        private val viktorField = ViktorFieldND(dim, dim)
     }
 }

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/globals.kt

@@ -0,0 +1,11 @@
+/*
+ * Copyright 2018-2024 KMath contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package space.kscience.kmath.benchmarks
+
+import org.jetbrains.kotlinx.multik.default.DefaultEngine
+import space.kscience.kmath.multik.MultikDoubleAlgebra
+
+val multikAlgebra = MultikDoubleAlgebra(DefaultEngine())

build.gradle.kts

@@ -1,58 +1,102 @@
+import org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation
+import space.kscience.gradle.useApache2Licence
+import space.kscience.gradle.useSPCTeam
+
 plugins {
-    id("ru.mipt.npm.gradle.project")
-    kotlin("jupyter.api") apply false
+    alias(spclibs.plugins.kscience.project)
+    alias(spclibs.plugins.kotlinx.kover)
 }
 
 allprojects {
     repositories {
-        maven("https://clojars.org/repo")
-        maven("https://jitpack.io")
-        maven("http://logicrunch.research.it.uu.se/maven") {
-            isAllowInsecureProtocol = true
-        }
+        maven("https://repo.kotlin.link")
         maven("https://oss.sonatype.org/content/repositories/snapshots")
         mavenCentral()
     }
 
     group = "space.kscience"
-    version = "0.3.0-dev-14"
+    version = "0.5.0"
+}
+
+dependencies {
+    subprojects.forEach {
+        dokka(it)
+    }
+}
+
+dokka {
+    dokkaSourceSets.configureEach {
+        val readmeFile = projectDir.resolve("README.md")
+        if (readmeFile.exists()) includes.from(readmeFile)
+    }
 }
 
 subprojects {
     if (name.startsWith("kmath")) apply<MavenPublishPlugin>()
 
-    afterEvaluate {
-        tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial> {
-            dependsOn(tasks.getByName("assemble"))
+    plugins.withId("org.jetbrains.dokka") {
+        dokka {
+            dokkaSourceSets.configureEach {
+                val readmeFile = projectDir.resolve("README.md")
+                if (readmeFile.exists()) includes.from(readmeFile)
+                val kotlinDirPath = "src/$name/kotlin"
+                val kotlinDir = file(kotlinDirPath)
+
+                if (kotlinDir.exists()) sourceLink {
+                    localDirectory.set(kotlinDir)
+                    remoteUrl(
+                        "https://github.com/SciProgCentre/kmath/tree/master/${name}/$kotlinDirPath"
+                    )
+                }
+
+                fun externalDocumentationLink(url: String, packageListUrl: String? = null) {
+                    externalDocumentationLinks.register(url) {
+                        url(url)
+                        packageListUrl?.let {
+                            packageListUrl(it)
+                        }
+                    }
+                }
 
-            dokkaSourceSets.all {
-                val readmeFile = File(this@subprojects.projectDir, "README.md")
-                if (readmeFile.exists()) includes.from(readmeFile.absolutePath)
-                externalDocumentationLink("https://ejml.org/javadoc/")
                 externalDocumentationLink("https://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/")
                 externalDocumentationLink("https://deeplearning4j.org/api/latest/")
                 externalDocumentationLink("https://axelclk.bitbucket.io/symja/javadoc/")
-                externalDocumentationLink("https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/")
 
                 externalDocumentationLink(
-                    "https://breandan.net/kotlingrad/kotlingrad/",
-                    "https://breandan.net/kotlingrad/kotlingrad/kotlingrad/package-list",
+                    "https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/",
+                    "https://kotlin.github.io/kotlinx.coroutines/package-list",
                 )
+
+                externalDocumentationLink(
+                    "https://breandan.net/kotlingrad/kotlingrad",
+                    "https://breandan.net/kotlingrad/package-list",
+                )
+            }
+        }
+
+    }
+}
+
+kscienceProject {
+    readme.readmeTemplate = file("docs/templates/README-TEMPLATE.md")
+
+
+    pom("https://github.com/SciProgCentre/kmath") {
+        useApache2Licence()
+        useSPCTeam()
+    }
+    publishTo("spc", "https://maven.sciprog.center/kscience")
+    publishToCentral()
+
+    @OptIn(ExperimentalAbiValidation::class)
+    abiValidation {
+        filters {
+            excluded {
+                annotatedWith.add("space.kscience.kmath.UnstableKMathAPI")
             }
         }
     }
 }
 
-readme {
-    readmeTemplate = file("docs/templates/README-TEMPLATE.md")
-}
 
-ksciencePublish {
-    github("kmath")
-    space()
-    sonatype()
-}
 
-apiValidation {
-    nonPublicMarkers.add("space.kscience.kmath.misc.UnstableKMathAPI")
-}

buildSrc/build.gradle.kts

@@ -1,20 +0,0 @@
-plugins {
-    `kotlin-dsl`
-    kotlin("plugin.serialization") version "1.4.31"
-}
-
-repositories {
-    maven("https://repo.kotlin.link")
-    mavenCentral()
-    gradlePluginPortal()
-}
-
-dependencies {
-    api("org.jetbrains.kotlinx:kotlinx-serialization-json:1.1.0")
-    api("ru.mipt.npm:gradle-tools:0.10.0")
-    api("org.jetbrains.kotlinx:kotlinx-benchmark-plugin:0.3.1")
-}
-
-kotlin.sourceSets.all {
-    languageSettings.useExperimentalAnnotation("kotlin.ExperimentalStdlibApi")
-}

buildSrc/src/main/kotlin/space/kscience/kmath/benchmarks/JmhReport.kt

@@ -1,60 +0,0 @@
-/*
- * Copyright 2018-2021 KMath contributors.
- * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
- */
-
-package space.kscience.kmath.benchmarks
-
-import kotlinx.serialization.Serializable
-
-@Serializable
-data class JmhReport(
-    val jmhVersion: String,
-    val benchmark: String,
-    val mode: String,
-    val threads: Int,
-    val forks: Int,
-    val jvm: String,
-    val jvmArgs: List<String>,
-    val jdkVersion: String,
-    val vmName: String,
-    val vmVersion: String,
-    val warmupIterations: Int,
-    val warmupTime: String,
-    val warmupBatchSize: Int,
-    val measurementIterations: Int,
-    val measurementTime: String,
-    val measurementBatchSize: Int,
-    val params: Map<String, String> = emptyMap(),
-    val primaryMetric: PrimaryMetric,
-    val secondaryMetrics: Map<String, SecondaryMetric>,
-) {
-    interface Metric {
-        val score: Double
-        val scoreError: Double
-        val scoreConfidence: List<Double>
-        val scorePercentiles: Map<Double, Double>
-        val scoreUnit: String
-    }
-
-    @Serializable
-    data class PrimaryMetric(
-        override val score: Double,
-        override val scoreError: Double,
-        override val scoreConfidence: List<Double>,
-        override val scorePercentiles: Map<Double, Double>,
-        override val scoreUnit: String,
-        val rawDataHistogram: List<List<List<List<Double>>>>? = null,
-        val rawData: List<List<Double>>? = null,
-    ) : Metric
-
-    @Serializable
-    data class SecondaryMetric(
-        override val score: Double,
-        override val scoreError: Double,
-        override val scoreConfidence: List<Double>,
-        override val scorePercentiles: Map<Double, Double>,
-        override val scoreUnit: String,
-        val rawData: List<List<Double>>,
-    ) : Metric
-}

buildSrc/src/main/kotlin/space/kscience/kmath/benchmarks/addBenchmarkProperties.kt

@@ -1,100 +0,0 @@
-/*
- * Copyright 2018-2021 KMath contributors.
- * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
- */
-
-package space.kscience.kmath.benchmarks
-
-import kotlinx.benchmark.gradle.BenchmarksExtension
-import kotlinx.serialization.*
-import kotlinx.serialization.json.*
-import org.gradle.api.Project
-import ru.mipt.npm.gradle.KScienceReadmeExtension
-import java.time.*
-import java.time.format.*
-import java.time.temporal.ChronoField.*
-
-private val ISO_DATE_TIME: DateTimeFormatter = DateTimeFormatterBuilder().run {
-    parseCaseInsensitive()
-    appendValue(YEAR, 4, 10, SignStyle.EXCEEDS_PAD)
-    appendLiteral('-')
-    appendValue(MONTH_OF_YEAR, 2)
-    appendLiteral('-')
-    appendValue(DAY_OF_MONTH, 2)
-    appendLiteral('T')
-    appendValue(HOUR_OF_DAY, 2)
-    appendLiteral('.')
-    appendValue(MINUTE_OF_HOUR, 2)
-    optionalStart()
-    appendLiteral('.')
-    appendValue(SECOND_OF_MINUTE, 2)
-    optionalStart()
-    appendFraction(NANO_OF_SECOND, 0, 9, true)
-    optionalStart()
-    appendOffsetId()
-    optionalStart()
-    appendLiteral('[')
-    parseCaseSensitive()
-    appendZoneRegionId()
-    appendLiteral(']')
-    toFormatter()
-}
-
-private fun noun(number: Number, singular: String, plural: String) = if (number.toLong() == 1L) singular else plural
-
-fun Project.addBenchmarkProperties() {
-    val benchmarksProject = this
-    rootProject.subprojects.forEach { p ->
-        p.extensions.findByType(KScienceReadmeExtension::class.java)?.run {
-            benchmarksProject.extensions.findByType(BenchmarksExtension::class.java)?.configurations?.forEach { cfg ->
-                property("benchmark${cfg.name.replaceFirstChar(Char::uppercase)}") {
-                    val launches = benchmarksProject.buildDir.resolve("reports/benchmarks/${cfg.name}")
-
-                    val resDirectory = launches.listFiles()?.maxByOrNull {
-                        LocalDateTime.parse(it.name, ISO_DATE_TIME).atZone(ZoneId.systemDefault()).toInstant()
-                    }
-
-                    if (resDirectory == null) {
-                        "> **Can't find appropriate benchmark data. Try generating readme files after running benchmarks**."
-                    } else {
-                        val reports =
-                            Json.decodeFromString<List<JmhReport>>(resDirectory.resolve("jvm.json").readText())
-
-                        buildString {
-                            appendLine("<details>")
-                            appendLine("<summary>")
-                            appendLine("Report for benchmark configuration <code>${cfg.name}</code>")
-                            appendLine("</summary>")
-                            appendLine()
-                            val first = reports.first()
-
-                            appendLine("* Run on ${first.vmName} (build ${first.vmVersion}) with Java process:")
-                            appendLine()
-                            appendLine("```")
-                            appendLine("${first.jvm} ${
-                                first.jvmArgs.joinToString(" ")
-                            }")
-                            appendLine("```")
-
-                            appendLine("* JMH ${first.jmhVersion} was used in `${first.mode}` mode with ${first.warmupIterations} warmup ${
-                                noun(first.warmupIterations, "iteration", "iterations")
-                            } by ${first.warmupTime} and ${first.measurementIterations} measurement ${
-                                noun(first.measurementIterations, "iteration", "iterations")
-                            } by ${first.measurementTime}.")
-
-                            appendLine()
-                            appendLine("| Benchmark | Score |")
-                            appendLine("|:---------:|:-----:|")
-
-                            reports.forEach { report ->
-                                appendLine("|`${report.benchmark}`|${report.primaryMetric.score} &plusmn; ${report.primaryMetric.scoreError} ${report.primaryMetric.scoreUnit}|")
-                            }
-
-                            appendLine("</details>")
-                        }
-                    }
-                }
-            }
-        }
-    }
-}

buildSrc/src/main/kotlin/space/kscience/kmath/ejml/codegen/ejmlCodegen.kt

@@ -1,425 +0,0 @@
-/*
- * Copyright 2018-2021 KMath contributors.
- * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
- */
-
-@file:Suppress("KDocUnresolvedReference")
-
-package space.kscience.kmath.ejml.codegen
-
-import org.intellij.lang.annotations.Language
-import java.io.File
-
-private fun Appendable.appendEjmlVector(type: String, ejmlMatrixType: String) {
-    @Language("kotlin") val text = """/**
- * [EjmlVector] specialization for [$type].
- */
-public class Ejml${type}Vector<out M : $ejmlMatrixType>(public override val origin: M) : EjmlVector<$type, M>(origin) {
-    init {
-        require(origin.numRows == 1) { "The origin matrix must have only one row to form a vector" }
-    }
-
-    public override operator fun get(index: Int): $type = origin[0, index]
-}"""
-    appendLine(text)
-    appendLine()
-}
-
-private fun Appendable.appendEjmlMatrix(type: String, ejmlMatrixType: String) {
-    val text = """/**
- * [EjmlMatrix] specialization for [$type].
- */
-public class Ejml${type}Matrix<out M : $ejmlMatrixType>(public override val origin: M) : EjmlMatrix<$type, M>(origin) {
-    public override operator fun get(i: Int, j: Int): $type = origin[i, j]
-}"""
-    appendLine(text)
-    appendLine()
-}
-
-private fun Appendable.appendEjmlLinearSpace(
-    type: String,
-    kmathAlgebra: String,
-    ejmlMatrixParentTypeMatrix: String,
-    ejmlMatrixType: String,
-    ejmlMatrixDenseType: String,
-    ops: String,
-    denseOps: String,
-    isDense: Boolean,
-) {
-    @Language("kotlin") val text = """/**
- * [EjmlLinearSpace] implementation based on [CommonOps_$ops], [DecompositionFactory_${ops}] operations and
- * [${ejmlMatrixType}] matrices.
- */
-public object EjmlLinearSpace${ops} : EjmlLinearSpace<${type}, ${kmathAlgebra}, $ejmlMatrixType>() {
-    /**
-     * The [${kmathAlgebra}] reference.
-     */
-    public override val elementAlgebra: $kmathAlgebra get() = $kmathAlgebra
-
-    @Suppress("UNCHECKED_CAST")
-    public override fun Matrix<${type}>.toEjml(): Ejml${type}Matrix<${ejmlMatrixType}> = when {
-        this is Ejml${type}Matrix<*> && origin is $ejmlMatrixType -> this as Ejml${type}Matrix<${ejmlMatrixType}>
-        else -> buildMatrix(rowNum, colNum) { i, j -> get(i, j) }
-    }
-
-    @Suppress("UNCHECKED_CAST")
-    public override fun Point<${type}>.toEjml(): Ejml${type}Vector<${ejmlMatrixType}> = when {
-        this is Ejml${type}Vector<*> && origin is $ejmlMatrixType -> this as Ejml${type}Vector<${ejmlMatrixType}>
-        else -> Ejml${type}Vector(${ejmlMatrixType}(size, 1).also {
-            (0 until it.numRows).forEach { row -> it[row, 0] = get(row) }
-        })
-    }
-
-    public override fun buildMatrix(
-        rows: Int,
-        columns: Int,
-        initializer: ${kmathAlgebra}.(i: Int, j: Int) -> ${type},
-    ): Ejml${type}Matrix<${ejmlMatrixType}> = ${ejmlMatrixType}(rows, columns).also {
-        (0 until rows).forEach { row ->
-            (0 until columns).forEach { col -> it[row, col] = elementAlgebra.initializer(row, col) }
-        }
-    }.wrapMatrix()
-
-    public override fun buildVector(
-        size: Int,
-        initializer: ${kmathAlgebra}.(Int) -> ${type},
-    ): Ejml${type}Vector<${ejmlMatrixType}> = Ejml${type}Vector(${ejmlMatrixType}(size, 1).also {
-        (0 until it.numRows).forEach { row -> it[row, 0] = elementAlgebra.initializer(row) }
-    })
-
-    private fun <T : ${ejmlMatrixParentTypeMatrix}> T.wrapMatrix() = Ejml${type}Matrix(this)
-    private fun <T : ${ejmlMatrixParentTypeMatrix}> T.wrapVector() = Ejml${type}Vector(this)
-
-    public override fun Matrix<${type}>.unaryMinus(): Matrix<${type}> = this * elementAlgebra { -one }
-
-    public override fun Matrix<${type}>.dot(other: Matrix<${type}>): Ejml${type}Matrix<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.mult(toEjml().origin, other.toEjml().origin, out)
-        return out.wrapMatrix()
-    }
-
-    public override fun Matrix<${type}>.dot(vector: Point<${type}>): Ejml${type}Vector<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.mult(toEjml().origin, vector.toEjml().origin, out)
-        return out.wrapVector()
-    }
-
-    public override operator fun Matrix<${type}>.minus(other: Matrix<${type}>): Ejml${type}Matrix<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-
-        CommonOps_${ops}.add(
-            elementAlgebra.one, 
-            toEjml().origin, 
-            elementAlgebra { -one },
-            other.toEjml().origin, 
-            out,${
-        if (isDense) "" else
-            """
-            null, 
-            null,"""
-    }
-        )
-
-        return out.wrapMatrix()
-    }
-
-    public override operator fun Matrix<${type}>.times(value: ${type}): Ejml${type}Matrix<${ejmlMatrixType}> {
-        val res = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.scale(value, toEjml().origin, res)
-        return res.wrapMatrix()
-    }
-
-    public override fun Point<${type}>.unaryMinus(): Ejml${type}Vector<${ejmlMatrixType}> {
-        val res = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.changeSign(toEjml().origin, res)
-        return res.wrapVector()
-    }
-
-    public override fun Matrix<${type}>.plus(other: Matrix<${type}>): Ejml${type}Matrix<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-        
-        CommonOps_${ops}.add(
-            elementAlgebra.one,
-            toEjml().origin,
-            elementAlgebra.one,
-            other.toEjml().origin, 
-            out,${
-        if (isDense) "" else
-            """
-            null, 
-            null,"""
-    }
-        )
-
-        return out.wrapMatrix()
-    }
-
-    public override fun Point<${type}>.plus(other: Point<${type}>): Ejml${type}Vector<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-
-        CommonOps_${ops}.add(
-            elementAlgebra.one,
-            toEjml().origin,
-            elementAlgebra.one,
-            other.toEjml().origin,
-            out,${
-        if (isDense) "" else
-            """
-            null, 
-            null,"""
-    }
-        )
-
-        return out.wrapVector()
-    }
-
-    public override fun Point<${type}>.minus(other: Point<${type}>): Ejml${type}Vector<${ejmlMatrixType}> {
-        val out = ${ejmlMatrixType}(1, 1)
-
-        CommonOps_${ops}.add(
-            elementAlgebra.one,
-            toEjml().origin,
-            elementAlgebra { -one },
-            other.toEjml().origin,
-            out,${
-        if (isDense) "" else
-            """
-            null, 
-            null,"""
-    }
-        )
-
-        return out.wrapVector()
-    }
-
-    public override fun ${type}.times(m: Matrix<${type}>): Ejml${type}Matrix<${ejmlMatrixType}> = m * this
-
-    public override fun Point<${type}>.times(value: ${type}): Ejml${type}Vector<${ejmlMatrixType}> {
-        val res = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.scale(value, toEjml().origin, res)
-        return res.wrapVector()
-    }
-
-    public override fun ${type}.times(v: Point<${type}>): Ejml${type}Vector<${ejmlMatrixType}> = v * this
-
-    @UnstableKMathAPI
-    public override fun <F : StructureFeature> getFeature(structure: Matrix<${type}>, type: KClass<out F>): F? {
-        structure.getFeature(type)?.let { return it }
-        val origin = structure.toEjml().origin
-
-        return when (type) {
-        ${
-        if (isDense)
-            """    InverseMatrixFeature::class -> object : InverseMatrixFeature<${type}> {
-                override val inverse: Matrix<${type}> by lazy {
-                    val res = origin.copy()
-                    CommonOps_${ops}.invert(res)
-                    res.wrapMatrix()
-                }
-            }
-
-            DeterminantFeature::class -> object : DeterminantFeature<${type}> {
-                override val determinant: $type by lazy { CommonOps_${ops}.det(origin) }
-            }
-
-            SingularValueDecompositionFeature::class -> object : SingularValueDecompositionFeature<${type}> {
-                private val svd by lazy {
-                    DecompositionFactory_${ops}.svd(origin.numRows, origin.numCols, true, true, false)
-                        .apply { decompose(origin.copy()) }
-                }
-
-                override val u: Matrix<${type}> by lazy { svd.getU(null, false).wrapMatrix() }
-                override val s: Matrix<${type}> by lazy { svd.getW(null).wrapMatrix() }
-                override val v: Matrix<${type}> by lazy { svd.getV(null, false).wrapMatrix() }
-                override val singularValues: Point<${type}> by lazy { ${type}Buffer(svd.singularValues) }
-            }
-
-            QRDecompositionFeature::class -> object : QRDecompositionFeature<${type}> {
-                private val qr by lazy {
-                    DecompositionFactory_${ops}.qr().apply { decompose(origin.copy()) }
-                }
-
-                override val q: Matrix<${type}> by lazy {
-                    qr.getQ(null, false).wrapMatrix() + OrthogonalFeature
-                }
-
-                override val r: Matrix<${type}> by lazy { qr.getR(null, false).wrapMatrix() + UFeature }
-            }
-
-            CholeskyDecompositionFeature::class -> object : CholeskyDecompositionFeature<${type}> {
-                override val l: Matrix<${type}> by lazy {
-                    val cholesky =
-                        DecompositionFactory_${ops}.chol(structure.rowNum, true).apply { decompose(origin.copy()) }
-
-                    cholesky.getT(null).wrapMatrix() + LFeature
-                }
-            }
-
-            LupDecompositionFeature::class -> object : LupDecompositionFeature<${type}> {
-                private val lup by lazy {
-                    DecompositionFactory_${ops}.lu(origin.numRows, origin.numCols).apply { decompose(origin.copy()) }
-                }
-
-                override val l: Matrix<${type}> by lazy {
-                    lup.getLower(null).wrapMatrix() + LFeature
-                }
-
-                override val u: Matrix<${type}> by lazy {
-                    lup.getUpper(null).wrapMatrix() + UFeature
-                }
-
-                override val p: Matrix<${type}> by lazy { lup.getRowPivot(null).wrapMatrix() }
-            }""" else """    QRDecompositionFeature::class -> object : QRDecompositionFeature<$type> {
-                private val qr by lazy {
-                    DecompositionFactory_${ops}.qr(FillReducing.NONE).apply { decompose(origin.copy()) }
-                }
-
-                override val q: Matrix<${type}> by lazy {
-                    qr.getQ(null, false).wrapMatrix() + OrthogonalFeature
-                }
-
-                override val r: Matrix<${type}> by lazy { qr.getR(null, false).wrapMatrix() + UFeature }
-            }
-
-            CholeskyDecompositionFeature::class -> object : CholeskyDecompositionFeature<${type}> {
-                override val l: Matrix<${type}> by lazy {
-                    val cholesky =
-                        DecompositionFactory_${ops}.cholesky().apply { decompose(origin.copy()) }
-
-                    (cholesky.getT(null) as ${ejmlMatrixParentTypeMatrix}).wrapMatrix() + LFeature
-                }
-            }
-
-            LUDecompositionFeature::class, DeterminantFeature::class, InverseMatrixFeature::class -> object :
-                LUDecompositionFeature<${type}>, DeterminantFeature<${type}>, InverseMatrixFeature<${type}> {
-                private val lu by lazy {
-                    DecompositionFactory_${ops}.lu(FillReducing.NONE).apply { decompose(origin.copy()) }
-                }
-
-                override val l: Matrix<${type}> by lazy {
-                    lu.getLower(null).wrapMatrix() + LFeature
-                }
-
-                override val u: Matrix<${type}> by lazy {
-                    lu.getUpper(null).wrapMatrix() + UFeature
-                }
-
-                override val inverse: Matrix<${type}> by lazy {
-                    var a = origin
-                    val inverse = ${ejmlMatrixDenseType}(1, 1)
-                    val solver = LinearSolverFactory_${ops}.lu(FillReducing.NONE)
-                    if (solver.modifiesA()) a = a.copy()
-                    val i = CommonOps_${denseOps}.identity(a.numRows)
-                    solver.solve(i, inverse)
-                    inverse.wrapMatrix()
-                }
-
-                override val determinant: $type by lazy { elementAlgebra.number(lu.computeDeterminant().real) }
-            }"""
-    }
-
-            else -> null
-        }?.let(type::cast)
-    }
-
-    /**
-     * Solves for *x* in the following equation: *x = [a] <sup>-1</sup> &middot; [b]*.
-     *
-     * @param a the base matrix.
-     * @param b n by p matrix.
-     * @return the solution for *x* that is n by p.
-     */
-    public fun solve(a: Matrix<${type}>, b: Matrix<${type}>): Ejml${type}Matrix<${ejmlMatrixType}> {
-        val res = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.solve(${ejmlMatrixType}(a.toEjml().origin), ${ejmlMatrixType}(b.toEjml().origin), res)
-        return res.wrapMatrix()
-    }
-
-    /**
-     * Solves for *x* in the following equation: *x = [a] <sup>-1</sup> &middot; [b]*.
-     *
-     * @param a the base matrix.
-     * @param b n by p vector.
-     * @return the solution for *x* that is n by p.
-     */
-    public fun solve(a: Matrix<${type}>, b: Point<${type}>): Ejml${type}Vector<${ejmlMatrixType}> {
-        val res = ${ejmlMatrixType}(1, 1)
-        CommonOps_${ops}.solve(${ejmlMatrixType}(a.toEjml().origin), ${ejmlMatrixType}(b.toEjml().origin), res)
-        return Ejml${type}Vector(res)
-    }
-}"""
-    appendLine(text)
-    appendLine()
-}
-
-
-/**
- * Generates routine EJML classes.
- */
-fun ejmlCodegen(outputFile: String): Unit = File(outputFile).run {
-    parentFile.mkdirs()
-
-    writer().use {
-        it.appendLine("/*")
-        it.appendLine(" * Copyright 2018-2021 KMath contributors.")
-        it.appendLine(" * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.")
-        it.appendLine(" */")
-        it.appendLine()
-        it.appendLine("/* This file is generated with buildSrc/src/main/kotlin/space/kscience/kmath/ejml/codegen/ejmlCodegen.kt */")
-        it.appendLine()
-        it.appendLine("package space.kscience.kmath.ejml")
-        it.appendLine()
-        it.appendLine("""import org.ejml.data.*
-import org.ejml.dense.row.CommonOps_DDRM
-import org.ejml.dense.row.CommonOps_FDRM
-import org.ejml.dense.row.factory.DecompositionFactory_DDRM
-import org.ejml.dense.row.factory.DecompositionFactory_FDRM
-import org.ejml.sparse.FillReducing
-import org.ejml.sparse.csc.CommonOps_DSCC
-import org.ejml.sparse.csc.CommonOps_FSCC
-import org.ejml.sparse.csc.factory.DecompositionFactory_DSCC
-import org.ejml.sparse.csc.factory.DecompositionFactory_FSCC
-import org.ejml.sparse.csc.factory.LinearSolverFactory_DSCC
-import org.ejml.sparse.csc.factory.LinearSolverFactory_FSCC
-import space.kscience.kmath.linear.*
-import space.kscience.kmath.linear.Matrix
-import space.kscience.kmath.misc.UnstableKMathAPI
-import space.kscience.kmath.nd.StructureFeature
-import space.kscience.kmath.operations.DoubleField
-import space.kscience.kmath.operations.FloatField
-import space.kscience.kmath.operations.invoke
-import space.kscience.kmath.structures.DoubleBuffer
-import space.kscience.kmath.structures.FloatBuffer
-import kotlin.reflect.KClass
-import kotlin.reflect.cast""")
-        it.appendLine()
-        it.appendEjmlVector("Double", "DMatrix")
-        it.appendEjmlVector("Float", "FMatrix")
-        it.appendEjmlMatrix("Double", "DMatrix")
-        it.appendEjmlMatrix("Float", "FMatrix")
-        it.appendEjmlLinearSpace("Double", "DoubleField", "DMatrix", "DMatrixRMaj", "DMatrixRMaj", "DDRM", "DDRM", true)
-        it.appendEjmlLinearSpace("Float", "FloatField", "FMatrix", "FMatrixRMaj", "FMatrixRMaj", "FDRM", "FDRM", true)
-
-        it.appendEjmlLinearSpace(
-            type = "Double",
-            kmathAlgebra = "DoubleField",
-            ejmlMatrixParentTypeMatrix = "DMatrix",
-            ejmlMatrixType = "DMatrixSparseCSC",
-            ejmlMatrixDenseType = "DMatrixRMaj",
-            ops = "DSCC",
-            denseOps = "DDRM",
-            isDense = false,
-        )
-
-        it.appendEjmlLinearSpace(
-            type = "Float",
-            kmathAlgebra = "FloatField",
-            ejmlMatrixParentTypeMatrix = "FMatrix",
-            ejmlMatrixType = "FMatrixSparseCSC",
-            ejmlMatrixDenseType = "FMatrixRMaj",
-            ops = "FSCC",
-            denseOps = "FDRM",
-            isDense = false,
-        )
-    }
-}

docs/algebra.md

@@ -1,85 +1,45 @@
 # Algebraic Structures and Algebraic Elements
 
-The mathematical operations in KMath are generally separated from mathematical objects. This means that to perform an 
-operation, say `+`, one needs two objects of a type `T` and an algebra context, which draws appropriate operation up, 
-say `Space<T>`. Next one needs to run the actual operation in the context:
+The mathematical operations in KMath are generally separated from mathematical objects. This means that to perform an
+operation, say `+`, one needs two objects of a type `T` and an algebra context, which draws appropriate operation up,
+say `Group<T>`. Next one needs to run the actual operation in the context:
 
 ```kotlin
 import space.kscience.kmath.operations.*
 
 val a: T = ...
 val b: T = ...
-val space: Space<T> = ...
+val group: Group<T> = ...
 
-val c = space { a + b }
+val c = group { a + b }
 ```
 
-At first glance, this distinction seems to be a needless complication, but in fact one needs to remember that in 
-mathematics, one could draw up different operations on same objects. For example, one could use different types of 
+At first glance, this distinction seems to be a needless complication, but in fact one needs to remember that in
+mathematics, one could draw up different operations on same objects. For example, one could use different types of
 geometry for vectors.
 
 ## Algebraic Structures
 
-Mathematical contexts have the following hierarchy:
+Primary mathematical contexts have the following hierarchy:
 
-**Algebra** ← **Space** ← **Ring** ← **Field**
+`Field <: Ring <: Group <: Algebra`
 
 These interfaces follow real algebraic structures:
 
-- [Space](https://mathworld.wolfram.com/VectorSpace.html) defines addition, its neutral element (i.e. 0) and scalar 
-multiplication;
-- [Ring](http://mathworld.wolfram.com/Ring.html) adds multiplication and its neutral element (i.e. 1);
+- [Group](https://mathworld.wolfram.com/Group.html) defines addition, its identity element (i.e., 0) and additive
+  inverse (-x);
+- [Ring](http://mathworld.wolfram.com/Ring.html) adds multiplication and its identity element (i.e., 1);
 - [Field](http://mathworld.wolfram.com/Field.html) adds division operation.
 
 A typical implementation of `Field<T>` is the `DoubleField` which works on doubles, and `VectorSpace` for `Space<T>`.
 
 In some cases algebra context can hold additional operations like `exp` or `sin`, and then it inherits appropriate
-interface. Also, contexts may have operations, which produce elements outside of the context. For example, `Matrix.dot` 
-operation produces a matrix with new dimensions, which can be incompatible with initial matrix in terms of linear 
-operations.
-
-## Algebraic Element
-
-To achieve more familiar behavior (where you apply operations directly to mathematical objects), without involving 
-contexts KMath submits special type objects called `MathElement`. A `MathElement` is basically some object coupled to
-a mathematical context. For example `Complex` is the pair of real numbers representing real and imaginary parts,
-but it also holds reference to the `ComplexField` singleton, which allows performing direct operations on `Complex`
-numbers without explicit involving the context like:
-
-```kotlin
-import space.kscience.kmath.operations.*
-
-// Using elements
-val c1 = Complex(1.0, 1.0)
-val c2 = Complex(1.0, -1.0)
-val c3 = c1 + c2 + 3.0.toComplex()
-
-// Using context
-val c4 = ComplexField { c1 + i - 2.0 }
-```
-
-Both notations have their pros and cons.
-
-The hierarchy for algebraic elements follows the hierarchy for the corresponding algebraic structures.
-
-**MathElement** ← **SpaceElement** ← **RingElement** ← **FieldElement**
-
-`MathElement<C>` is the generic common ancestor of the class with context.
-
-One major distinction between algebraic elements and algebraic contexts is that elements have three type 
-parameters:
-
-1. The type of elements, the field operates on.
-2. The self-type of the element returned from operation (which has to be an algebraic element).
-3. The type of the algebra over first type-parameter.
-
-The middle type is needed for of algebra members do not store context. For example, it is impossible to add a context 
-to regular `Double`. The element performs automatic conversions from context types and back. One should use context 
-operations in all performance-critical places. The performance of element operations is not guaranteed.
+interface. Also, contexts may have operations, which produce elements outside the context. For example, `Matrix.dot`
+operation produces a matrix with new dimensions, which can be incompatible with initial matrix in linear operations.
 
 ## Spaces and Fields
 
-KMath submits both contexts and elements for builtin algebraic structures:
+KMath introduces contexts for builtin algebraic structures:
 
 ```kotlin
 import space.kscience.kmath.operations.*
@@ -102,13 +62,13 @@ val c2 = ComplexField { c1 - 1.0 } // Returns: Complex(re=0.0, im=2.0)
 val c3 = ComplexField { c1 - i * 2.0 }
 ```
 
-**Note**: In theory it is possible to add behaviors directly to the context, but as for now Kotlin does not support 
-that. Watch [KT-10468](https://youtrack.jetbrains.com/issue/KT-10468) and 
+**Note**: In theory it is possible to add behaviors directly to the context, but as for now Kotlin does not support
+that. Watch [KT-10468](https://youtrack.jetbrains.com/issue/KT-10468) and
 [KEEP-176](https://github.com/Kotlin/KEEP/pull/176) for updates.
 
 ## Nested fields
 
-Contexts allow one to build more complex structures. For example, it is possible to create a `Matrix` from complex 
+Contexts allow one to build more complex structures. For example, it is possible to create a `Matrix` from complex
 elements like so:
 
 ```kotlin
@@ -118,8 +78,9 @@ val element = NDElement.complex(shape = intArrayOf(2, 2)) { index: IntArray ->
 ```
 
 The `element` in this example is a member of the `Field` of 2D structures, each element of which is a member of its own
-`ComplexField`. It is important one does not need to create a special n-d class to hold complex
-numbers and implement operations on it, one just needs to provide a field for its elements.
+`ComplexField`. It is important one does not need to create a special n-d class to hold complex numbers and implement
+operations on it, one just needs to provide a field for its elements.
 
-**Note**: Fields themselves do not solve the problem of JVM boxing, but it is possible to solve with special contexts like
+**Note**: Fields themselves do not solve the problem of JVM boxing, but it is possible to solve with special contexts
+like
 `MemorySpec`.

docs/buffers.md

@@ -1,17 +1,20 @@
 # Buffers
 
-Buffer is one of main building blocks of kmath. It is a basic interface allowing random-access read and write (with `MutableBuffer`).
-There are different types of buffers:
+Buffer is one of main building blocks of kmath. It is a basic interface allowing random-access read and write (
+with `MutableBuffer`). There are different types of buffers:
 
-* Primitive buffers wrapping like `RealBuffer` which are wrapping primitive arrays.
+* Primitive buffers wrapping like `DoubleBuffer` which are wrapping primitive arrays.
 * Boxing `ListBuffer` wrapping a list
 * Functionally defined `VirtualBuffer` which does not hold a state itself, but provides a function to calculate value
 * `MemoryBuffer` allows direct allocation of objects in continuous memory block.
 
-Some kmath features require a `BufferFactory` class to operate properly. A general convention is to use functions defined in
-`Buffer` and `MutableBuffer` companion classes. For example factory `Buffer.Companion::auto` in most cases creates the most suitable
-buffer for given reified type (for types with custom memory buffer it still better to use their own `MemoryBuffer.create()` factory).
+Some kmath features require a `BufferFactory` class to operate properly. A general convention is to use functions
+defined in
+`Buffer` and `MutableBuffer` companion classes. For example factory `Buffer.Companion::auto` in most cases creates the
+most suitable buffer for given reified type (for types with custom memory buffer it still better to use their
+own `MemoryBuffer.create()` factory).
 
 ## Buffer performance
 
-One should avoid using default boxing buffer wherever it is possible. Try to use primitive buffers or memory buffers instead  
+One should avoid using default boxing buffer wherever it is possible. Try to use primitive buffers or memory buffers
+instead.

docs/codestyle.md

@@ -1,34 +1,35 @@
 # Coding Conventions
 
-KMath code follows general [Kotlin conventions](https://kotlinlang.org/docs/reference/coding-conventions.html), but 
-with a number of small changes and clarifications.
+Generally, KMath code follows
+general [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html), but with a number of
+small changes and clarifications.
 
 ## Utility Class Naming
 
-Filename should coincide with a name of one of the classes contained in the file or start with small letter and 
-describe its contents.
+Filename should coincide with a name of one of the classes contained in the file or start with small letter and describe
+its contents.
 
-The code convention [here](https://kotlinlang.org/docs/reference/coding-conventions.html#source-file-names) says that 
-file names should start with a capital letter even if file does not contain classes. Yet starting utility classes and 
+The code convention [here](https://kotlinlang.org/docs/reference/coding-conventions.html#source-file-names) says that
+file names should start with a capital letter even if file does not contain classes. Yet starting utility classes and
 aggregators with a small letter seems to be a good way to visually separate those files.
 
 This convention could be changed in future in a non-breaking way.
 
 ## Private Variable Naming
 
-Private variables' names may start with underscore `_` for of the private mutable variable is shadowed by the public 
+Private variables' names may start with underscore `_` for of the private mutable variable is shadowed by the public
 read-only value with the same meaning.
 
-This rule does not permit underscores in names, but it is sometimes useful to "underscore" the fact that public and 
+This rule does not permit underscores in names, but it is sometimes useful to "underscore" the fact that public and
 private versions draw up the same entity. It is allowed only for private variables.
 
 This convention could be changed in future in a non-breaking way.
 
 ## Functions and Properties One-liners
 
-Use one-liners when they occupy single code window line both for functions and properties with getters like 
-`val b: String get() = "fff"`. The same should be performed with multiline expressions when they could be 
+Use one-liners when they occupy single code window line both for functions and properties with getters like
+`val b: String get() = "fff"`. The same should be performed with multiline expressions when they could be
 cleanly separated.
 
-There is no universal consensus whenever use `fun a() = ...` or `fun a() { return ... }`. Yet from reader outlook 
+There is no universal consensus whenever use `fun a() = ...` or `fun a() { return ... }`. Yet from reader outlook
 one-lines seem to better show that the property or function is easily calculated.

docs/contexts.md

@@ -2,18 +2,17 @@
 
 ## The problem
 
-A known problem for implementing mathematics in statically-typed languages (but not only in them) is that different
-sets of mathematical operators can be defined on the same mathematical objects. Sometimes there is no single way to
-treat some operations, including basic arithmetic operations, on a Java/Kotlin `Number`. Sometimes there are different ways to
-define the same structure, such as Euclidean and elliptic geometry vector spaces over real vectors. Another problem arises when
-one wants to add some kind of behavior to an existing entity. In dynamic languages those problems are usually solved
-by adding dynamic context-specific behaviors at runtime, but this solution has a lot of drawbacks.
+A known problem for implementing mathematics in statically-typed languages (but not only in them) is that different sets
+of mathematical operators can be defined on the same mathematical objects. Sometimes there is no single way to treat
+some operations, including basic arithmetic operations, on a Java/Kotlin `Number`. Sometimes there are different ways to
+define the same structure, such as Euclidean and elliptic geometry vector spaces over real vectors. Another problem
+arises when one wants to add some kind of behavior to an existing entity. In dynamic languages those problems are
+usually solved by adding dynamic context-specific behaviors at runtime, but this solution has a lot of drawbacks.
 
 ## Context-oriented approach
 
-One possible solution to these problems is to divorce numerical representations from behaviors.
-For example in Kotlin one can define a separate class which represents some entity without any operations,
-ex. a complex number:
+One possible solution to these problems is to divorce numerical representations from behaviors. For example in Kotlin
+one can define a separate class representing some entity without any operations, ex. a complex number:
 
 ```kotlin
 data class Complex(val re: Double, val im: Double)
@@ -28,9 +27,10 @@ object ComplexOperations {
 }
 ```
 
-In Java, applying such external operations could be very cumbersome, but Kotlin has a unique feature which allows us
-implement this naturally: [extensions with receivers](https://kotlinlang.org/docs/reference/extensions.html#extension-functions).
-In Kotlin, an operation on complex number could be implemented as:
+In Java, applying such external operations could be cumbersome, but Kotlin has a unique feature that allows us
+implement this
+naturally: [extensions with receivers](https://kotlinlang.org/docs/reference/extensions.html#extension-functions). In
+Kotlin, an operation on complex number could be implemented as:
 
 ```kotlin
 with(ComplexOperations) { c1 + c2 - c3 }
@@ -52,20 +52,20 @@ In KMath, contexts are not only responsible for operations, but also for raw obj
 
 ### Type classes
 
-An obvious candidate to get more or less the same functionality is the type class, which allows one to bind a behavior to
-a specific type without modifying the type itself. On the plus side, type classes do not require explicit context
+An obvious candidate to get more or less the same functionality is the type class, which allows one to bind a behavior
+to a specific type without modifying the type itself. On the plus side, type classes do not require explicit context
 declaration, so the code looks cleaner. On the minus side, if there are different sets of behaviors for the same types,
-it is impossible to combine them into one module. Also, unlike type classes, context can have parameters or even
-state. For example in KMath, sizes and strides for `NDElement` or `Matrix` could be moved to context to optimize
-performance in case of a large amount of structures.
+it is impossible to combine them into one module. Also, unlike type classes, context can have parameters or even state.
+For example in KMath, sizes and strides for `NDElement` or `Matrix` could be moved to context to optimize performance in
+case of a large amount of structures.
 
 ### Wildcard imports and importing-on-demand
 
-Sometimes, one may wish to use a single context throughout a file. In this case, is possible to import all members
-from a package or file, via `import context.complex.*`. Effectively, this is the same as enclosing an entire file
-with a single context. However when using multiple contexts, this technique can introduce operator ambiguity, due to
-namespace pollution. If there are multiple scoped contexts which define the same operation, it is still possible to
-to import specific operations as needed, without using an explicit context with extension functions, for example:
+Sometimes, one may wish to use a single context throughout a file. In this case, is possible to import all members from
+a package or file, via `import context.complex.*`. Effectively, this is the same as enclosing an entire file with a
+single context. However, when using multiple contexts, this technique can introduce operator ambiguity, due to namespace
+pollution. If there are multiple scoped contexts that define the same operation, it is still possible to import
+specific operations as needed, without using an explicit context with extension functions, for example:
 
 ```
 import context.complex.op1

docs/expressions.md

@@ -1,26 +1,24 @@
 # Expressions
 
-**Experimental: this API is in early stage and could change any time**
-
-Expressions is an experimental feature which allows to construct lazily or immediately calculated parametric mathematical 
+Expressions is a feature, which allows constructing lazily or immediately calculated parametric mathematical
 expressions.
 
 The potential use-cases for it (so far) are following:
 
-* Lazy evaluation (in general simple lambda is better, but there are some border cases)
+* lazy evaluation (in general simple lambda is better, but there are some border cases);
+* automatic differentiation in single-dimension and in multiple dimensions;
+* generation of mathematical syntax trees with subsequent code generation for other languages;
+* symbolic computations, especially differentiation (and some other actions with `kmath-symja` integration with