doc/html/usersguide.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
   7 <title>SympyCore User's Guide</title>
   8 <meta name="authors" content="Pearu Peterson  Fredrik Johansson" />
   9 <style type="text/css">
  10
  11 /*
  12 :Author: Pearu Peterson
  13 :Contact: pearu.peterson AT gmail DOT com
  14 :Copyright: This stylesheet has been placed in the public domain.
  15
  16 Stylesheet for use with Docutils.
  17 */
  18
  19 @import url(html4css1.css);
  20
  21 /* Your customizations go here.  For example: */
  22
  23 body {
  24     margin:0px;
  25     padding:25px;
  26     background-color: #ccc;
  27     font-size: 13px; font-family: arial, sans-serif;
  28     line-height:1.5em;
  29 }
  30
  31 div.document {
  32     max-width: 700px;
  33     color: #000;
  34     background-color: #fff;
  35     padding:25px;
  36     border:5px solid #ddd;
  37 }
  38
  39 div.sidebar {
  40   margin-left: 1em ;
  41   border: medium outset ;
  42   padding: 1em ;
  43   background-color: #ffffee ;
  44   width: 40% ;
  45   float: right ;
  46   clear: right }
  47
  48 div.sidebar p.rubric {
  49   font-family: sans-serif ;
  50   font-size: medium }
  51
  52 p.sidebar-title {
  53   font-family: sans-serif ;
  54   font-weight: bold ;
  55   font-size: larger }
  56
  57 p.sidebar-subtitle {
  58   font-family: sans-serif ;
  59   font-weight: bold }
  60
  61 pre, tt {
  62   font-family: consolas, lucida console, courier new, monospace;
  63   color: #000080 ;
  64 }
  65
  66 pre.literal-block, pre.doctest-block {
  67   line-height:1.3em;
  68   border-top:1px solid #ccc;
  69   border-bottom:1px solid #ccc;
  70   background-color:#f0f0f0;
  71   color: #000080 ;
  72 }
  73
  74 div.admonition, div.attention, div.caution, div.danger, div.error,
  75 div.hint, div.important, div.note, div.tip, div.warning {
  76   margin: 2em ;
  77   border: medium outset ;
  78   padding: 0.5em;
  79   background-color: #fffacd;
  80 }
  81
  82 div.admonition p.admonition-title, div.hint p.admonition-title,
  83 div.important p.admonition-title, div.note p.admonition-title,
  84 div.tip p.admonition-title {
  85   font-weight: bold ;
  86   font-family: sans-serif }
  87
  88 div.attention p.admonition-title, div.caution p.admonition-title,
  89 div.danger p.admonition-title, div.error p.admonition-title,
  90 div.warning p.admonition-title {
  91   color: red ;
  92   font-weight: bold ;
  93   font-family: sans-serif }
  94
  95 </style>
  96 </head>
  97 <body>
  98 <div class="document" id="sympycore-user-s-guide">
  99 <h1 class="title">SympyCore User's Guide</h1>
 100 <table class="docinfo" frame="void" rules="none">
 101 <col class="docinfo-name" />
 102 <col class="docinfo-content" />
 103 <tbody valign="top">
 104 <tr><th class="docinfo-name">Authors:</th>
 105 <td>Pearu Peterson
 106 <br />Fredrik Johansson</td></tr>
 107 <tr class="field"><th class="docinfo-name">Created:</th><td class="field-body">January 2008</td>
 108 </tr>
 109 <tr class="field"><th class="docinfo-name">Website:</th><td class="field-body"><a class="reference" href="http://sympycore.googlecode.com/">http://sympycore.googlecode.com/</a></td>
 110 </tr>
 111 <tr><th class="docinfo-name">Version:</th>
 112 <td>sympycore 0.2-svn.
 113 Other versions: <a class="reference" href="http://sympycore.googlecode.com/svn-history/r818/trunk/doc/html/userguide.html">0.1</a>.</td></tr>
 114 </tbody>
 115 </table>
 116 <!-- -*- rest -*- -->
 117 <!-- To verify examples, use command ``python run_doctest.py`` -->
 118 <!-- To produce HTML file, use command ``rst2html userguide.rst html/userguide.html`` -->
 119 <!-- To produce PDF file, use command ``rst2latex userguide.rst userguide.tex; pdflatex userguide.tex`` -->
 120 <table class="docutils field-list" frame="void" rules="none">
 121 <col class="field-name" />
 122 <col class="field-body" />
 123 <tbody valign="top">
 124 <tr class="field"><th class="field-name">Other formats:</th><td class="field-body"><a class="reference" href="http://sympycore.googlecode.com/svn/trunk/doc/sympycore_usersguide.pdf">PDF</a></td>
 125 </tr>
 126 </tbody>
 127 </table>
 128 <div class="sidebar">
 129 <p class="first sidebar-title">Table of contents</p>
 130 <div class="contents local last topic">
 131 <ul class="auto-toc simple">
 132 <li><a class="reference" href="#introduction" id="id6" name="id6">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
 133 <li><a class="reference" href="#getting-started" id="id7" name="id7">2&nbsp;&nbsp;&nbsp;Getting Started</a></li>
 134 <li><a class="reference" href="#the-cas-model" id="id8" name="id8">3&nbsp;&nbsp;&nbsp;The CAS model</a></li>
 135 <li><a class="reference" href="#package-structure" id="id9" name="id9">4&nbsp;&nbsp;&nbsp;Package structure</a></li>
 136 <li><a class="reference" href="#basic-methods" id="id10" name="id10">5&nbsp;&nbsp;&nbsp;Basic methods</a><ul class="auto-toc">
 137 <li><a class="reference" href="#output-methods" id="id11" name="id11">5.1&nbsp;&nbsp;&nbsp;Output methods</a></li>
 138 <li><a class="reference" href="#conversation-methods" id="id12" name="id12">5.2&nbsp;&nbsp;&nbsp;Conversation methods</a></li>
 139 <li><a class="reference" href="#substitution-of-expressions" id="id13" name="id13">5.3&nbsp;&nbsp;&nbsp;Substitution of expressions</a></li>
 140 <li><a class="reference" href="#pattern-matching" id="id14" name="id14">5.4&nbsp;&nbsp;&nbsp;Pattern matching</a></li>
 141 <li><a class="reference" href="#checking-for-atomic-objects" id="id15" name="id15">5.5&nbsp;&nbsp;&nbsp;Checking for atomic objects</a></li>
 142 </ul>
 143 </li>
 144 <li><a class="reference" href="#verbatim-algebra" id="id16" name="id16">6&nbsp;&nbsp;&nbsp;Verbatim algebra</a></li>
 145 <li><a class="reference" href="#commutative-ring" id="id17" name="id17">7&nbsp;&nbsp;&nbsp;Commutative ring</a><ul class="auto-toc">
 146 <li><a class="reference" href="#operations" id="id18" name="id18">7.1&nbsp;&nbsp;&nbsp;Operations</a></li>
 147 <li><a class="reference" href="#expanding" id="id19" name="id19">7.2&nbsp;&nbsp;&nbsp;Expanding</a></li>
 148 <li><a class="reference" href="#differentation" id="id20" name="id20">7.3&nbsp;&nbsp;&nbsp;Differentation</a></li>
 149 <li><a class="reference" href="#integration" id="id21" name="id21">7.4&nbsp;&nbsp;&nbsp;Integration</a></li>
 150 </ul>
 151 </li>
 152 <li><a class="reference" href="#commutative-ring-implementation" id="id22" name="id22">8&nbsp;&nbsp;&nbsp;Commutative ring implementation</a><ul class="auto-toc">
 153 <li><a class="reference" href="#defining-functions-for-collectingfield" id="id23" name="id23">8.1&nbsp;&nbsp;&nbsp;Defining functions for <tt class="docutils literal"><span class="pre">CollectingField</span></tt></a></li>
 154 </ul>
 155 </li>
 156 <li><a class="reference" href="#calculus" id="id24" name="id24">9&nbsp;&nbsp;&nbsp;Calculus</a></li>
 157 <li><a class="reference" href="#arithemetics" id="id25" name="id25">10&nbsp;&nbsp;&nbsp;Arithemetics</a></li>
 158 <li><a class="reference" href="#polynomials" id="id26" name="id26">11&nbsp;&nbsp;&nbsp;Polynomials</a><ul class="auto-toc">
 159 <li><a class="reference" href="#univariatepolynomial" id="id27" name="id27">11.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt></a></li>
 160 <li><a class="reference" href="#polynomialring" id="id28" name="id28">11.2&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt></a></li>
 161 </ul>
 162 </li>
 163 <li><a class="reference" href="#matrices" id="id29" name="id29">12&nbsp;&nbsp;&nbsp;Matrices</a></li>
 164 <li><a class="reference" href="#canonical-forms-and-suppressed-evaluation" id="id30" name="id30">13&nbsp;&nbsp;&nbsp;Canonical forms and suppressed evaluation</a></li>
 165 </ul>
 166 </div>
 167 </div>
 168 <div class="section">
 169 <h1><a class="toc-backref" href="#id6" id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
 170 <p>The aim of the SympyCore project is to develop a robust, consistent,
 171 and easy to extend Computer Algebra System model for Python.</p>
 172 <p>Editorial notes:
 173 - This document is written in <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> format.</p>
 174 </div>
 175 <div class="section">
 176 <h1><a class="toc-backref" href="#id7" id="getting-started" name="getting-started">2&nbsp;&nbsp;&nbsp;Getting Started</a></h1>
 177 <p>To use SympyCore from Python, one needs to import the <tt class="docutils literal"><span class="pre">sympycore</span></tt> package:</p>
 178 <pre class="literal-block">
 179 &gt;&gt;&gt; from sympycore import *
 180 </pre>
 181 <p>The <tt class="docutils literal"><span class="pre">sympycore</span></tt> package provides <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions to
 182 construct symbolic objects and numbers. By default, the symbolic
 183 objects are the elements of <tt class="docutils literal"><span class="pre">Calculus</span></tt> algebra -- a commutative
 184 ring of symbolic expressions where exponent algebra is also <tt class="docutils literal"><span class="pre">Calculus</span></tt>
 185 algebra.</p>
 186 <pre class="doctest-block">
 187 &gt;&gt;&gt; x = Symbol('x')
 188 &gt;&gt;&gt; n = Number(2,5)
 189 &gt;&gt;&gt; x+n
 190 Calculus('x + 2/5')
 191 &gt;&gt;&gt; x,y,z,v,w=map(Symbol,'xyzvw')
 192 </pre>
 193 <p>To construct expression from a string, use the corresponding algebra
 194 class with one argument. For example,</p>
 195 <pre class="doctest-block">
 196 &gt;&gt;&gt; Calculus('x+y+1/4 + x**2')+x
 197 Calculus('y + x**2 + 1/4 + 2*x')
 198 </pre>
 199 <p>More examples on <tt class="docutils literal"><span class="pre">sympycore</span></tt> features can be found in <a class="reference" href="demo0_1.html">Demo documentation</a>.</p>
 200 </div>
 201 <div class="section">
 202 <h1><a class="toc-backref" href="#id8" id="the-cas-model" name="the-cas-model">3&nbsp;&nbsp;&nbsp;The CAS model</a></h1>
 203 <p>Symbolic expressions represent mathematical concepts like numbers,
 204 constants, variables, functions, operators, and various relations
 205 between them. Symbolic objects, on the other hand, represent symbolic
 206 expressions in a running computer program. The aim of a Computer
 207 Algebra System (CAS) is to provide methods to manipulate symbolic
 208 objects and by that manipulate symbolic expressions. These
 209 manipulations of symbolic expressions have mathematical meaning when
 210 the methods are consistent with the rules and theories from
 211 mathematics.</p>
 212 <p>There are many possible ways to represent a mathematical concept as a
 213 structure of a computer program. SympyCore mimics mathematical
 214 concepts via implementing the corresponding algebra and algebraic
 215 operations in a class, say Algebra, that is derived from the
 216 BasicAlgebra class. So, a symbolic object is an instance of the
 217 Algebra class. This instance contains information about the
 218 mathematical operator that when applied to operands forms the
 219 corresponding symbolic object. The operator and operands of the given
 220 symbolic object can be accessed via atrributes <tt class="docutils literal"><span class="pre">func</span></tt> and
 221 <tt class="docutils literal"><span class="pre">args</span></tt>. The value of <tt class="docutils literal"><span class="pre">func</span></tt> is a callable object and <tt class="docutils literal"><span class="pre">args</span></tt> is a
 222 sequence of symbolic objects. So, if <tt class="docutils literal"><span class="pre">A</span></tt> is a <tt class="docutils literal"><span class="pre">Algebra</span></tt> instance
 223 then:</p>
 224 <pre class="literal-block">
 225 &lt;symbolic object&gt; = A.func(*A.args)
 226 </pre>
 227 <p>The actual value of <tt class="docutils literal"><span class="pre">func</span></tt> is defined by the <tt class="docutils literal"><span class="pre">Algebra</span></tt> class. For
 228 example, in the case of calculus algebra class <tt class="docutils literal"><span class="pre">Calculus</span></tt>, the
 229 <tt class="docutils literal"><span class="pre">func</span></tt> value can be <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>,
 230 etc. If the symbolic object represents a symbol (eg a variable) or a
 231 number of the algebra then <tt class="docutils literal"><span class="pre">func</span></tt> contains a callable that returns the
 232 symbolic object (the <tt class="docutils literal"><span class="pre">args</span></tt> in this case will be an empty sequence).</p>
 233 <p>The symbolic objects representing symbols and numbers can be
 234 constructed via the <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions. Such symbolic
 235 objects are called atomic.  One should note that functions <tt class="docutils literal"><span class="pre">Add</span></tt>,
 236 <tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">Symbol</span></tt>, <tt class="docutils literal"><span class="pre">Number</span></tt>, etc are always specific to
 237 the given algebra (in fact, they are defined as classmethods of the
 238 corresponding algebra class).</p>
 239 <p>While most of the algebra operators assume symbolic objects as their
 240 operands then <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions may take various
 241 Python objects as arguments. For example, the argument to
 242 <tt class="docutils literal"><span class="pre">Calculus.Symbol</span></tt> can be any python object that is immutable (this
 243 requirement comes from the fact terms of sums and factors of products
 244 are internally saved as Python dictionary keys), and the arguments to
 245 <tt class="docutils literal"><span class="pre">Calculus.Number</span></tt> can be Python number types such as <tt class="docutils literal"><span class="pre">int</span></tt>,
 246 <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">complex</span></tt> as well as <tt class="docutils literal"><span class="pre">mpq</span></tt>,
 247 <tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt> instances (these are defined in
 248 <tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt> package).</p>
 249 <p>One can construct symbolic objects from Python strings using algebra
 250 <tt class="docutils literal"><span class="pre">convert</span></tt> class method or algebra constructor with one argument. For
 251 example,</p>
 252 <pre class="doctest-block">
 253 &gt;&gt;&gt; Calculus.convert('a-3/4+b**2')
 254 Calculus('a + b**2 - 3/4')
 255 &gt;&gt;&gt; Calculus('a-3/4+b**2').func
 256 &lt;bound method type.Add of &lt;class 'sympycore.calculus.algebra.Calculus'&gt;&gt;
 257 &gt;&gt;&gt; Calculus('a-3/4+b**2').args
 258 [Calculus('a'), Calculus('-3/4'), Calculus('b**2')]
 259 </pre>
 260 </div>
 261 <div class="section">
 262 <h1><a class="toc-backref" href="#id9" id="package-structure" name="package-structure">4&nbsp;&nbsp;&nbsp;Package structure</a></h1>
 263 <p>SympyCore project provides a python package <tt class="docutils literal"><span class="pre">sympycore</span></tt> that consists of
 264 several modules and subpackages:</p>
 265 <ol class="arabic">
 266 <li><p class="first"><tt class="docutils literal"><span class="pre">core.py</span></tt> - provides a base class <tt class="docutils literal"><span class="pre">Basic</span></tt> to all symbolic
 267 objects. Note that almost any (hashable) python object can be used
 268 as an operand to algebraic operations (assuming the corresponding
 269 algebra class accepts it) and hence it is not always necessary to
 270 derive classes defining some mathematical notion from
 271 <tt class="docutils literal"><span class="pre">Basic</span></tt>. Only classes that could be used by other parts of the
 272 <tt class="docutils literal"><span class="pre">sympycore</span></tt> should be derived from <tt class="docutils literal"><span class="pre">Basic</span></tt>. In such cases,
 273 these classes are available via <tt class="docutils literal"><span class="pre">classes</span></tt> attributes (also
 274 defined in <tt class="docutils literal"><span class="pre">core.py</span></tt>). For example,</p>
 275 <pre class="doctest-block">
 276 &gt;&gt;&gt; from sympycore.core import classes
 277 &gt;&gt;&gt; classes.Calculus
 278 &lt;class 'sympycore.calculus.algebra.Calculus'&gt;
 279 &gt;&gt;&gt; classes.Unit
 280 &lt;class 'sympycore.physics.units.Unit'&gt;
 281 &gt;&gt;&gt; classes.CollectingField
 282 &lt;class 'sympycore.basealgebra.pairs.CollectingField'&gt;
 283 </pre>
 284 </li>
 285 <li><p class="first"><tt class="docutils literal"><span class="pre">arithmetic/</span></tt> - provides <tt class="docutils literal"><span class="pre">mpq</span></tt>, <tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt>,
 286 <tt class="docutils literal"><span class="pre">mpc</span></tt> classes that represent low-level fractions,
 287 multiprecision floating point numbers, and complex numbers with
 288 rational parts. The package defines also <tt class="docutils literal"><span class="pre">Infinity</span></tt> class to
 289 represent extended numbers.</p>
 290 </li>
 291 <li><p class="first"><tt class="docutils literal"><span class="pre">basealgebra/</span></tt> - provides abstract base classes representing
 292 algebras: <tt class="docutils literal"><span class="pre">BasicAlgebra</span></tt>, <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>, etc, and base
 293 classes for algebras with implementations: <tt class="docutils literal"><span class="pre">Primitive</span></tt>,
 294 <tt class="docutils literal"><span class="pre">CollectingField</span></tt>, etc.</p>
 295 </li>
 296 <li><p class="first"><tt class="docutils literal"><span class="pre">calculus/</span></tt> - provides class <tt class="docutils literal"><span class="pre">Calculus</span></tt> that represents the
 297 algebra of symbolic expressions. The <tt class="docutils literal"><span class="pre">Calculus</span></tt> class defines the
 298 default algebra in <tt class="docutils literal"><span class="pre">sympycore</span></tt>. For more information, see
 299 [section on calculus].  <tt class="docutils literal"><span class="pre">calculus/functions/</span></tt> - provides symbolic
 300 functions like <tt class="docutils literal"><span class="pre">exp</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">cos</span></tt>, <tt class="docutils literal"><span class="pre">tan</span></tt>,
 301 <tt class="docutils literal"><span class="pre">cot</span></tt>, <tt class="docutils literal"><span class="pre">sqrt</span></tt>, ...</p>
 302 </li>
 303 <li><p class="first"><tt class="docutils literal"><span class="pre">physics/</span></tt> - provides class <tt class="docutils literal"><span class="pre">Unit</span></tt> that represents the algebra
 304 of symbolic expressions of physical quantities. For more
 305 information, see [section on physics].</p>
 306 </li>
 307 <li><p class="first"><tt class="docutils literal"><span class="pre">polynomials/</span></tt> - provides classes <tt class="docutils literal"><span class="pre">Polynomial</span></tt>,
 308 <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt>, <tt class="docutils literal"><span class="pre">MultivariatePolynomial</span></tt> to represent
 309 the algebras of polynomials with symbols, univariate polynomials in
 310 (coefficient:exponent) form, and multivariate polynomials in
 311 (coefficients:exponents) form, respectively. For more information,
 312 see [section on polynomials].</p>
 313 </li>
 314 </ol>
 315 </div>
 316 <div class="section">
 317 <h1><a class="toc-backref" href="#id10" id="basic-methods" name="basic-methods">5&nbsp;&nbsp;&nbsp;Basic methods</a></h1>
 318 <p>In <tt class="docutils literal"><span class="pre">sympycore</span></tt> all symbolic objects are assumed to be immutable. So,
 319 the manipulation of symbolic objects means creating new symbolic
 320 objects from the parts of existing ones.</p>
 321 <p>There are many methods that can be used to retrive information and
 322 subexpressions from a symbolic object. The most generic method is to
 323 use attribute pair of <tt class="docutils literal"><span class="pre">func</span></tt> and <tt class="docutils literal"><span class="pre">args</span></tt> as described
 324 above. However, many such methods are also algebra specific, for
 325 example, classes of commutative rings have methods like
 326 <tt class="docutils literal"><span class="pre">as_Add_args</span></tt>, <tt class="docutils literal"><span class="pre">as_Mul_args</span></tt>, etc for retriving the operands of
 327 operations and <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, etc for constructing new symbolic
 328 objects representing addition, multiplication, etc operations. For
 329 more information about such methods, see sections describing the
 330 particular algebra classes.</p>
 331 <div class="section">
 332 <h2><a class="toc-backref" href="#id11" id="output-methods" name="output-methods">5.1&nbsp;&nbsp;&nbsp;Output methods</a></h2>
 333 <dl class="docutils">
 334 <dt><tt class="docutils literal"><span class="pre">str(&lt;symbolic</span> <span class="pre">object&gt;)</span></tt></dt>
 335 <dd><p class="first">return a nice string representation of the symbolic object. For example,</p>
 336 <pre class="last doctest-block">
 337 &gt;&gt;&gt; expr = Calculus('-x + 2')
 338 &gt;&gt;&gt; str(expr)
 339 '2 - x'
 340 </pre>
 341 </dd>
 342 <dt><tt class="docutils literal"><span class="pre">repr(&lt;symbolic</span> <span class="pre">object&gt;)</span></tt></dt>
 343 <dd><p class="first">return a string representation of the symbolic object that can be
 344 used to reproduce an equal object:</p>
 345 <pre class="last doctest-block">
 346 &gt;&gt;&gt; expr=Calculus('-x+2')
 347 &gt;&gt;&gt; repr(expr)
 348 &quot;Calculus('2 - x')&quot;
 349 </pre>
 350 </dd>
 351 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_tree()</span></tt></dt>
 352 <dd><p class="first">return a tree string representation of the symbolic object. For example,</p>
 353 <pre class="doctest-block">
 354 &gt;&gt;&gt; expr = Calculus('-x + 2+y**3')
 355 &gt;&gt;&gt; print expr.as_tree()
 356 Calculus:
 357 ADD[
 358   -1:SYMBOL[x]
 359   1:MUL[
 360   1:  3:SYMBOL[y]
 361   1:]
 362   2:NUMBER[1]
 363 ]
 364 </pre>
 365 <p class="last">where the first line shows the name of a algebra class following the
 366 content of the symbolic object in tree form. Note how are
 367 represented the coefficients and exponents of the example
 368 subexpressions.</p>
 369 </dd>
 370 </dl>
 371 </div>
 372 <div class="section">
 373 <h2><a class="toc-backref" href="#id12" id="conversation-methods" name="conversation-methods">5.2&nbsp;&nbsp;&nbsp;Conversation methods</a></h2>
 374 <dl class="docutils">
 375 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_verbatim()</span></tt></dt>
 376 <dd><p class="first">return symbolic object as an instance of <tt class="docutils literal"><span class="pre">Verbatim</span></tt> class. All
 377 algebra classes must implement <tt class="docutils literal"><span class="pre">as_verbatim</span></tt> method as this allows
 378 converting symbolic objects from one algebra to another that is
 379 compatible with respect to algebraic operations. Also, producing the
 380 string representations of symbolic objects is done via converting
 381 them to Verbatim that implements the corresponding printing
 382 method. For example,</p>
 383 <pre class="last doctest-block">
 384 &gt;&gt;&gt; expr
 385 Calculus('2 + y**3 - x')
 386 &gt;&gt;&gt; expr.as_verbatim()
 387 Verbatim('2 + y**3 - x')
 388 </pre>
 389 </dd>
 390 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_algebra(&lt;algebra</span> <span class="pre">class&gt;)</span></tt></dt>
 391 <dd><p class="first">return symbolic object as an instance of given algebra class. The
 392 transformation is done by first converting the symbolic object to
 393 <tt class="docutils literal"><span class="pre">Verbatim</span></tt> instance which in turn is converted to the instance
 394 of targer algebra class by executing the corresponding target
 395 algebra operators on operands. For example,</p>
 396 <pre class="last doctest-block">
 397 &gt;&gt;&gt; expr = Calculus('-x + 2')
 398 &gt;&gt;&gt; print expr.as_tree()
 399 Calculus:
 400 ADD[
 401   -1:SYMBOL[x]
 402   2:NUMBER[1]
 403 ]
 404 &gt;&gt;&gt; print expr.as_algebra(Verbatim).as_tree()
 405 Verbatim:
 406 ADD[
 407   NEG[
 408     SYMBOL[x]
 409   ]
 410   NUMBER[2]
 411 ]
 412 &gt;&gt;&gt; print expr.as_algebra(CollectingField).as_tree()
 413 CollectingField:
 414 ADD[
 415   -1:SYMBOL[x]
 416   2:NUMBER[1]
 417 ]
 418 </pre>
 419 </dd>
 420 </dl>
 421 </div>
 422 <div class="section">
 423 <h2><a class="toc-backref" href="#id13" id="substitution-of-expressions" name="substitution-of-expressions">5.3&nbsp;&nbsp;&nbsp;Substitution of expressions</a></h2>
 424 <dl class="docutils">
 425 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs(&lt;sub-expr&gt;,</span> <span class="pre">&lt;new-expr&gt;)</span></tt></dt>
 426 <dd><p class="first">return a copy of <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;</span></tt> with all occurances of
 427 <tt class="docutils literal"><span class="pre">&lt;sub-expr&gt;</span></tt> replaced with <tt class="docutils literal"><span class="pre">&lt;new-expr&gt;</span></tt>. For example,</p>
 428 <pre class="last doctest-block">
 429 &gt;&gt;&gt; expr = Calculus('-x + 2+y**3')
 430 &gt;&gt;&gt; expr
 431 Calculus('2 + y**3 - x')
 432 &gt;&gt;&gt; expr.subs('y', '2*z')
 433 Calculus('2 + 8*z**3 - x')
 434 </pre>
 435 </dd>
 436 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs([(&lt;subexpr1&gt;,</span> <span class="pre">&lt;newexpr1&gt;),</span> <span class="pre">(&lt;subexpr2&gt;,</span> <span class="pre">&lt;newexpr2&gt;),</span> <span class="pre">...])</span></tt></dt>
 437 <dd><p class="first">is equivalent to <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs(&lt;subexp1&gt;,</span>
 438 <span class="pre">&lt;newexpr1&gt;).subs(&lt;subexpr2&gt;,</span> <span class="pre">&lt;newexpr2&gt;).subs</span></tt>. For example,</p>
 439 <pre class="last doctest-block">
 440 &gt;&gt;&gt; expr
 441 Calculus('2 + y**3 - x')
 442 &gt;&gt;&gt; expr.subs([('y', '2*z'),('z', 2)])
 443 Calculus('66 - x')
 444 </pre>
 445 </dd>
 446 </dl>
 447 </div>
 448 <div class="section">
 449 <h2><a class="toc-backref" href="#id14" id="pattern-matching" name="pattern-matching">5.4&nbsp;&nbsp;&nbsp;Pattern matching</a></h2>
 450 <dl class="docutils">
 451 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.match(&lt;pattern-expr&gt;</span> <span class="pre">[,</span> <span class="pre">&lt;wildcard1&gt;,</span> <span class="pre">&lt;wildcard2&gt;</span> <span class="pre">...])</span></tt></dt>
 452 <dd><p class="first">check if the give symbolic object matches given pattern. Pattern
 453 expression may contain wild symbols that match arbitrary
 454 expressions, the <tt class="docutils literal"><span class="pre">wildcard</span></tt> must be then the corresponding
 455 symbol. Wild symbols can be matched also conditionally, then the
 456 <tt class="docutils literal"><span class="pre">&lt;wildcard&gt;</span></tt> argument must be a tuple <tt class="docutils literal"><span class="pre">(&lt;wild-symbol&gt;,</span> <span class="pre">&lt;predicate&gt;)</span></tt>,
 457 where <tt class="docutils literal"><span class="pre">&lt;predicate&gt;</span></tt> is a single-argument function returning <tt class="docutils literal"><span class="pre">True</span></tt> if
 458 wild symbol matches the expression in argument. If the match is not
 459 found then the method returns. Otherwise it will return a dictionary
 460 object such that the following condition holds:</p>
 461 <pre class="literal-block">
 462 pattern.subs(expr.match(pattern, ...).items()) == expr
 463 </pre>
 464 <p>For example,</p>
 465 <pre class="last doctest-block">
 466 &gt;&gt;&gt; expr = 3*x + 4*y
 467 &gt;&gt;&gt; pattern = v*x + w*y
 468 &gt;&gt;&gt; d = expr.match(pattern, v, w)
 469 &gt;&gt;&gt; print 'v=',d.get(v)
 470 v= 3
 471 &gt;&gt;&gt; print 'w=',d.get(w)
 472 w= 4
 473 &gt;&gt;&gt; pattern.subs(d.items())==expr
 474 True
 475 </pre>
 476 </dd>
 477 </dl>
 478 </div>
 479 <div class="section">
 480 <h2><a class="toc-backref" href="#id15" id="checking-for-atomic-objects" name="checking-for-atomic-objects">5.5&nbsp;&nbsp;&nbsp;Checking for atomic objects</a></h2>
 481 <p>A symbolic object is atomic if <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.args</span> <span class="pre">==</span> <span class="pre">()</span></tt>.</p>
 482 <dl class="docutils">
 483 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.symbols</span></tt></dt>
 484 <dd>is a property that holds a set of all atomic symbols in the given
 485 symbolic expression.</dd>
 486 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.has(&lt;symbol&gt;)</span></tt></dt>
 487 <dd>returns <tt class="docutils literal"><span class="pre">True</span></tt> if the symbolic expression contains <tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt>.</dd>
 488 </dl>
 489 </div>
 490 </div>
 491 <div class="section">
 492 <h1><a class="toc-backref" href="#id16" id="verbatim-algebra" name="verbatim-algebra">6&nbsp;&nbsp;&nbsp;Verbatim algebra</a></h1>
 493 <p>Verbatim algebra elements are symbolic expressions that are not
 494 simplified in anyway when performing operatons. For example,</p>
 495 <pre class="doctest-block">
 496 &gt;&gt;&gt; s=Verbatim('s')
 497 &gt;&gt;&gt; s+s
 498 Verbatim('s + s')
 499 </pre>
 500 </div>
 501 <div class="section">
 502 <h1><a class="toc-backref" href="#id17" id="commutative-ring" name="commutative-ring">7&nbsp;&nbsp;&nbsp;Commutative ring</a></h1>
 503 <p>In SympyCore a commutative ring is represented by an abstract class
 504 <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>.  The <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt> class defines support
 505 for addition, substraction, multiplication, division, and
 506 exponentiation operations.</p>
 507 <div class="section">
 508 <h2><a class="toc-backref" href="#id18" id="operations" name="operations">7.1&nbsp;&nbsp;&nbsp;Operations</a></h2>
 509 <p>Classes deriving from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt> must define a number of
 510 method pairs <tt class="docutils literal"><span class="pre">(Operation,</span> <span class="pre">as_Operation_args)</span></tt> that satisfy the
 511 following condition:</p>
 512 <pre class="literal-block">
 513 cls.Operation(*obj.as_Operation_args()) == obj
 514 </pre>
 515 <p>Here <tt class="docutils literal"><span class="pre">Operation</span></tt> can be <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Terms</span></tt>, <tt class="docutils literal"><span class="pre">Factors</span></tt>,
 516 <tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">Log</span></tt>. For example,</p>
 517 <pre class="doctest-block">
 518 &gt;&gt;&gt; print map(str, (2*x+y).as_Add_args())
 519 ['y', '2*x']
 520 &gt;&gt;&gt; print map(str, (2*x+y).as_Mul_args())
 521 ['y + 2*x']
 522 &gt;&gt;&gt; print map(str, (2*x+y).as_Pow_args())
 523 ['y + 2*x', '1']
 524 &gt;&gt;&gt; print (2*x+y).as_Terms_args()
 525 [(Calculus('y'), 1), (Calculus('x'), 2)]
 526 </pre>
 527 </div>
 528 <div class="section">
 529 <h2><a class="toc-backref" href="#id19" id="expanding" name="expanding">7.2&nbsp;&nbsp;&nbsp;Expanding</a></h2>
 530 <p>Expanding means applying distributivity law to open parenthesis.</p>
 531 <dl class="docutils">
 532 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.expand()</span></tt></dt>
 533 <dd><p class="first">return an expanded expression. For example,</p>
 534 <pre class="last doctest-block">
 535 &gt;&gt;&gt; expr = x*(y+x)**2
 536 &gt;&gt;&gt; print expr
 537 x*(x + y)**2
 538 &gt;&gt;&gt; print expr.expand()
 539 x**3 + 2*y*x**2 + x*y**2
 540 </pre>
 541 </dd>
 542 </dl>
 543 </div>
 544 <div class="section">
 545 <h2><a class="toc-backref" href="#id20" id="differentation" name="differentation">7.3&nbsp;&nbsp;&nbsp;Differentation</a></h2>
 546 <dl class="docutils">
 547 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.diff(*symbols)</span></tt></dt>
 548 <dd><p class="first">return a derivative of symbolic expression with respect to given
 549 symbols. The diff methods argument can also be a positive integer
 550 after some symbol argument. Then the derivative is computed given
 551 number of times with respect to the last symbol.
 552 For example,</p>
 553 <pre class="last doctest-block">
 554 &gt;&gt;&gt; print sin(x*y).diff(x)
 555 y*cos(x*y)
 556 &gt;&gt;&gt; print sin(x*y).diff(x).diff(y)
 557 cos(x*y) - x*y*sin(x*y)
 558 &gt;&gt;&gt; print sin(x*y).diff(x,4)
 559 sin(x*y)*y**4
 560 </pre>
 561 </dd>
 562 </dl>
 563 </div>
 564 <div class="section">
 565 <h2><a class="toc-backref" href="#id21" id="integration" name="integration">7.4&nbsp;&nbsp;&nbsp;Integration</a></h2>
 566 <dl class="docutils">
 567 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.integrate(&lt;symbol&gt;,</span> <span class="pre">integrator=None)</span></tt></dt>
 568 <dd><p class="first">return an antiderivative of a symbolic expression with respect to
 569 <tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt>.
 570 For example,</p>
 571 <pre class="last doctest-block">
 572 &gt;&gt;&gt; from sympycore import *
 573 &gt;&gt;&gt; print (x**2 + x*y).integrate(x)
 574 1/2*y*x**2 + 1/3*x**3
 575 </pre>
 576 </dd>
 577 <dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.integrate((&lt;symbol&gt;,</span> <span class="pre">&lt;a&gt;,</span> <span class="pre">&lt;b&gt;)</span></tt></dt>
 578 <dd><p class="first">return a defined integral of a symbolic expression with respect to
 579 <tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt> over the interval <tt class="docutils literal"><span class="pre">[&lt;a&gt;,</span> <span class="pre">&lt;b&gt;]</span></tt>.
 580 For example,</p>
 581 <pre class="last doctest-block">
 582 &gt;&gt;&gt; from sympycore import *
 583 &gt;&gt;&gt; print (x**2 + x*y).integrate(x)
 584 1/2*y*x**2 + 1/3*x**3
 585 &gt;&gt;&gt; print (x**2 + x*y).integrate((x, 1, 3))
 586 26/3 + 4*y
 587 </pre>
 588 </dd>
 589 </dl>
 590 </div>
 591 </div>
 592 <div class="section">
 593 <h1><a class="toc-backref" href="#id22" id="commutative-ring-implementation" name="commutative-ring-implementation">8&nbsp;&nbsp;&nbsp;Commutative ring implementation</a></h1>
 594 <p>Commutative ring operations are implemented in the class
 595 <tt class="docutils literal"><span class="pre">CollectingField</span></tt> (derived from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>).</p>
 596 <p>The class <tt class="docutils literal"><span class="pre">CollectingField</span></tt> holds two attributes, <tt class="docutils literal"><span class="pre">head</span></tt>
 597 and <tt class="docutils literal"><span class="pre">data</span></tt>. The attribute <tt class="docutils literal"><span class="pre">head</span></tt> defines the meaning of the
 598 attribute <tt class="docutils literal"><span class="pre">data</span></tt> content:</p>
 599 <ol class="arabic simple">
 600 <li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==SYMBOL</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is treated as an element
 601 of the ring. Usually <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is a Python string object but
 602 in general it can be any hashable Python object.</li>
 603 <li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==NUMBER</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is treated as a
 604 number element of the ring, that is, an element that can be
 605 represented as <em>one * n</em> where <em>one</em> is unit element of the ring
 606 and <em>n</em> is a number saved in <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt>. Usually <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt>
 607 is a Python <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">complex</span></tt> object but it
 608 can be also any other number-like object that supports arithmetic
 609 operations with Python numbers. An examples are <tt class="docutils literal"><span class="pre">mpq</span></tt>,
 610 <tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt> classes defined in <tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt>
 611 package.</li>
 612 <li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==TERMS</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains a Python
 613 dictionary holding the pairs <tt class="docutils literal"><span class="pre">(&lt;ring</span> <span class="pre">element&gt;,</span> <span class="pre">&lt;coefficient&gt;)</span></tt>.
 614 The values of <tt class="docutils literal"><span class="pre">&lt;coefficients&gt;</span></tt> can be Python numbers or
 615 number-like objects or elements of some other ring (for example,
 616 see <tt class="docutils literal"><span class="pre">Unit</span></tt> class where the coefficients are <tt class="docutils literal"><span class="pre">Calculus</span></tt>
 617 instances). For example, if <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is <tt class="docutils literal"><span class="pre">{x:2,</span> <span class="pre">y:1}</span></tt> then
 618 <tt class="docutils literal"><span class="pre">&lt;obj&gt;</span></tt> represents an expression <em>y + 2*x</em>.</li>
 619 <li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==FACTORS</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains a Python
 620 dictionary holding the pairs <tt class="docutils literal"><span class="pre">(&lt;ring</span> <span class="pre">element&gt;,</span> <span class="pre">&lt;exponent&gt;)</span></tt>.  The
 621 values of <tt class="docutils literal"><span class="pre">&lt;coefficients&gt;</span></tt> can be Python numbers of number-like
 622 objects or elements of some ring (for exapmle, see <tt class="docutils literal"><span class="pre">Calculus</span></tt>
 623 class where the exponents can also be <tt class="docutils literal"><span class="pre">Calculus</span></tt> instances).</li>
 624 <li>If <tt class="docutils literal"><span class="pre">callable(&lt;obj&gt;.head)</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;</span></tt> represents an applied
 625 function where <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head</span></tt> contains a callable object that
 626 performs evaluation and <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains an argument
 627 instance (for example, an instance of some algebra elements)
 628 or a Python <tt class="docutils literal"><span class="pre">tuple</span></tt> containing argument instances.</li>
 629 </ol>
 630 <p>The constants <tt class="docutils literal"><span class="pre">SYMBOL</span></tt>, <tt class="docutils literal"><span class="pre">NUMBER</span></tt>, <tt class="docutils literal"><span class="pre">TERMS</span></tt>, <tt class="docutils literal"><span class="pre">FACTORS</span></tt> are defined
 631 in <tt class="docutils literal"><span class="pre">sympycore/utils.py</span></tt>.</p>
 632 <p>For example,</p>
 633 <pre class="doctest-block">
 634 &gt;&gt;&gt; from sympycore.utils import head_to_string
 635 &gt;&gt;&gt; head_to_string[x.head]
 636 'SYMBOL'
 637 &gt;&gt;&gt; x.data
 638 'x'
 639 &gt;&gt;&gt; head_to_string[(x+y).head]
 640 'ADD'
 641 &gt;&gt;&gt; (x+y).data == {x:1,y:1}
 642 True
 643 &gt;&gt;&gt; head_to_string[(x**y).head]
 644 'MUL'
 645 &gt;&gt;&gt; (x**y).data
 646 {Calculus('x'): Calculus('y')}
 647 &gt;&gt;&gt; sin(x).head
 648 &lt;class 'sympycore.calculus.functions.elementary.sin'&gt;
 649 &gt;&gt;&gt; sin(x).data
 650 Calculus('x')
 651 </pre>
 652 <div class="section">
 653 <h2><a class="toc-backref" href="#id23" id="defining-functions-for-collectingfield" name="defining-functions-for-collectingfield">8.1&nbsp;&nbsp;&nbsp;Defining functions for <tt class="docutils literal"><span class="pre">CollectingField</span></tt></a></h2>
 654 <p>The representation of an applied function within the class
 655 <tt class="docutils literal"><span class="pre">CollectingField</span></tt> can hold any Python callable object that
 656 satisfies the following basic condition: it must return an instance of
 657 a algebra class. The instance may represent an evaluated result of
 658 applying the function to its arguments, or when evaluation is not
 659 possible, then it return <tt class="docutils literal"><span class="pre">&lt;algebra</span> <span class="pre">class&gt;(&lt;arguments&gt;,</span>
 660 <span class="pre">head=&lt;callable&gt;)</span></tt>.</p>
 661 <p>For example, let us define a customized sinus function:</p>
 662 <pre class="doctest-block">
 663 &gt;&gt;&gt; def mysin(x):
 664 ...     if x==0:
 665 ...         return x
 666 ...     return Calculus(mysin, x)
 667 ...
 668 &gt;&gt;&gt; mysin(0)
 669 0
 670 &gt;&gt;&gt; print mysin(x+y)
 671 mysin(x + y)
 672 </pre>
 673 </div>
 674 </div>
 675 <div class="section">
 676 <h1><a class="toc-backref" href="#id24" id="calculus" name="calculus">9&nbsp;&nbsp;&nbsp;Calculus</a></h1>
 677 <p>The default algebra of symbolic expressions with commutative ring
 678 operations is represented by the <tt class="docutils literal"><span class="pre">Calculus</span></tt> class (derived from
 679 <tt class="docutils literal"><span class="pre">CollectingField</span></tt>). The <tt class="docutils literal"><span class="pre">Calculus</span></tt> class can handle
 680 rational numbers represented by the <tt class="docutils literal"><span class="pre">mpq</span></tt> class, multi-precision
 681 floating point numbers represented by the <tt class="docutils literal"><span class="pre">mpf</span></tt> class, and
 682 rational complex numbers represented by the <tt class="docutils literal"><span class="pre">mpqc</span></tt> class.</p>
 683 <p>The <tt class="docutils literal"><span class="pre">sympycore.calculus.functions</span></tt> package defines the following
 684 symbolic functions: <tt class="docutils literal"><span class="pre">sqrt</span></tt>, <tt class="docutils literal"><span class="pre">exp</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">cos</span></tt>,
 685 <tt class="docutils literal"><span class="pre">tan</span></tt>, <tt class="docutils literal"><span class="pre">cot</span></tt>. It also provides <tt class="docutils literal"><span class="pre">Calculus</span></tt> based interfaces to
 686 constants <tt class="docutils literal"><span class="pre">E</span></tt>, <tt class="docutils literal"><span class="pre">pi</span></tt>, and symbols <tt class="docutils literal"><span class="pre">I</span></tt>, <tt class="docutils literal"><span class="pre">oo</span></tt>, <tt class="docutils literal"><span class="pre">moo</span></tt>, <tt class="docutils literal"><span class="pre">zoo</span></tt>,
 687 <tt class="docutils literal"><span class="pre">undefined</span></tt>.</p>
 688 </div>
 689 <div class="section">
 690 <h1><a class="toc-backref" href="#id25" id="arithemetics" name="arithemetics">10&nbsp;&nbsp;&nbsp;Arithemetics</a></h1>
 691 <p>The <tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt> package is not an algebra package but it
 692 implements fractions, multi-precision floating point numbers, rational
 693 complex numbers, and <a class="reference" href="evaluation_rules.html#extended-numbers">extended numbers</a>. In addition, it implements
 694 various algorithms from number theory and provides methods to compute
 695 the values of constants like pi and Eulers number, etc.</p>
 696 </div>
 697 <div class="section">
 698 <h1><a class="toc-backref" href="#id26" id="polynomials" name="polynomials">11&nbsp;&nbsp;&nbsp;Polynomials</a></h1>
 699 <p>The <tt class="docutils literal"><span class="pre">sympycore.polynomials</span></tt> package has two different
 700 implementations for polynomials: <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> and
 701 <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt>.</p>
 702 <div class="section">
 703 <h2><a class="toc-backref" href="#id27" id="univariatepolynomial" name="univariatepolynomial">11.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt></a></h2>
 704 <p>The <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> class stores polynomial coefficients in a
 705 Python tuple. The exponents are implicitly defined as indices of the
 706 list so that the degree of a polynomial is equal to the length of the
 707 list minus 1. <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> is most efficient for
 708 manipulating low order and dense polynomials. To specify the variable
 709 symbol of a polynomial, use <tt class="docutils literal"><span class="pre">symbol</span></tt> keyword argument (default
 710 variable symbol is <tt class="docutils literal"><span class="pre">x</span></tt>).</p>
 711 <pre class="doctest-block">
 712 &gt;&gt;&gt; poly([4,3,2,1])
 713 4 + 3*x + 2*x**2 + x**3
 714 &gt;&gt;&gt; poly([4,3,2,1]).degree
 715 3
 716 &gt;&gt;&gt; poly([4,3,2,1],symbol='y')
 717 4 + 3*y + 2*y**2 + y**3
 718 </pre>
 719 <p>Coefficients can be arbitrary symbolic expressions:</p>
 720 <pre class="doctest-block">
 721 &gt;&gt;&gt; poly([2,y+1,y+z])
 722 2 + ((1 + y))*x + ((y + z))*x**2
 723 </pre>
 724 </div>
 725 <div class="section">
 726 <h2><a class="toc-backref" href="#id28" id="polynomialring" name="polynomialring">11.2&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt></a></h2>
 727 <p>The <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> based classes store polynomial exponenets and
 728 coefficients information in a Python dictionary object where keys are
 729 exponenents (in univariate case Python integers, in multivariate case
 730 <tt class="docutils literal"><span class="pre">AdditiveTuple</span></tt> instances) and values are coefficients.
 731 <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> is most efficient for manipulating sparse
 732 polynomials.  The coefficients belong to specified ring (default ring
 733 is <tt class="docutils literal"><span class="pre">Calculus</span></tt>).</p>
 734 <p>The <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> class (derived from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>) is
 735 a base class to various polynomial rings with different coefficent
 736 rings and different number of variables. To create a class
 737 representing a polynomial element with variables <tt class="docutils literal"><span class="pre">(X,</span> <span class="pre">Y,</span> <span class="pre">..)</span></tt> and
 738 with <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> coefficients, use one of the following constructions:</p>
 739 <pre class="literal-block">
 740 PolynomialRing[(X, Y, ..), &lt;ring&gt;]
 741 PolynomialRing[&lt;int&gt;, &lt;ring&gt;]
 742 </pre>
 743 <p>where nonnegative <tt class="docutils literal"><span class="pre">&lt;int&gt;</span></tt> specifies the number of variables (default
 744 symbols are then <tt class="docutils literal"><span class="pre">X0</span></tt>, <tt class="docutils literal"><span class="pre">X1</span></tt>, etc). The <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> argument can be
 745 omitted, then <tt class="docutils literal"><span class="pre">Calculus</span></tt> is used as a default ring.  Variables can
 746 be arbitrary symbolic expressions.</p>
 747 <p>For example,</p>
 748 <pre class="doctest-block">
 749 &gt;&gt;&gt; polyXY = PolynomialRing[('X', 'Y'), Calculus]
 750 &gt;&gt;&gt; polyXY
 751 &lt;class 'sympycore.polynomials.algebra.PolynomialRing[(X, Y), Calculus]'&gt;
 752 </pre>
 753 <p>To create a polynomial with given exponents and coefficients pairs,
 754 the <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> constructor accepts dictinary objects
 755 containing the corresponding pairs:</p>
 756 <pre class="doctest-block">
 757 &gt;&gt;&gt; polyXY.convert({(0,0):4, (2,1):3, (0,3):2})
 758 PolynomialRing[(X, Y), Calculus]('3*X**2*Y + 2*Y**3 + 4')
 759 </pre>
 760 <p>Univariate polynomials can also be constructed from a list in the same
 761 way as <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> instances were constructed above:</p>
 762 <pre class="doctest-block">
 763 &gt;&gt;&gt; PolynomialRing[1].convert([4,3,2,1])
 764 PolynomialRing[X0, Calculus]('X0**3 + 2*X0**2 + 3*X0 + 4')
 765 </pre>
 766 </div>
 767 </div>
 768 <div class="section">
 769 <h1><a class="toc-backref" href="#id29" id="matrices" name="matrices">12&nbsp;&nbsp;&nbsp;Matrices</a></h1>
 770 <p>The <tt class="docutils literal"><span class="pre">sympycore.matrices</span></tt> package defines <tt class="docutils literal"><span class="pre">MatrixRing</span></tt> that is base
 771 class to matrix algebras. Matrix algebras are represented as classes
 772 (derived from <tt class="docutils literal"><span class="pre">MatrixRing</span></tt>) parametrized with matrix shape and
 773 element ring (default ring is <tt class="docutils literal"><span class="pre">Calculus</span></tt>). To create a matrix
 774 ring, use the following constructs:</p>
 775 <pre class="literal-block">
 776 MatrixRing[&lt;shape&gt;, &lt;ring&gt;]
 777 SquareMatrix[&lt;size&gt;, &lt;ring&gt;]
 778 PermutationMatrix[&lt;size&gt;]
 779 </pre>
 780 <p>where <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> can be omitted, then <tt class="docutils literal"><span class="pre">Calculus</span></tt> is used as a
 781 default element ring.</p>
 782 <p>For example,</p>
 783 <pre class="doctest-block">
 784 &gt;&gt;&gt; m=MatrixRing[3,4]({})
 785 &gt;&gt;&gt; print m
 786  0  0  0  0
 787  0  0  0  0
 788  0  0  0  0
 789 &gt;&gt;&gt; m[1,2] = 3
 790 &gt;&gt;&gt; m[2,3] = 4
 791 &gt;&gt;&gt; print m
 792  0  0  0  0
 793  0  0  3  0
 794  0  0  0  4
 795 </pre>
 796 <p>The content of the matrix is stored as a dictionary containing
 797 pairs <tt class="docutils literal"><span class="pre">(&lt;rowindex&gt;,&lt;column-index&gt;):</span> <span class="pre">&lt;non-zero</span> <span class="pre">element&gt;</span></tt>.</p>
 798 <p>Matrix instances can be constructed from Python dictionary or from a
 799 Python list:</p>
 800 <pre class="doctest-block">
 801 &gt;&gt;&gt; print MatrixRing[2,2]({(0,0):1,(0,1):2,(1,1):3})
 802  1  2
 803  0  3
 804 &gt;&gt;&gt; print MatrixRing[2,2]([[1,2],[3,4]])
 805  1  2
 806  3  4
 807 </pre>
 808 <p>Permutation matrices can be constructed from a sequence of
 809 integers:</p>
 810 <pre class="doctest-block">
 811 &gt;&gt;&gt; print PermutationMatrix([1,0,2])
 812  0  1  0
 813  1  0  0
 814  0  0  1
 815 </pre>
 816 <p>Use <tt class="docutils literal"><span class="pre">random()</span></tt> classmethod to construct matrices with random
 817 content:</p>
 818 <pre class="doctest-block">
 819 &gt;&gt;&gt; print SquareMatrix[2].random()         #doctest: +SKIP
 820  -1  3
 821   3  0
 822 &gt;&gt;&gt; print SquareMatrix[2].random((10,20))  #doctest: +SKIP
 823  15  10
 824  13  15
 825 </pre>
 826 </div>
 827 <div class="section">
 828 <h1><a class="toc-backref" href="#id30" id="canonical-forms-and-suppressed-evaluation" name="canonical-forms-and-suppressed-evaluation">13&nbsp;&nbsp;&nbsp;Canonical forms and suppressed evaluation</a></h1>
 829 <p>See also <a class="reference" href="evaluation_rules.html">Automatic evaluation rules of symbolic expressions</a>.</p>
 830 <p>The <tt class="docutils literal"><span class="pre">Calculus</span></tt> algebra automatically applies some transformations to
 831 expressions. The purpose of these transformations is to permit quick
 832 recognition of mathematically equivalent expressions.
 833 Sums and products of numbers are always evaluated, and
 834 multiples/powers of identical subexpressions are automatically
 835 collected together.  Rational factors are also automatically
 836 distributed over sums. For example, the following transformations
 837 are performed automatically:</p>
 838 <pre class="literal-block">
 839 2*3 -&gt; 6
 840
 841 x+x -&gt; 2*x
 842
 843 x*x -&gt; x**2
 844
 845 2*(x+y) -&gt; 2*x + 2*y
 846 </pre>
 847 <p>An expression to which default transformations have been applied is
 848 said to be in canonical or normalized form. The enforcement of
 849 canonical forms is important for performance reasons as it ensures that,
 850 in many important basic cases, expressions that are mathematically
 851 equivalent will be recognized directly as equal no matter in what
 852 form they were entered, without the need to apply additional
 853 transformations. The default transformations described above
 854 ensure that for example the following expressions cancel completely:</p>
 855 <pre class="literal-block">
 856 2*3 - 6 -&gt; 0
 857
 858 x+x - (2*x) -&gt; 0
 859
 860 x*x - x**2 -&gt; 0
 861
 862 2*(x-y) + 2*(y-x) -&gt; 0
 863 </pre>
 864 <p>Ideally we would like the canonical form to be the simplest
 865 expression possible, e.g.:</p>
 866 <pre class="literal-block">
 867 cos(x)**2 + sin(x)**2 -&gt; 1
 868 </pre>
 869 <p>Automatically generating the simplest possible form is not always
 870 possible, as some expressions have multiple valid representations that
 871 may each be useful in different contexts. E.g.: <tt class="docutils literal"><span class="pre">cos(2*x)</span></tt> and
 872 <tt class="docutils literal"><span class="pre">cos(x)**2</span> <span class="pre">-</span> <span class="pre">sin(x)**2</span></tt>. In general, detecting whether two expressions are
 873 equal is not even algorithmically decidable, and even when it is
 874 possible, the required simplifications can be extremely computationally
 875 expensive (and unpredictably so).</p>
 876 <p>Default transformations are limited to performing operations cases that
 877 are fast and have predictable behavior. To perform more expensive
 878 simplifications, one should explicitly invoke <tt class="docutils literal"><span class="pre">simplify()</span></tt> or, depending on
 879 the desired form, special-purpose rewriting functions like <tt class="docutils literal"><span class="pre">collect()</span></tt>,
 880 <tt class="docutils literal"><span class="pre">apart()</span></tt>, etc (note: these are not yet implemented in SympyCore).</p>
 881 <p>It can sometimes be useful to bypass automatic transformations, for
 882 example to keep the expression <tt class="docutils literal"><span class="pre">2*(x+y)</span></tt> in factored form. The most
 883 general way to achieve this is to use the <tt class="docutils literal"><span class="pre">Verbatim</span></tt> class
 884 (which performs no simplifications whatsoever) instead of <tt class="docutils literal"><span class="pre">Calculus</span></tt>.</p>
 885 <blockquote>
 886 <pre class="doctest-block">
 887 &gt;&gt;&gt; Verbatim('2*(x+pi)')
 888 Verbatim('2*(x + pi)')
 889 </pre>
 890 </blockquote>
 891 <p>You can also construct non-canonical <tt class="docutils literal"><span class="pre">Calculus</span></tt> instances by manually
 892 passing data to the <tt class="docutils literal"><span class="pre">Calculus</span></tt> constructor. For example:</p>
 893 <blockquote>
 894 <pre class="doctest-block">
 895 &gt;&gt;&gt; p = Calculus(utils.TERMS, {(pi+x):2})
 896 &gt;&gt;&gt; print p
 897 2*(pi + x)
 898 </pre>
 899 </blockquote>
 900 <p>It is important to note that some <tt class="docutils literal"><span class="pre">Calculus</span></tt> functions assume the input to
 901 be in canonical form. Although they should never break (i.e. generate
 902 invalid results) when given noncanonical input, they may fail to simplify
 903 results. For example, <tt class="docutils literal"><span class="pre">sin</span></tt> assumes its argument to be flattened such that
 904 if it contains an integer multiple of pi that can be eliminated, this term
 905 will be available at the top of the expression. Thus:</p>
 906 <blockquote>
 907 <pre class="doctest-block">
 908 &gt;&gt;&gt; sin(2*(pi+x))  # sin(2*pi + 2*x)
 909 Calculus('sin(2*x)')
 910 &gt;&gt;&gt; sin(p)
 911 Calculus('sin(2*(pi + x))')
 912 </pre>
 913 </blockquote>
 914 <p>To canonize an expression, either use the function XXX or convert it to
 915 <tt class="docutils literal"><span class="pre">Verbatim</span></tt> and then back to <tt class="docutils literal"><span class="pre">Calculus</span></tt>.</p>
 916 <blockquote>
 917 <pre class="doctest-block">
 918 &gt;&gt;&gt; Calculus(Verbatim(p))
 919 Calculus('2*pi + 2*x')
 920 </pre>
 921 </blockquote>
 922 </div>
 923 </div>
 924 </body>
 925 </html>