From bf2f4db468afe8b619c392c5745f9ed4a7e750dd Mon Sep 17 00:00:00 2001 From: Alexander Nozik Date: Sun, 8 Dec 2019 10:59:49 +0300 Subject: [PATCH] readme update --- .github/workflows/gradle.yml | 17 ++++ README.md | 79 ++++++++----------- build.gradle.kts | 4 +- .../scientifik/kmath/operations/Algebra.kt | 3 + 4 files changed, 53 insertions(+), 50 deletions(-) create mode 100644 .github/workflows/gradle.yml diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml new file mode 100644 index 000000000..adc74adfe --- /dev/null +++ b/.github/workflows/gradle.yml @@ -0,0 +1,17 @@ +name: Gradle build + +on: [push] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 + - name: Set up JDK 11 + uses: actions/setup-java@v1 + with: + java-version: 11 + - name: Build with Gradle + run: ./gradlew build diff --git a/README.md b/README.md index a1050f6ff..5678fc530 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,24 @@ Bintray: [ ![Download](https://api.bintray.com/packages/mipt-npm/scientifik/kmath-core/images/download.svg) ](https://bintray.com/mipt-npm/scientifik/kmath-core/_latestVersion) +Bintray-dev: [ ![Download](https://api.bintray.com/packages/mipt-npm/dev/kmath-core/images/download.svg) ](https://bintray.com/mipt-npm/scientifik/kmath-core/_latestVersion) + [![DOI](https://zenodo.org/badge/129486382.svg)](https://zenodo.org/badge/latestdoi/129486382) # KMath Could be pronounced as `key-math`. The Kotlin MATHematics library is intended as a Kotlin-based analog to Python's `numpy` library. In contrast to `numpy` and `scipy` it is modular and has a lightweight core. +# Goal +* Provide a flexible and powerful API to work with mathematics abstractions in Kotlin-multiplatform (JVM and JS for now and Native in future). +* 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. +* Provide 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 `for-real`, which will give better experience for those, who want to work with specific types. + ## Features Actual feature list is [here](doc/features.md) @@ -48,58 +61,15 @@ The plan is to have wrappers for koma implementations for compatibility with kma ## Multi-platform support -KMath is developed as a multi-platform library, which means that most of interfaces are declared in the [common module](kmath-core/src/commonMain). -Implementation is also done in the common module wherever possible. In some cases, features are delegated to -platform-specific implementations even if they could be done in the common module for performance reasons. -Currently, the JVM is the main focus of development, however Kotlin/Native and Kotlin/JS contributions are also welcome. +KMath is developed as a multi-platform library, which means that most of interfaces are declared in the [common module](kmath-core/src/commonMain). Implementation is also done in the common module wherever possible. In some cases, features are delegated to platform-specific implementations even if they could be done in the common module for performance reasons. Currently, the JVM is the main focus of development, however Kotlin/Native and Kotlin/JS contributions are also welcome. ## Performance -Calculation performance is one of major goals of KMath in the future, but in some cases it is not possible to achieve -both performance and flexibility. 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 should be better than SciPy. +Calculation performance is one of major goals of KMath in the future, but in some cases it is not possible to achieve both performance and flexibility. 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. -## Releases +### Dependency -Working builds can be obtained here: [![](https://jitpack.io/v/altavir/kmath.svg)](https://jitpack.io/#altavir/kmath). - -### Development - -The project is currently in pre-release stage. Nightly builds can be used by adding an additional repository to the Gradle config like so: - -```groovy -repositories { - maven { url = "http://npm.mipt.ru:8081/artifactory/gradle-dev" } - mavenCentral() -} -``` - -or for the Gradle Kotlin DSL: - -```kotlin -repositories { - maven("http://npm.mipt.ru:8081/artifactory/gradle-dev") - mavenCentral() -} -``` - -Then use a regular dependency like so: - -```groovy -api "scientifik:kmath-core-jvm:0.1.0-dev" -``` - -or in the Gradle Kotlin DSL: - -```kotlin -api("scientifik:kmath-core-jvm:0.1.0-dev") -``` - -### Release - -Release artifacts are accessible from bintray with following configuration: +Release artifacts are accessible from bintray with following configuration (see documentation for [kotlin-multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html) form more details): ```kotlin repositories{ @@ -107,10 +77,23 @@ repositories{ } dependencies{ - api("scientifik:kmath-core-jvm:0.1.0") + api("scientifik:kmath-core:${kmathVersion}") + //api("scientifik:kmath-core-jvm:${kmathVersion}") for jvm-specific version } ``` +Gradle `5.2+` is required for multiplatform artifacts. + +### Development + +Development builds are accessible from the reposirtory +```kotlin +repositories{ + maven("https://dl.bintray.com/mipt-npm/dev") +} +``` +with the same artifact names. + ## Contributing The project requires a lot of additional work. Please feel free to contribute in any way and propose new features. diff --git a/build.gradle.kts b/build.gradle.kts index 0b4171486..a63966dfe 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,8 +1,8 @@ plugins { - id("scientifik.publish") version "0.2.5" apply false + id("scientifik.publish") version "0.2.6" apply false } -val kmathVersion by extra("0.1.4-dev") +val kmathVersion by extra("0.1.4-dev-1") val bintrayRepo by extra("scientifik") val githubProject by extra("kmath") diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Algebra.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Algebra.kt index 9186e891f..0ed769db8 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Algebra.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Algebra.kt @@ -1,5 +1,8 @@ package scientifik.kmath.operations +@DslMarker +annotation class KMathContext + /** * Marker interface for any algebra */