From 61c1dad4516fe2174f78954352b48ad8f635841b Mon Sep 17 00:00:00 2001 From: "breandan.considine" Date: Thu, 27 Dec 2018 23:06:01 -0500 Subject: [PATCH] clean up readme --- README.md | 63 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 8e07b546a..9dd62a21e 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,54 @@ # KMath -Kotlin MATHematics library is intended as a kotlin based analog of numpy python library. Contrary to `numpy` -and `scipy` it is modular and has a lightweight core. +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. ## Features * **Algebra** - * Mathematical operation entities like rings, spaces and fields with (**TODO** add example to wiki) - * Basic linear algebra operations (summs products, etc) backed by `Space` API. - * Complex numbers backed by `Field` API (meaning that they will be useable in any structures like vectors and NDArrays). - * [In progress] advanced linear algebra operations like matrix inversions. -* **Array-like structures** Full support of numpy-like ndarray including mixed arithmetic operations and function operations -on arrays and numbers just like it works in python (with benefit of static type checking). + * Algebraic structures like rings, spaces and field (**TODO** add example to wiki) + * Basic linear algebra operations (sums, products, etc.), backed by the `Space` API. + * Complex numbers backed by the `Field` API (meaning that they will be usable in any structure like vectors and N-dimensional arrays). + * [In progress] advanced linear algebra operations like matrix inversion and LU decomposition. +* **Array-like structures** Full support of [numpy-like ndarrays](https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.ndarray.html) including mixed arithmetic operations and function operations over arrays and numbers just like in Python (with the added benefit of static type checking). -* **Expressions** Expressions are one of the ultimate goals of kmath. It is planned to be able to write some mathematical -expression once an then apply it to different types of objects by providing different context. Exception could be used -for a wide variety of purposes from high performance calculations to code generation. +* **Expressions** Expressions are one of the ultimate goals of KMath. By writing a single mathematical expression +once, users will be able to apply different types of objects to the expression by providing a context. Exceptions +can be used for a wide variety of purposes from high performance calculations to code generation. ## Planned features * **Common mathematics** 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 suite kotlin programming paradigm. There is no fixed priority list for that. Feel free -to submit a future request if you want something to be done first. +library in Kotlin code and maybe rewrite some parts to better suit the Kotlin programming paradigm, however there is no fixed roadmap for that. Feel free +to submit a feature request if you want something to be done first. * **Messaging** A mathematical notation to support multi-language and multi-node communication for mathematical tasks. ## Multi-platform support -KMath is developed as a multi-platform library, which means that most of interfaces are declared in common module. -Implementation is also done in common module wherever it is possible. In some cases features are delegated to -platform even if they could be done in common module because of platform performance optimization. -Currently the main focus of development is the JVM platform, contribution of implementations for Kotlin - Native and -Kotlin - JS is 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 -The 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 firstly focus on creating convenient universal API and then work on -increasing performance for specific cases. We expect the worst KMath performance still be better than natural 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 should be better than SciPy. ## Releases -The project is currently in pre-release stage. Nightly builds could be used by adding additional repository to (groovy) gradle config: +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 kotlin gradle dsl: + +or for the Gradle Kotlin DSL: ```kotlin repositories { @@ -56,16 +57,20 @@ repositories { } ``` -Then use regular dependency like +Then use a regular dependency like so: + ```groovy compile(group: 'scientifik', name: 'kmath-core', version: '0.0.1-SNAPSHOT') ``` -or in kotlin + +or in the Gradle Kotlin DSL: + ```kotlin compile(group = "scientifik", name = "kmath-core", version = "0.0.1-SNAPSHOT") ``` -Work builds could be obtained with [![](https://jitpack.io/v/altavir/kmath.svg)](https://jitpack.io/#altavir/kmath). +Working builds can be obtained here: [![](https://jitpack.io/v/altavir/kmath.svg)](https://jitpack.io/#altavir/kmath). ## Contributing -The project requires a lot of additional work. Please fill free to contribute in any way and propose new features. + +The project requires a lot of additional work. Please fill free to contribute in any way and propose new features. \ No newline at end of file