Metadata-Version: 2.0
Name: cexprtk
Version: 0.3.1
Summary: Mathematical expression parser: cython wrapper around the 'C++ Mathematical Expression Toolkit Library' 
Home-page: https://bitbucket.org/mjdr/cexprtk
Author: M.J.D. Rushton
Author-email: m.j.d.rushton@gmail.com
License: CPL
Download-URL: https://bitbucket.org/mjdr/cexprtk/get/0.3.1.tar.gz
Description-Content-Type: UNKNOWN
Keywords: math,formula,parser,arithmetic,evaluate
Platform: UNKNOWN
Classifier: License :: OSI Approved :: Common Public License
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Cython
Classifier: Topic :: Scientific/Engineering :: Mathematics

cexprtk: Mathematical Expression Parsing and Evaluation in Python
=================================================================

``cexprtk`` is a cython wrapper around the "`C++ Mathematical Expression
Toolkit Library
(ExprTk) <http://www.partow.net/programming/exprtk/index.html>`__\ " by
Arash Partow. Using ``cexprtk`` a powerful mathematical expression
engine can be incorporated into your python project.

Table of Contents
-----------------

[TOC]

Installation
------------

The latest version of ``cexprtk`` can be installed using
`pip <http://www.pip-installer.org/en/latest/index.html>`__ :

.. code:: bash

        $ pip install cexprtk

**Note:** Installation requires a compatible C++ compiler to be
installed.

Usage
-----

The following examples show the major features of ``cexprtk``.

Example: Evaluate a simple equation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following shows how the arithmetic expression ``(5+5) * 23`` can be
evaluated:

.. code:: python

        >>> import cexprtk
        >>> cexprtk.evaluate_expression("(5+5) * 23", {})
        230.0

Example: Using Variables
~~~~~~~~~~~~~~~~~~~~~~~~

Variables can be used within expressions by passing a dictionary to the
``evaluate_expression`` function. This maps variable names to their
values. The expression from the previous example can be re-calculated
using variable values:

.. code:: python

        >>> import cexprtk
        >>> cexprtk.evaluate_expression("(A+B) * C", {"A" : 5, "B" : 5, "C" : 23})
        230.0

Example: Re-using expressions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When using the ``evaluate_expression()`` function, the mathematical
expression is parsed, evaluated and then immediately thrown away. This
example shows how to re-use an ``Expression`` for multiple evaluations.

-  An expression will be defined to calculate the circumference of
   circle, this will then be re-used to calculate the value for several
   different radii.
-  First a ``Symbol_Table`` is created containing a variable ``r`` (for
   radius), it is also populated with some useful constants such as Ï€.

   .. code:: python

           >>> import cexprtk
           >>> st = cexprtk.Symbol_Table({'r' : 1.0}, add_constants= True)

-  Now an instance of ``Expression`` is created, defining our function:

   .. code:: python

           >>> circumference = cexprtk.Expression('2*pi*r', st)

-  The ``Symbol_Table`` was initialised with ``r=1``, the expression can
   be evaluated for this radius simply by calling it:

   .. code:: python

           >>> circumference()
           6.283185307179586

-  Now update the radius to a value of 3.0 using the dictionary like
   object returned by the ``Symbol_Table``'s ``.variables`` property:

   .. code:: python

           >>> st.variables['r'] = 3.0
           >>> circumference()
           18.84955592153876

Example: Defining an unknown symbol resolver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A callback can be passed to the ``Expression`` constructor through the
``unknown_symbol_resolver_callback`` parameter. This callback is invoked
during expression parsing when a variable or constant is encountered
that isn't in the ``Symbol_Table`` associated with the ``Expression``.

The callback can be used to provide some logic that leads to a new
symbol being registered or for an error condition to be flagged.

**The Problem:** The following example shows a potential use for the
symbol resolver:

-  An expression contains variables of the form ``m_VARIABLENAME`` and
   ``f_VARIABLENAME``.
-  ``m_`` or ``f_`` prefix the actual variable name (perhaps indicating
   gender).
-  ``VARIABLENAME`` should be used to look up the desired value in a
   dictionary.
-  The dictionary value of ``VARIABLENAME`` should then be weighted
   according to its prefix:

   -  ``m_`` variables should be multiplied by 0.8.
   -  ``f_`` variables should be multiplied by 1.1.

**The Solution:**

-  First the ``VARIABLENAME`` dictionary is defined:

   .. code:: python

       variable_values = { 'county_a' : 82, 'county_b' : 76}

-  Now the callback is defined. This takes a single argument, *symbol*,
   which gives the name of the missing variable found in the expression:

   .. code:: python


       def callback(symbol):
           # Tokenize the symbol name into prefix and VARIABLENAME components.
           prefix,variablename = symbol.split("_", 1)
           # Get the value for this VARIABLENAME from the variable_values dict
           value = variable_values[variablename]
           # Find the correct weight for the prefix
           if prefix == 'm':
               weight = 0.8
           elif prefix == 'f':
               weight = 1.1
           else:
               # Flag an error condition if prefix not found.
               errormsg = "Unknown prefix "+ str(prefix)
               return (False, cexprtk.USRSymbolType.VARIABLE, 0.0, errormsg)
           # Apply the weight to the 
           value *= weight
           # Indicate success and return value to cexprtk
           return (True, cexprtk.USRSymbolType.VARIABLE, value, "")

-  All that remains is to register the callback with an instance of
   ``Expression`` and to evaluate an expression. The expression to be
   evaluated is:

   -  ``(m_county_a - f_county_b)``
   -  This should give a value of ``(0.8*82) - (1.1*76) = -18``

   .. code:: python

           >>> st = cexprtk.Symbol_Table({})
           >>> e = cexprtk.Expression("(m_county_a - f_county_b)", st, callback)
           >>> e.value()
           -18.0

--------------

API Reference
-------------

For information about expressions supported by ``cexprtk`` please refer
to the original C++
`ExprTK <http://www.partow.net/programming/exprtk/index.html>`__
documentation:

Class Reference
~~~~~~~~~~~~~~~

class Expression:
^^^^^^^^^^^^^^^^^

Class representing mathematical expression.

-  Following instantiation, the expression is evaluated calling the
   expression or invoking its ``value()`` method.
-  The variable values used by the Expression can be modified through
   the ``variables`` property of the ``Symbol_Table`` instance
   associated with the expression. The ``Symbol_Table`` can be accessed
   using the ``Expression.symbol_table`` property.

Defining unknown symbol-resolver:


The ``unknown_symbol_resolver_callback`` argument to the ``Expression``
constructor accepts a callable which is invoked whenever a symbol (i.e.
a variable or a constant), is not found in the ``Symbol_Table`` given by
the ``symbol_table`` argument. The ``unknown_symbol_resolver_callback``
can be used to provide a value for the missing value or to set an error
condition.

The callable should have following signature:

.. code:: python

        def callback(symbol_name):
            ...

Where ``symbol_name`` is a string identifying the missing symbol.

The callable should return a tuple of the form:

.. code:: python

        (HANDLED_FLAG, USR_SYMBOL_TYPE, SYMBOL_VALUE, ERROR_STRING)

Where:

-  ``HANDLED_FLAG`` is a boolean:

   -  ``True`` indicates that callback was able handle the error
      condition and that ``SYMBOL_VALUE`` should be used for the missing
      symbol.
   -  ``False``, flags and error condition, the reason why the unknown
      symbol could not be resolved by the callback is described by
      ``ERROR_STRING``.

-  ``USR_SYMBOL_TYPE`` gives type of symbol (constant or variable) that
   should be added to the ``symbol_table`` when unkown symbol is
   resolved. Value should be one of those given in
   ``cexprtk.USRSymbolType``. e.g.

   -  ``cexprtk.USRSymbolType.VARIABLE``
   -  ``cexprtk.USRSymbolType.CONSTANT``

-  ``SYMBOL_VALUE``, floating point value that should be used when
   resolving missing symbol.
-  ``ERROR_STRING`` when ``HANDLED_FLAG`` is ``False`` this can be used
   to describe error condition.

def **init**\ (self, *expression*, *symbol\_table*, *unknown\_symbol\_resolver\_callback* = None):
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Instantiate ``Expression`` from a text string giving formula and
``Symbol_Table`` instance encapsulating variables and constants used by
the expression.

**Parameters:**

-  **expression** (*str*) String giving expression to be calculated.
-  **symbol\_table** (*Symbol\_Table*) Object defining variables and
   constants.
-  **unknown\_symbol\_resolver\_callback** (*callable*) See description
   above.

def value(self):
''''''''''''''''

Evaluate expression using variable values currently set within
associated ``Symbol_Table``

**Returns:**

-  (*float*) Value resulting from evaluation of expression.

def **call**\ (self):
'''''''''''''''''''''

Equivalent to calling ``value()`` method.

**Returns:**

-  (*float*) Value resulting from evaluation of expression.

symbol\_table
'''''''''''''

Read only property that returns ``Symbol_Table`` instance associated
with this expression.

**Returns:**

-  (*Symbol\_Table*) ``Symbol_Table`` associated with this
   ``Expression``.

--------------

class Symbol\_Table:
^^^^^^^^^^^^^^^^^^^^

Class for providing variable and constant values to ``Expression``
instances.

def **init**\ (self, *variables*, *constants* = {}, *add\_constants* = False):
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Instantiate ``Symbol_Table`` defining variables and constants for use
with ``Expression`` class.

**Example:**

-  To instantiate a ``Symbol_Table`` with:

   -  ``x = 1``
   -  ``y = 5``
   -  define a constant ``k = 1.3806488e-23``

-  The following code would be used:

   .. code:: python

           st = cexprtk.Symbol_Table({'x' : 1, 'y' : 5}, {'k'= 1.3806488e-23})

**Parameters:**

-  **variables** (*dict*) Mapping between variable name and initial
   variable value.
-  **constants** (*dict*) Dictionary containing values that should be
   added to ``Symbol_Table`` as constants. These can be used a variables
   within expressions but their values cannot be updated following
   ``Symbol_Table`` instantiation.
-  **add\_constants** (*bool*) If ``True``, add the standard constants
   ``pi``, ``inf``, ``epsilon`` to the 'constants' dictionary before
   populating the ``Symbol_Table``

variables
'''''''''

Returns dictionary like object containing variable values.
``Symbol_Table`` values can be updated through this object.

**Example:**

.. code:: python

        >>> import cexprtk
        >>> st = cexprtk.Symbol_Table({'x' : 5, 'y' : 5})
        >>> expression = cexprtk.Expression('x+y', st)
        >>> expression()
        10.0

Update the value of ``x`` in the symbol table and re-evaluate the
expression:

.. code:: python

        >>> expression.symbol_table.variables['x'] = 11.0
        >>> expression()
        16.0

**Returns:**

-  Dictionary like giving variables stored in this ``Symbol_Table``.
   Keys are variables names and these map to variable values.

constants
'''''''''

Property giving constants stored in this ``Symbol_Table``.

**Returns:**

-  Read-only dictionary like object mapping constant names stored in
   ``Symbol_Table`` to their values.

--------------

class USRSymbolType:
^^^^^^^^^^^^^^^^^^^^

Defines constant values used to determine symbol type returned by
``unknown_symbol_resolver_callback`` (see ``Expression`` constructor
documentation for more).

VARIABLE
''''''''

Value that should be returned by an ``unknown_symbol_resolver_callback``
to define a variable.

CONSTANT
''''''''

Value that should be returned by an ``unknown_symbol_resolver_callback``
to define a constant.

--------------

Utility Functions
~~~~~~~~~~~~~~~~~

def check\_expression (*expression*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check that expression can be parsed. If successful do nothing, if
unsuccessful raise ``ParseException``.

**Parameters:**

-  *expression* (*str*) Formula to be evaluated

**Raises:**

-  ``ParseException``: If expression is invalid.

def evaluate\_expression (*expression*, *variables*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Evaluate a mathematical formula using the exprtk library and return
result.

For more information about supported functions and syntax see the
`exprtk C++ library
website <http://www.partow.net/programming/exprtk/index.html>`__.

**Parameters:**

-  **expression** (*str*) Expression to be evaluated.
-  **variables** (*dict*) Dictionary containing variable name, variable
   value pairs to be used in expression.

**Returns:**

-  (*float*): Evaluated expression

**Raises:**

-  ``ParseException``: if *expression* is invalid.

--------------

Authors
-------

Cython wrapper by Michael Rushton (m.j.d.rushton@gmail.com), although
most credit should go to Arash Partow for creating the underlying
`ExprTK <http://www.partow.net/programming/exprtk/index.html>`__
library.

License
-------

``cexprtk`` is released under the same terms as the
`ExprTK <http://www.partow.net/programming/exprtk/index.html>`__ library
the `Common Public License Version
1.0 <http://opensource.org/licenses/cpl1.0.php>`__ (CPL).


