119 lines
14 KiB
HTML
119 lines
14 KiB
HTML
<html>
|
|
<head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
|
|
<title>kmath-ast</title>
|
|
</head><body><link href="../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../";</script><script type="text/javascript" src="../scripts/sourceset_dependencies.js" async></script><link href="../styles/style.css" rel="Stylesheet"><link href="../styles/logo-styles.css" rel="Stylesheet"><link href="../styles/jetbrains-mono.css" rel="Stylesheet"><link href="../styles/main.css" rel="Stylesheet"><script type="text/javascript" src="../scripts/clipboard.js" async></script><script type="text/javascript" src="../scripts/navigation-loader.js" async></script><script type="text/javascript" src="../scripts/platform-content-handler.js" async></script><script type="text/javascript" src="../scripts/main.js" async></script>
|
|
|
|
<div id="container">
|
|
<div id="leftColumn"><a href="../index.html">
|
|
<div id="logo"></div>
|
|
</a>
|
|
<div id="paneSearch"></div>
|
|
<div id="sideMenu"></div>
|
|
</div>
|
|
<div id="main">
|
|
<script type="text/javascript" src="../scripts/main.js"></script><div id="leftToggler"><span class="icon-toggler"></span></div>
|
|
|
|
<div class="main-content" id="content" pageids="kmath-ast::////PointingToDeclaration//-1763828843">
|
|
<div class="navigation-wrapper" id="navigation-wrapper">
|
|
<div class="breadcrumbs"><a href="index.html">kmath-ast</a></div>
|
|
<div class="pull-right d-flex">
|
|
<div class="filter-section" id="filter-section"><button class="platform-tag platform-selector common-like" data-active="" data-filter=":kmath-ast:dokkaHtmlPartial/commonMain">common</button><button class="platform-tag platform-selector js-like" data-active="" data-filter=":kmath-ast:dokkaHtmlPartial/jsMain">js</button><button class="platform-tag platform-selector jvm-like" data-active="" data-filter=":kmath-ast:dokkaHtmlPartial/jvmMain">jvm</button></div>
|
|
<div id="searchBar"></div>
|
|
</div>
|
|
</div>
|
|
<div class="cover ">
|
|
<h1 class="cover"><span>kmath-ast</span></h1>
|
|
<div class="platform-hinted UnderCoverText" data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kmath-ast:dokkaHtmlPartial/commonMain"><p class="paragraph">Performance and visualization extensions to MST API.</p><ul><li><p class="paragraph">src/commonMain/kotlin/space/kscience/kmath/ast/parser.kt : Expression language and its parser</p></li><li><p class="paragraph">src/jvmMain/kotlin/space/kscience/kmath/asm/asm.kt : Dynamic MST to JVM bytecode compiler</p></li><li><p class="paragraph">src/jsMain/kotlin/space/kscience/kmath/estree/estree.kt : Dynamic MST to JS compiler</p></li><li><p class="paragraph">src/commonMain/kotlin/space/kscience/kmath/ast/rendering/MathRenderer.kt : Extendable MST rendering</p></li></ul><h2 class=""> Artifact:</h2><p class="paragraph">The Maven coordinates of this project are <code>space.kscience:kmath-ast:0.3.0-dev-17</code>.</p><p class="paragraph">Gradle:</p><div class="sample-container"><code class="" theme="idea"><pre>repositories {<br> maven { url 'https://repo.kotlin.link' }<br> mavenCentral()<br>}<br><br>dependencies {<br> implementation 'space.kscience:kmath-ast:0.3.0-dev-17'<br>}</pre></code></div><p class="paragraph">Gradle Kotlin DSL:</p><div class="sample-container"><code class="" theme="idea"><pre>repositories {<br> maven("https://repo.kotlin.link")<br> mavenCentral()<br>}<br><br>dependencies {<br> implementation("space.kscience:kmath-ast:0.3.0-dev-17")<br>}</pre></code></div><h2 class=""> Dynamic expression code generation</h2><h3 class=""> On JVM</h3><p class="paragraph"><code>kmath-ast</code> JVM module supports runtime code generation to eliminate overhead of tree traversal. Code generator builds a special implementation of <code>Expression<T></code> with implemented <code>invoke</code> function.</p><p class="paragraph">For example, the following builder:</p><div class="sample-container"><code class="" theme="idea"><pre>import space.kscience.kmath.expressions.Symbol.Companion.x<br>import space.kscience.kmath.expressions.*<br>import space.kscience.kmath.operations.*<br>import space.kscience.kmath.asm.*<br><br>MstField { x + 2 }.compileToExpression(DoubleField)</pre></code></div><p class="paragraph">... leads to generation of bytecode, which can be decompiled to the following Java class:</p><div class="sample-container"><code class="" theme="idea"><pre>package space.kscience.kmath.asm.generated;<br><br>import java.util.Map;<br><br>import kotlin.jvm.functions.Function2;<br>import space.kscience.kmath.asm.internal.MapIntrinsics;<br>import space.kscience.kmath.expressions.Expression;<br>import space.kscience.kmath.expressions.Symbol;<br><br>public final class AsmCompiledExpression_45045_0 implements Expression<Double> {<br> private final Object[] constants;<br><br> public final Double invoke(Map<Symbol, ? extends Double> arguments) {<br> return (Double) ((Function2) this.constants[0]).invoke((Double) MapIntrinsics.getOrFail(arguments, "x"), 2);<br> }<br><br> public AsmCompiledExpression_45045_0(Object[] constants) {<br> this.constants = constants;<br> }<br>}</pre></code></div><h4 class=""> Known issues</h4><ul><li><p class="paragraph">The same classes may be generated and loaded twice, so it is recommended to cache compiled expressions to avoid class loading overhead.</p></li><li><p class="paragraph">This API is not supported by non-dynamic JVM implementations (like TeaVM and GraalVM) because of using class loaders.</p></li></ul><h3 class=""> On JS</h3><p class="paragraph">A similar feature is also available on JS.</p><div class="sample-container"><code class="" theme="idea"><pre>import space.kscience.kmath.expressions.Symbol.Companion.x<br>import space.kscience.kmath.expressions.*<br>import space.kscience.kmath.operations.*<br>import space.kscience.kmath.estree.*<br><br>MstField { x + 2 }.compileToExpression(DoubleField)</pre></code></div><p class="paragraph">The code above returns expression implemented with such a JS function:</p><div class="sample-container"><code class="" theme="idea"><pre>var executable = function (constants, arguments) {<br> return constants[1](constants[0](arguments, "x"), 2);<br>};</pre></code></div><p class="paragraph">JS also supports experimental expression optimization with <a href="https://webassembly.org/">WebAssembly</a> IR generation. Currently, only expressions inside <code>DoubleField</code> and <code>IntRing</code> are supported.</p><div class="sample-container"><code class="" theme="idea"><pre>import space.kscience.kmath.expressions.Symbol.Companion.x<br>import space.kscience.kmath.expressions.*<br>import space.kscience.kmath.operations.*<br>import space.kscience.kmath.wasm.*<br><br>MstField { x + 2 }.compileToExpression(DoubleField)</pre></code></div><p class="paragraph">An example of emitted Wasm IR in the form of WAT:</p><div class="sample-container"><code class="" theme="idea"><pre>(func $executable (param $0 f64) (result f64)<br> (f64.add<br> (local.get $0)<br> (f64.const 2)<br> )<br>)</pre></code></div><h4 class=""> Known issues</h4><ul><li><p class="paragraph">ESTree expression compilation uses <code>eval</code> which can be unavailable in several environments.</p></li><li><p class="paragraph">WebAssembly isn't supported by old versions of browsers (see https://webassembly.org/roadmap/).</p></li></ul><h2 class=""> Rendering expressions</h2><p class="paragraph">kmath-ast also includes an extensible engine to display expressions in LaTeX or MathML syntax.</p><p class="paragraph">Example usage:</p><div class="sample-container"><code class="" theme="idea"><pre>import space.kscience.kmath.ast.*<br>import space.kscience.kmath.ast.rendering.*<br>import space.kscience.kmath.misc.*</pre></code></div></div></div>
|
|
</div>
|
|
<h2 class="">Packages</h2>
|
|
<div class="table"><a data-name="1930886389%2FPackages%2F1542328537" anchor-label="space.kscience.kmath.asm" id="1930886389%2FPackages%2F1542328537" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jvmMain"></a>
|
|
<div class="table-row" data-filterable-current=":kmath-ast:dokkaHtmlPartial/jvmMain" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jvmMain">
|
|
<div>
|
|
<div class="main-subrow ">
|
|
<div class=""><span class="inline-flex"><a href="space.kscience.kmath.asm/index.html">space.kscience.kmath.asm</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="1930886389%2FPackages%2F1542328537"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div class="pull-right">
|
|
<div class="platform-tags no-gutters">
|
|
<div class="platform-tag jvm-like">jvm</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
</div>
|
|
<a data-name="72249916%2FPackages%2F353974653" anchor-label="space.kscience.kmath.ast" id="72249916%2FPackages%2F353974653" data-filterable-set=":kmath-ast:dokkaHtmlPartial/commonMain"></a>
|
|
<div class="table-row" data-filterable-current=":kmath-ast:dokkaHtmlPartial/commonMain" data-filterable-set=":kmath-ast:dokkaHtmlPartial/commonMain">
|
|
<div>
|
|
<div class="main-subrow ">
|
|
<div class=""><span class="inline-flex"><a href="space.kscience.kmath.ast/index.html">space.kscience.kmath.ast</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="72249916%2FPackages%2F353974653"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div class="pull-right">
|
|
<div class="platform-tags no-gutters">
|
|
<div class="platform-tag common-like">common</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
</div>
|
|
<a data-name="-622937510%2FPackages%2F353974653" anchor-label="space.kscience.kmath.ast.rendering" id="-622937510%2FPackages%2F353974653" data-filterable-set=":kmath-ast:dokkaHtmlPartial/commonMain"></a>
|
|
<div class="table-row" data-filterable-current=":kmath-ast:dokkaHtmlPartial/commonMain" data-filterable-set=":kmath-ast:dokkaHtmlPartial/commonMain">
|
|
<div>
|
|
<div class="main-subrow ">
|
|
<div class=""><span class="inline-flex"><a href="space.kscience.kmath.ast.rendering/index.html">space.kscience.kmath.ast.rendering</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="-622937510%2FPackages%2F353974653"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div class="pull-right">
|
|
<div class="platform-tags no-gutters">
|
|
<div class="platform-tag common-like">common</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
</div>
|
|
<a data-name="-2000073002%2FPackages%2F-359754593" anchor-label="space.kscience.kmath.estree" id="-2000073002%2FPackages%2F-359754593" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jsMain"></a>
|
|
<div class="table-row" data-filterable-current=":kmath-ast:dokkaHtmlPartial/jsMain" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jsMain">
|
|
<div>
|
|
<div class="main-subrow ">
|
|
<div class=""><span class="inline-flex"><a href="space.kscience.kmath.estree/index.html">space.kscience.kmath.estree</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="-2000073002%2FPackages%2F-359754593"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div class="pull-right">
|
|
<div class="platform-tags no-gutters">
|
|
<div class="platform-tag js-like">js</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
</div>
|
|
<a data-name="452572206%2FPackages%2F-359754593" anchor-label="space.kscience.kmath.wasm" id="452572206%2FPackages%2F-359754593" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jsMain"></a>
|
|
<div class="table-row" data-filterable-current=":kmath-ast:dokkaHtmlPartial/jsMain" data-filterable-set=":kmath-ast:dokkaHtmlPartial/jsMain">
|
|
<div>
|
|
<div class="main-subrow ">
|
|
<div class=""><span class="inline-flex"><a href="space.kscience.kmath.wasm/index.html">space.kscience.kmath.wasm</a><span class="anchor-wrapper"><span class="anchor-icon" pointing-to="452572206%2FPackages%2F-359754593"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div class="pull-right">
|
|
<div class="platform-tags no-gutters">
|
|
<div class="platform-tag js-like">js</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="footer"><span class="go-to-top-icon"><a href="#content"></a></span><span>© 2021 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span></div>
|
|
</div>
|
|
</div>
|
|
|
|
</body></html>
|
|
|
|
|