build based on 1dcb314

previews/PR596/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.3","generation_timestamp":"2024-05-14T18:20:46","documenter_version":"1.4.1"}}
+{"documenter":{"julia_version":"1.10.3","generation_timestamp":"2024-05-14T18:49:43","documenter_version":"1.4.1"}}

previews/PR596/index.html

@@ -14,4 +14,4 @@
 expr1 + expr2</code></pre><p>SymbolicUtils automatically simplifies</p><pre><code class="language-julia hljs">2w + 3w - 3z + α</code></pre><p>and reorders</p><pre><code class="language-julia hljs">(z + w)*(α + β)</code></pre><p>expressions of type <code>Symbolic{&lt;:Number}</code> (which includes <code>Sym{Real}</code>) when they are created. It also does constant elimination (including rational numbers)</p><pre><code class="language-julia hljs">5 + 2w - 3z + α - (β + 5//3) + 3w - 2 + 3//2 * β</code></pre><p>It&#39;s worth remembering that the expression may be transformed with respect to the input when it&#39;s created.</p><h2 id="Function-like-symbols"><a class="docs-heading-anchor" href="#Function-like-symbols">Function-like symbols</a><a id="Function-like-symbols-1"></a><a class="docs-heading-anchor-permalink" href="#Function-like-symbols" title="Permalink"></a></h2><p>Symbols can be defined to behave like functions. Both the input and output types for the function can be specified. Any application to that function will only admit either values of those types or symbols of the same <code>symtype</code>.</p><pre><code class="language-julia hljs">using SymbolicUtils
 @syms f(x) g(x::Real, y::Real)::Real
 
-f(z) + g(1, α) + sin(w)</code></pre><p>This does not work since <code>z</code> is a <code>Number</code>, not a <code>Real</code>.</p><pre><code class="language-julia hljs">g(1, z)</code></pre><p>This works because <code>g</code> &quot;returns&quot; a <code>Real</code>.</p><pre><code class="language-julia hljs">g(2//5, g(1, β))</code></pre><h2 id="Expression-interface"><a class="docs-heading-anchor" href="#Expression-interface">Expression interface</a><a id="Expression-interface-1"></a><a class="docs-heading-anchor-permalink" href="#Expression-interface" title="Permalink"></a></h2><p>Symbolic expressions are of type <code>Term{T}</code>, <code>Add{T}</code>, <code>Mul{T}</code>, <code>Pow{T}</code> or <code>Div{T}</code> and denote some function call where one or more arguments are themselves such expressions or <code>Sym</code>s. See more about the representation <a href="/representation/">here</a>.</p><p>All the expression types support the following:</p><ul><li><code>istree(x)</code> – always returns <code>true</code> denoting, <code>x</code> is not a leaf node like Sym or a literal.</li><li><code>operation(x)</code> – the function being called</li><li><code>arguments(x)</code> – a vector of arguments</li><li><code>symtype(x)</code> – the &quot;inferred&quot; type (<code>T</code>)</li></ul><p>See more on the interface <a href="/interface">here</a></p><h2 id="Term-rewriting"><a class="docs-heading-anchor" href="#Term-rewriting">Term rewriting</a><a id="Term-rewriting-1"></a><a class="docs-heading-anchor-permalink" href="#Term-rewriting" title="Permalink"></a></h2><p>SymbolicUtils contains <a href="/rewrite/#rule-based_rewriting">a rule-based rewriting language</a> for easy pattern matching and rewriting of expression. There is also a <a href="/rewrite/#composing_rewriters">combinator library</a> to combine rules to chain, branch and loop over rules.</p><h2 id="Simplification"><a class="docs-heading-anchor" href="#Simplification">Simplification</a><a id="Simplification-1"></a><a class="docs-heading-anchor-permalink" href="#Simplification" title="Permalink"></a></h2><p>By default <code>+</code>, <code>*</code> and <code>^</code> operations apply the most basic simplification upon construction of the expression.</p><p>The rules with which the canonical form of <code>Symbolic{&lt;:Number}</code> terms are constructed are the next (where <code>x isa Symbolic</code> and <code>c isa Number</code>)</p><ul><li><code>0 + x</code>, <code>1 * x</code> and <code>x^1</code> always gives <code>x</code></li><li><code>0 * x</code> always gives <code>0</code> and <code>x ^ 0</code> gives <code>1</code></li><li><code>-x</code> becomes <code>(-1)*x</code></li><li>commutativity and associativity over <code>+</code> and <code>*</code> are assumed. Re-ordering of terms will be done under a <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/ordering.jl">total order</a></li><li><code>p/q * x</code> or <code>x * p/q</code> results in <code>(p*x)/q</code></li><li><code>p/q * x/y</code> results in <code>(p*x)/(q*y)</code></li><li><code>x + ... + x</code> will be fused into <code>n*x</code> with type <code>Mul</code></li><li><code>x * ... * x</code> will be fused into <code>x^n</code> with type <code>Pow</code></li><li>sum of <code>Add</code>&#39;s are fused</li><li>product of <code>Mul</code>&#39;s are fused</li><li><code>c * (c₁x₁ + ... + cₙxₙ)</code> will be converted into <code>c*c₁*x₁ + ... + c*cₙ*xₙ</code></li><li><code>(x₁^c₁ * ... * xₙ^cₙ)^c</code> will be converted into <code>x₁^(c*c₁) * ... * xₙ^(c*cₙ)</code></li><li>there are come other simplifications on construction that you can check <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/methods.jl">here</a></li></ul><p>Here is an example of this</p><pre><code class="language-julia hljs">2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1)</code></pre><p>The <code>simplify</code> function applies a built-in set of rules to rewrite expressions in order to simplify it.</p><pre><code class="language-julia hljs">simplify(2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1))</code></pre><p>The rules in the default simplify applies simple constant elimination and trigonometric identities.</p><p>If you read the previous section on the rules DSL, you should be able to read and understand the <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/simplify_rules.jl">rules</a> that are used by <code>simplify</code>.</p><h2 id="Code-generation"><a class="docs-heading-anchor" href="#Code-generation">Code generation</a><a id="Code-generation-1"></a><a class="docs-heading-anchor-permalink" href="#Code-generation" title="Permalink"></a></h2><p><strong>Experimental feature</strong></p><p>It is common to want to generate executable code from symbolic expressions and blocks of them. We are working on experimental support for turning Symbolic expressions into executable functions with specific focus on array input and output and performance which is critical to the Differential Equations ecosystem which is making heavy use of this package.</p><p>See <a href="/codegen/">Code generation</a> for more about this.</p><h2 id="Learn-more"><a class="docs-heading-anchor" href="#Learn-more">Learn more</a><a id="Learn-more-1"></a><a class="docs-heading-anchor-permalink" href="#Learn-more" title="Permalink"></a></h2><p>If you have a package that you would like to utilize rule-based rewriting in, look at the suggestions in the <a href="/interface/">Interfacing</a> section to find out how you can do that without any fundamental changes to your package. Look at the <a href="/api/">API documentation</a> for docstrings about specific functions or macros.</p><p>Head over to the github repository to ask questions and <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl">report problems</a>! Join the <a href="https://julialang.zulipchat.com/#narrow/stream/236639-symbolic-programming">Zulip stream</a> to chat!</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="manual/representation/">Term representation and simplification »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.4.1 on <span class="colophon-date" title="Tuesday 14 May 2024 18:20">Tuesday 14 May 2024</span>. Using Julia version 1.10.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+f(z) + g(1, α) + sin(w)</code></pre><p>This does not work since <code>z</code> is a <code>Number</code>, not a <code>Real</code>.</p><pre><code class="language-julia hljs">g(1, z)</code></pre><p>This works because <code>g</code> &quot;returns&quot; a <code>Real</code>.</p><pre><code class="language-julia hljs">g(2//5, g(1, β))</code></pre><h2 id="Expression-interface"><a class="docs-heading-anchor" href="#Expression-interface">Expression interface</a><a id="Expression-interface-1"></a><a class="docs-heading-anchor-permalink" href="#Expression-interface" title="Permalink"></a></h2><p>Symbolic expressions are of type <code>Term{T}</code>, <code>Add{T}</code>, <code>Mul{T}</code>, <code>Pow{T}</code> or <code>Div{T}</code> and denote some function call where one or more arguments are themselves such expressions or <code>Sym</code>s. See more about the representation <a href="/representation/">here</a>.</p><p>All the expression types support the following:</p><ul><li><code>istree(x)</code> – always returns <code>true</code> denoting, <code>x</code> is not a leaf node like Sym or a literal.</li><li><code>operation(x)</code> – the function being called</li><li><code>arguments(x)</code> – a vector of arguments</li><li><code>symtype(x)</code> – the &quot;inferred&quot; type (<code>T</code>)</li></ul><p>See more on the interface <a href="/interface">here</a></p><h2 id="Term-rewriting"><a class="docs-heading-anchor" href="#Term-rewriting">Term rewriting</a><a id="Term-rewriting-1"></a><a class="docs-heading-anchor-permalink" href="#Term-rewriting" title="Permalink"></a></h2><p>SymbolicUtils contains <a href="/rewrite/#rule-based_rewriting">a rule-based rewriting language</a> for easy pattern matching and rewriting of expression. There is also a <a href="/rewrite/#composing_rewriters">combinator library</a> to combine rules to chain, branch and loop over rules.</p><h2 id="Simplification"><a class="docs-heading-anchor" href="#Simplification">Simplification</a><a id="Simplification-1"></a><a class="docs-heading-anchor-permalink" href="#Simplification" title="Permalink"></a></h2><p>By default <code>+</code>, <code>*</code> and <code>^</code> operations apply the most basic simplification upon construction of the expression.</p><p>The rules with which the canonical form of <code>Symbolic{&lt;:Number}</code> terms are constructed are the next (where <code>x isa Symbolic</code> and <code>c isa Number</code>)</p><ul><li><code>0 + x</code>, <code>1 * x</code> and <code>x^1</code> always gives <code>x</code></li><li><code>0 * x</code> always gives <code>0</code> and <code>x ^ 0</code> gives <code>1</code></li><li><code>-x</code> becomes <code>(-1)*x</code></li><li>commutativity and associativity over <code>+</code> and <code>*</code> are assumed. Re-ordering of terms will be done under a <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/ordering.jl">total order</a></li><li><code>p/q * x</code> or <code>x * p/q</code> results in <code>(p*x)/q</code></li><li><code>p/q * x/y</code> results in <code>(p*x)/(q*y)</code></li><li><code>x + ... + x</code> will be fused into <code>n*x</code> with type <code>Mul</code></li><li><code>x * ... * x</code> will be fused into <code>x^n</code> with type <code>Pow</code></li><li>sum of <code>Add</code>&#39;s are fused</li><li>product of <code>Mul</code>&#39;s are fused</li><li><code>c * (c₁x₁ + ... + cₙxₙ)</code> will be converted into <code>c*c₁*x₁ + ... + c*cₙ*xₙ</code></li><li><code>(x₁^c₁ * ... * xₙ^cₙ)^c</code> will be converted into <code>x₁^(c*c₁) * ... * xₙ^(c*cₙ)</code></li><li>there are come other simplifications on construction that you can check <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/methods.jl">here</a></li></ul><p>Here is an example of this</p><pre><code class="language-julia hljs">2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1)</code></pre><p>The <code>simplify</code> function applies a built-in set of rules to rewrite expressions in order to simplify it.</p><pre><code class="language-julia hljs">simplify(2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1))</code></pre><p>The rules in the default simplify applies simple constant elimination and trigonometric identities.</p><p>If you read the previous section on the rules DSL, you should be able to read and understand the <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/simplify_rules.jl">rules</a> that are used by <code>simplify</code>.</p><h2 id="Code-generation"><a class="docs-heading-anchor" href="#Code-generation">Code generation</a><a id="Code-generation-1"></a><a class="docs-heading-anchor-permalink" href="#Code-generation" title="Permalink"></a></h2><p><strong>Experimental feature</strong></p><p>It is common to want to generate executable code from symbolic expressions and blocks of them. We are working on experimental support for turning Symbolic expressions into executable functions with specific focus on array input and output and performance which is critical to the Differential Equations ecosystem which is making heavy use of this package.</p><p>See <a href="/codegen/">Code generation</a> for more about this.</p><h2 id="Learn-more"><a class="docs-heading-anchor" href="#Learn-more">Learn more</a><a id="Learn-more-1"></a><a class="docs-heading-anchor-permalink" href="#Learn-more" title="Permalink"></a></h2><p>If you have a package that you would like to utilize rule-based rewriting in, look at the suggestions in the <a href="/interface/">Interfacing</a> section to find out how you can do that without any fundamental changes to your package. Look at the <a href="/api/">API documentation</a> for docstrings about specific functions or macros.</p><p>Head over to the github repository to ask questions and <a href="https://github.com/JuliaSymbolics/SymbolicUtils.jl">report problems</a>! Join the <a href="https://julialang.zulipchat.com/#narrow/stream/236639-symbolic-programming">Zulip stream</a> to chat!</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="manual/representation/">Term representation and simplification »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.4.1 on <span class="colophon-date" title="Tuesday 14 May 2024 18:49">Tuesday 14 May 2024</span>. Using Julia version 1.10.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>