sally
1.0.0indexedSolves simple algebraic linear equations, optimizing codebase by reducing multiple formulaic methods into a single function. Supports expressions with unknown variables marked as 'x'.
2
Stars
—
Used by
dependents
—
Health
/ 100
Sally
Sally is a simple solver for Simple Algebraic Linear equations.
Platform-agnostic as a common module in a Kotlin/Multiplatform library.
Installation
Kotlin Multiplatform
// Add Maven Central if needed
repositories {
mavenCentral()
// maven { url = java.net.URI("https://s01.oss.sonatype.org/content/repositories/snapshots") } // for snapshots
}
kotlin {
sourceSets {
commonMain {
dependencies {
implementation(group = "io.github.sikrinick", name = "sally", version = "1.0.0")
}
}
}
}
Kotlin JVM
// Add Maven Central if needed
repositories {
mavenCentral()
// maven { url = java.net.URI("https://s01.oss.sonatype.org/content/repositories/snapshots") } // for snapshots
}
implementation(group = "io.github.sikrinick", name = "sally-jvm", version = "1.0.0")
Kotlin JS
// Add Maven Central if needed
repositories {
mavenCentral()
// maven { url = java.net.URI("https://s01.oss.sonatype.org/content/repositories/snapshots") } // for snapshots
}
implementation(group = "io.github.sikrinick", name = "sally-js", version = "1.0.0")
Kotlin Native
// Add Maven Central if needed
repositories {
mavenCentral()
// maven { url = java.net.URI("https://s01.oss.sonatype.org/content/repositories/snapshots") } // for snapshots
}
implementation(group = "io.github.sikrinick", name = "sally-native", version = "1.0.0")
Why?
Occasionally, even in commercial programming you may run into a problem, which can be represented by a simple equation.
Let's assume, we run a logistic business.
For example, basic business requirement may be to calculate box volume:
fun boxVolume(length: Double, width: Double, height: Double) = length * width * height
The next business requirement may be to calculate length, width or height based on any other 3 known parameters.
fun boxLength(volume: Double, width: Double, height: Double) = volume / width / height
fun boxWidth(volume: Double, length: Double, height: Double) = volume / length / height
= volume / length / width
It is obvious that for the same relationship, which can be represented by a single formula we need 4 methods and tests for each of those.
As an option, we may represent relationship as an expression and delegate methods to that expression.
How-to
Unknown part is marked with an x.
val expr = x - 1
println(expr.solve()) // 1
For explicit conversion of number to expressions use asExpr()
val expr = 10.asExpr() - x * 2.asExpr()
println(expr.solve()) // 5
If there is no x in expression, it will be solved as a simple expression.
val expr = 10.asExpr() - 3 * 2
println(expr.solve()) // 4
Reasoning
Consider common financial formula that represents relationship between Future Value (FV), Present Value (PV), and Periodic Payments (PMT).
Where:
i is an annual rate.
n is a number of years.
m is a number of periods of capitalization of interest per year.
For a simple deposit for 2 years with a rate of 10% and an initial amount of 1000 we would need next formula:
For a credit for 2 years with a rate of 10% and an initial amount of 1000 we may use a set of 2 formulas.
This is not an optimal solution, but it allows us to use same relationship.
Firstly, we have to find FV, the value of a loan in 2 years.
Then, we have to find out monthly payments:
As one can observe, same formula is used in all the examples, but in some cases FV, PV or PMT is equal to zero.
However, as a code naive solution would be represented by 3 methods, one for each unknown variable FV, PV or PMT.
This results in an unnecessary growth of codebase, which can be substituted with a simple algebraic solver for linear equations.
Sally allows to rewrite it as a single function representing logic with a couple of decorating functions.
Performance
Obviously, performance would be lower than a simple version based on Doubles.
Consider next benchmarks, one is using Doubles:
@Benchmark
fun naive_double_performance(): Double {
val pv = 1000.00
val pmt = 100.00
val m =
n =
i = / / m
mn = m * n
pv * ( + i).pow(mn) - pmt * (( + i).pow(mn) - ) / i
}
Another one is using this library:
On a Macbook Pro 2019 it shows next results (the higher the better):
| Double-based | Sally | |
|---|---|---|
| JVM | 26981.54 ops/ms | 1601.96 ops/ms |
Therefore, I suggest using it on a JVM platform, and, probably, Kotlin/Native, not on a JS platform.