Merge pull request #122 from Kotlin/v0.2.0

V0.2.0
Kotlin · Jul 25, 2022 · 82c36a6 · 82c36a6
2 parents af126cd + fedaba3
commit 82c36a6
Show file tree

Hide file tree

Showing 94 changed files with 885 additions and 194 deletions.
diff --git a/LICENSE b/LICENSE
@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2000-2021 JetBrains s.r.o.
+   Copyright 2000-2022 JetBrains s.r.o.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -8,12 +8,13 @@
 Multidimensional array library for Kotlin.
 
 ## Modules
-* multik-core &mdash; contains ndarrays, methods called on them and [math], [stat] and [linalg] interfaces.
-* multik-default &mdash; implementation including `jvm` and `native` for performance.
-* multik-kotlin &mdash; implementation of [math], [stat] and [linalg] interfaces on JVM.
-* multik-openblas &mdash; implementation of [math], [stat] and [linalg] interfaces in native code using OpenBLAS.
+* `multik-core` &mdash; contains ndarrays, methods called on them and [math], [stat] and [linalg] interfaces.
+* `multik-default` &mdash; implementation including `multik-kotlin` and `multik-openblas` for performance.
+* `multik-kotlin` &mdash; implementation of [math], [stat] and [linalg] interfaces on JVM.
+* `multik-openblas` &mdash; implementation of [math], [stat] and [linalg] interfaces in native code using OpenBLAS.
 
 ## Using in your projects
+### Gradle
 In your Gradle build script:
 1. Add the Maven Central Repository.
 2. Add the `org.jetbrains.kotlinx:multik-core:$multik_version` api dependency.
@@ -27,8 +28,8 @@ repositories {
 }
 
 dependencies {
-    implementation "org.jetbrains.kotlinx:multik-core:0.1.1"
-    implementation "org.jetbrains.kotlinx:multik-default:0.1.1"
+    implementation "org.jetbrains.kotlinx:multik-core:0.2.0"
+    implementation "org.jetbrains.kotlinx:multik-default:0.2.0"
 }
 ```
 
@@ -39,11 +40,73 @@ repositories {
 }
 
 dependencies {
-    implementation("org.jetbrains.kotlinx:multik-core:0.1.1")
-    implementation("org.jetbrains.kotlinx:multik-default:0.1.1")
+    implementation("org.jetbrains.kotlinx:multik-core:0.2.0")
+    implementation("org.jetbrains.kotlinx:multik-default:0.2.0")
 }
 ```
 
+For a multiplatform project, set the dependency in a common block:
+
+```kotlin
+kotlin {
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation("org.jetbrains.kotlinx:multik-core:0.2.0")
+            }
+        }
+    }
+}
+```
+
+or in a platform-specific block:
+
+```kotlin
+kotlin {
+    sourceSets {
+        val jvmName by getting {
+            dependencies {
+                implementation("org.jetbrains.kotlinx:multik-core-jvm:0.2.0")
+            }
+        }
+    }
+}
+```
+
+### Jupyter Notebook
+Install [Kotlin kernel](https://github.com/Kotlin/kotlin-jupyter) for
+[Jupyter](https://jupyter.org/)
+or just visit to [Datalore](https://datalore.jetbrains.com/).
+
+Import stable `multik` version into notebook:
+```
+%use multik
+```
+
+## Support platforms
+
+|       Platforms       |   `multik-core`    |  `multik-kotlin`   |                                                                              `multik-openblas`                                                                              |                                                                              `multik-default`                                                                               |
+|:---------------------:|:------------------:|:------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+|        **JS**         | :white_check_mark: | :white_check_mark: |                                                                                     :x:                                                                                     |                                                                             :white_check_mark:                                                                              |
+|     **linuxX64**      | :white_check_mark: | :white_check_mark: |                                                                             :white_check_mark:                                                                              |                                                                             :white_check_mark:                                                                              |
+|     **mingwX64**      | :white_check_mark: | :white_check_mark: |                                                                             :white_check_mark:                                                                              |                                                                             :white_check_mark:                                                                              |
+|     **macosX64**      | :white_check_mark: | :white_check_mark: |                                                                             :white_check_mark:                                                                              |                                                                             :white_check_mark:                                                                              |
+|    **macosArm64**     | :white_check_mark: | :white_check_mark: |                                                                             :white_check_mark:                                                                              |                                                                             :white_check_mark:                                                                              |
+|     **iosArm64**      | :white_check_mark: | :white_check_mark: |                                                                                     :x:                                                                                     |                                                                             :white_check_mark:                                                                              |
+|      **iosX64**       | :white_check_mark: | :white_check_mark: |                                                                                     :x:                                                                                     |                                                                             :white_check_mark:                                                                              |
+| **iosSimulatorArm64** | :white_check_mark: | :white_check_mark: |                                                                                     :x:                                                                                     |                                                                             :white_check_mark:                                                                              |
+|        **JVM**        | :white_check_mark: | :white_check_mark: | linuxX64 - :white_check_mark:<br/>mingwX64 - :white_check_mark:<br/>macosX64 - :white_check_mark:<br/>macosArm64 - :white_check_mark:<br/>androidArm64 - :white_check_mark: | linuxX64 - :white_check_mark:<br/>mingwX64 - :white_check_mark:<br/>macosX64 - :white_check_mark:<br/>macosArm64 - :white_check_mark:<br/>androidArm64 - :white_check_mark: |
+
+For Kotlin/JS, we use the new [IR](https://kotlinlang.org/docs/js-ir-compiler.html).
+We also use the [new memory model](https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/)
+in Kotlin/Native. Keep this in mind when using Multik in your multiplatform projects.
+
+**Note**:
+* on ubuntu 18.04 and older `multik-openblas` doesn't work due to older versions of _**glibc**_.
+* `multik-openblas` for desktop targets (_linuxX64_, _mingwX64_, _macosX64_, _macosArm64_) is experimental and unstable.
+We will improve stability and perfomance as _Kotlin/Native_ evolves.
+* JVM target `multik-openblas` for Android only supports **arm64-v8a** processors.
+
 ## Quickstart
 
 Visit [Multik documentation](https://kotlin.github.io/multik) for a detailed feature overview.
@@ -153,6 +216,12 @@ f * d // multiplication
 ```
 
 #### Array mathematics
+
+See documentation for other methods of
+[mathematics](https://kotlin.github.io/multik/multik-core/org.jetbrains.kotlinx.multik.api.math/index.html),
+[linear algebra](https://kotlin.github.io/multik/multik-core/org.jetbrains.kotlinx.multik.api.linalg/index.html),
+[statistics](https://kotlin.github.io/multik/multik-core/org.jetbrains.kotlinx.multik.api.stat/index.html).
+
 ```kotlin
 a.sin() // element-wise sin, equivalent to mk.math.sin(a)
 a.cos() // element-wise cos, equivalent to mk.math.cos(a)
@@ -161,8 +230,6 @@ b.exp() // element-wise exp, equivalent to mk.math.exp(b)
 d dot e // dot product, equivalent to mk.linalg.dot(d, e)
 ```
 
-See [documentation](https://kotlin.github.io/multik) for other linear algebra methods.
-
 #### Aggregate functions
 ```kotlin
 mk.math.sum(c) // array-wise sum
@@ -230,18 +297,15 @@ a.inplace {
 ```
 
 ## Building
-Multik uses BLAS and LAPACK for implementing algebraic operations. 
-Therefore, you would need a C ++ compiler and gfortran.
+To build the entire project, you need to set up an environment for building `multik-openblas`:
+* JDK 1.8 or higher
+* _JAVA_HOME_ environment - to search for jni files
+* Compilers _gcc_, _g++_, _gfortran_ version 8 or higher.
+It is important that they are of the same version.
+
 Run `./gradlew assemble` to build all modules.
-* To build api module run `./gradlew multik-core:assemble`.
-* To build jvm module run `./gradlew multik-kotlin:assemble`.
-* To build native module run `./gradlew multik-openblas:assemble`. 
-To reuse `multik-openblas` in the future, you must first build `multik_jni` and place the native library in 
-`multik-openblas/build/libs`
-* To build default module run `./gradlew multik-openblas:assemble` then `./gradlew multik-default:assemble`.
-
-## Testing
-`./gradlew test`
+If you don't need to build `multik-openblas`,
+just disable the `cmake_build` task and build the module you need.
 
 ## Contributing
 There is an opportunity to contribute to the project:

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2020-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 import java.time.Duration
 

diff --git a/gradle.properties b/gradle.properties
@@ -1,13 +1,13 @@
 kotlin.code.style=official
-multik_version=0.2.0-dev-4
+multik_version=0.2.0
 
 # Kotlin
 systemProp.kotlin_version=1.7.10
 group=org.jetbrains.kotlinx
 
 # Dependencies
 systemProp.nexus_version=1.1.0
-systemProp.dokka_version=1.6.0
+systemProp.dokka_version=1.7.10
 openblas_version=0.3.19
 common_csv_version=1.9.0
 

diff --git a/gradle/publish.gradle b/gradle/publish.gradle
@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2020-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 

diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
@@ -1,5 +1,5 @@
 #Thu Apr 09 14:05:51 MSK 2020
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStorePath=wrapper/dists

diff --git a/multik-core/build.gradle.kts b/multik-core/build.gradle.kts
@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2020-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 plugins {
@@ -87,15 +87,22 @@ kotlin {
 
 tasks.dokkaHtml.configure {
     outputDirectory.set(rootProject.buildDir.resolve("dokka"))
+    suppressObviousFunctions.set(true)
+    suppressInheritedMembers.set(true)
 
     dokkaSourceSets {
         configureEach {
-            includeNonPublic.set(false)
-            skipEmptyPackages.set(false)
+            documentedVisibilities.set(
+                setOf(
+                    org.jetbrains.dokka.DokkaConfiguration.Visibility.PUBLIC,
+                    org.jetbrains.dokka.DokkaConfiguration.Visibility.PROTECTED
+                )
+            )
+            skipDeprecated.set(false)
             jdkVersion.set(8)
             noStdlibLink.set(false)
             noJdkLink.set(false)
-            samples.from(files("src/test/kotlin/samples/creation.kt"))
+            samples.from(files("src/commonTest/kotlin/samples/creation.kt"))
         }
     }
 }