Tutorial-LaTeX_SymPy_Conversion.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<script async src=\"https://www.googletagmanager.com/gtag/js?id=UA-59152712-8\"></script>\n",
    "<script>\n",
    "  window.dataLayer = window.dataLayer || [];\n",
    "  function gtag(){dataLayer.push(arguments);}\n",
    "  gtag('js', new Date());\n",
    "\n",
    "  gtag('config', 'UA-59152712-8');\n",
    "</script>\n",
    "\n",
    "# Convert LaTeX Sentence to SymPy Expression\n",
    "\n",
    "## Author: Ken Sible\n",
    "\n",
    "## The following module will demonstrate a recursive descent parser for LaTeX.\n",
    "\n",
    "### NRPy+ Source Code for this module:\n",
    "1. [latex_parser.py](../edit/latex_parser.py); [\\[**tutorial**\\]](Tutorial-LaTeX_SymPy_Conversion.ipynb) The latex_parser.py script will convert a LaTeX sentence to a SymPy expression using the following function: parse(sentence)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='toc'></a>\n",
    "\n",
    "# Table of Contents\n",
    "$$\\label{toc}$$\n",
    "\n",
    "1. [Step 1](#intro): Introduction: Lexical Analysis and Syntax Analysis\n",
    "1. [Step 2](#sandbox): Demonstration and Sandbox (LaTeX Parser)\n",
    "1. [Step 3](#tensor): Tensor Support with Einstein Notation (WIP)\n",
    "1. [Step 4](#latex_pdf_output): $\\LaTeX$ PDF Output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='intro'></a>\n",
    "\n",
    "# Step 1: Lexical Analysis and Syntax Analysis \\[Back to [top](#toc)\\]\n",
    "$$\\label{intro}$$\n",
    "\n",
    "In the following section, we discuss [lexical analysis](https://en.wikipedia.org/wiki/Lexical_analysis) (lexing) and [syntax analysis](https://en.wikipedia.org/wiki/Parsing) (parsing). In the process of lexical analysis, a lexer will tokenize a character string, called a sentence, using substring pattern matching (or tokenizing). We implemented a regex-based lexer for NRPy+, which does pattern matching using a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) for each token pattern. In the process of syntax analysis, a parser will receive a token iterator from the lexer and build a parse tree containing all syntactic information of the language, as specified by a [formal grammar](https://en.wikipedia.org/wiki/Formal_grammar). We implemented a [recursive descent parser](https://en.wikipedia.org/wiki/Recursive_descent_parser) for NRPy+, which will build a parse tree in [preorder](https://en.wikipedia.org/wiki/Tree_traversal#Pre-order_(NLR)), starting from the root [nonterminal](https://en.wikipedia.org/wiki/Terminal_and_nonterminal_symbols), using a [right recursive](https://en.wikipedia.org/wiki/Left_recursion) grammar. The following right recursive, [context-free grammar](https://en.wikipedia.org/wiki/Context-free_grammar) was written for parsing [LaTeX](https://en.wikipedia.org/wiki/LaTeX), adhering to the canonical (extended) [BNF](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form) notation used for describing a context-free grammar:\n",
    "```\n",
    "<ROOT>          -> <VARIABLE> = <EXPR> | <EXPR>\n",
    "<EXPR>          -> [ - ] <TERM> { ( + | - ) <TERM> }\n",
    "<TERM>          -> <FACTOR> { [ / ] <FACTOR> }\n",
    "<FACTOR>        -> <SUBEXPR> { ^( <SUBEXPR> | {<EXPR>} ) }\n",
    "<SUBEXPR>       -> <OPERAND> | (<EXPR>) | [<EXPR>]\n",
    "<OPERAND>       -> <VARIABLE> | <NUMBER> | <COMMAND>\n",
    "<VARIABLE>      -> <ARRAY> | <SYMBOL> [ _( <SYMBOL> | <INTEGER> ) ]\n",
    "<NUMBER>        -> <RATIONAL> | <DECIMAL> | <INTEGER>\n",
    "<COMMAND>       -> <SQRT> | <FRAC>\n",
    "<SQRT>          -> \\ sqrt [ [<INTEGER>] ] {<EXPR>}\n",
    "<FRAC>          -> \\ frac {<EXPR>} {<EXPR>}\n",
    "<ARRAY>         -> <TENSOR> [ _( <SYMBOL> | {{ <SYMBOL> }} ) [ ^( <SYMBOL> | {{ <SYMBOL> }} ) ]\n",
    "                    | ^( <SYMBOL> | {{ <SYMBOL> }} ) [ _( <SYMBOL> | {{ <SYMBOL> }} ) ] ]\n",
    "```\n",
    "\n",
    "<small>**Source**: Robert W. Sebesta. Concepts of Programming Languages. Pearson Education Limited, 2016.</small>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from latex_parser import * # Import NRPy+ module for lexing and parsing LaTeX\n",
    "from sympy import srepr    # Import SymPy function for expression tree representation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SQRT_CMD, LEFT_BRACE, INTEGER, RIGHT_BRACE, LEFT_PAREN, SYMBOL, PLUS, RATIONAL, RIGHT_PAREN, CARET, INTEGER\n"
     ]
    }
   ],
   "source": [
    "lexer = Lexer(None); lexer.initialize(r'\\sqrt{5}(x + 2/3)^2')\n",
    "print(', '.join(token for token in lexer.tokenize()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "sqrt(5)*(x + 2/3)**2 : Mul(Pow(Integer(5), Rational(1, 2)), Pow(Add(Symbol('x'), Rational(2, 3)), Integer(2)))\n"
     ]
    }
   ],
   "source": [
    "expr = parse(r'\\sqrt{5}(x + 2/3)^2')\n",
    "print(expr, ':', srepr(expr))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='sandbox'></a>\n",
    "\n",
    "# Step 2: Demonstration and Sandbox (LaTeX Parser) \\[Back to [top](#toc)\\]\n",
    "$$\\label{sandbox}$$\n",
    "\n",
    "We implemented a wrapper function for the parse() method that will accept a LaTeX sentence and return a SymPy expression. Furthermore, the entire parsing module was designed for extendibility. We apply the following procedure for extending parser functionality to include an unsupported LaTeX command: append that command to the grammar dictionary in the Lexer class with the mapping regex:token, write a grammar abstraction (similar to a regular expression) for that command, add the associated nonterminal (the command name) to the command abstraction in the Parser class, and finally implement the straightforward (private) method for parsing the grammar abstraction. We shall demonstrate the extension procedure using the `\\sqrt` LaTeX command.\n",
    "\n",
    "```<SQRT> -> sqrt [ [<INTEGER>] ] {<EXPRESSION>}```\n",
    "```\n",
    "def __sqrt(self):\n",
    "\tif self.__accept('LEFT_BRACKET'):\n",
    "\t\troot = self.lexer.word\n",
    "\t\tself.__expect('INTEGER')\n",
    "\t\tself.__expect('RIGHT_BRACKET')\n",
    "\telse: root = 2\n",
    "\tself.__expect('LEFT_BRACE')\n",
    "\texpr = self.__expression()\n",
    "\tself.__expect('RIGHT_BRACE')\n",
    "\treturn 'Pow(%s, Rational(1, %s))' % (expr, root)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "alpha_0**(1/3)\n"
     ]
    }
   ],
   "source": [
    "print(parse(r'\\sqrt[3]{\\alpha_0}'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to expression parsing, we included support for equation parsing, which will return a dictionary mapping LHS $\\mapsto$ RHS where LHS must be a symbol."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'x': 2**(n/2)*n}\n"
     ]
    }
   ],
   "source": [
    "print(parse(r'x = n\\sqrt{2}^n'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'x_1': x + 1, 'x_2': x + 2, 'x_3': x + 3}\n"
     ]
    }
   ],
   "source": [
    "eqn_list = [r'x_1 = x + 1', r'x_2 = x + 2', r'x_3 = x + 3']\n",
    "\n",
    "var_map  = parse(eqn_list[0])\n",
    "for eqn in eqn_list:\n",
    "    var_map.update(parse(eqn))\n",
    "print(var_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We implemented robust error messaging, using the custom `ParseError` exception, which should handle every conceivable case to identify, as detailed as possible, invalid syntax inside of a LaTeX sentence. The following are runnable examples of possible error messages (simply uncomment and run the cell):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "# parse(r'\\sqrt[*]{2}')\n",
    "    # ParseError: \\sqrt[*]{2}\n",
    "    #                   ^\n",
    "    # unexpected '*' at position 6\n",
    "\n",
    "# parse(r'\\sqrt[0.5]{2}')\n",
    "    # ParseError: \\sqrt[0.5]{2}\n",
    "    #                   ^\n",
    "    # expected token INTEGER at position 6\n",
    "\n",
    "# parse(r'\\command{}')\n",
    "    # ParseError: \\command{}\n",
    "    #             ^\n",
    "    # unsupported command '\\command' at position 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the sandbox code cell below, you can experiment with the LaTeX parser using the wrapper function parse(sentence), where sentence must be a [raw string](https://docs.python.org/3/reference/lexical_analysis.html) to interpret a backslash as a literal character rather than an [escape sequence](https://en.wikipedia.org/wiki/Escape_sequence)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Write Sandbox Code Here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='tensor'></a>\n",
    "\n",
    "# Step 3: Tensor Support with Einstein Notation (WIP) \\[Back to [top](#toc)\\]\n",
    "$$\\label{tensor}$$\n",
    "\n",
    "In the following section, we demonstrate the current parser support for tensor notation using the Einstein summation convention. The first example will parse a simple equation for raising an index using the metric tensor, while assuming a 3-dimensional space (i.e. `i` and `j` range over `0, 1, 2`) and $g$ symmetric:\n",
    "$$v^i=g_{ij}v_j.$$\n",
    "The second example will parse an equation for a simple tensor contraction, while assuming $h$ and $R$ are symmetric:\n",
    "$$T=h^{jk}R_{jk}.$$\n",
    "We should mention that a future build of the parser would require a configuration file be specified before parsing a tensorial equation. The process demonstrated below for declaring a tensor, adding that tensor to a namespace, and passing that namespace to the parser would be eliminated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import indexedexp as ixp  # Import NRPy+ module for indexed expressions\n",
    "from sympy import symbols # Import SymPy function for declaring symbols"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'vU': [gUU00*vD0 + gUU01*vD1 + gUU02*vD2, gUU01*vD0 + gUU11*vD1 + gUU12*vD2, gUU02*vD0 + gUU12*vD1 + gUU22*vD2]}\n"
     ]
    }
   ],
   "source": [
    "vD  = ixp.declarerank1('vD', DIM=3)\n",
    "gUU = ixp.declarerank2('gUU', 'sym01', DIM=3)\n",
    "namespace = {'vD': vD, 'gUU': gUU}\n",
    "# The following should be the only user input (in the future) aside from an auto-generated/user-modified configuration.\n",
    "print(parse(r'v^i = g^{ij}v_j', namespace))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'T': RDD00*hUU00 + 2*RDD01*hUU01 + 2*RDD02*hUU02 + RDD11*hUU11 + 2*RDD12*hUU12 + RDD22*hUU22}\n"
     ]
    }
   ],
   "source": [
    "T   = symbols('T', real=True)\n",
    "hUU = ixp.declarerank2('hUU', 'sym01', DIM=3)\n",
    "RDD = ixp.declarerank2('RDD', 'sym01', DIM=3)\n",
    "namespace = {'T': T, 'hUU': hUU, 'RDD': RDD}\n",
    "# The following should be the only user input (in the future) aside from an auto-generated/user-modified configuration.\n",
    "print(parse(r'T = h^{jk}R_{jk}', namespace))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='latex_pdf_output'></a>\n",
    "\n",
    "# Step 4: Output this notebook to $\\LaTeX$-formatted PDF file \\[Back to [top](#toc)\\]\n",
    "$$\\label{latex_pdf_output}$$\n",
    "\n",
    "The following code cell converts this Jupyter notebook into a proper, clickable $\\LaTeX$-formatted PDF file. After the cell is successfully run, the generated PDF may be found in the root NRPy+ tutorial directory, with filename\n",
    "[Tutorial-LaTeX_SymPy_Conversion.pdf](Tutorial-LaTeX_SymPy_Conversion.pdf) (Note that clicking on this link may not work; you may need to open the PDF file through another means.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Created Tutorial-LaTeX_SymPy_Conversion.tex, and compiled LaTeX file to PDF\n",
      "    file Tutorial-LaTeX_SymPy_Conversion.pdf\n"
     ]
    }
   ],
   "source": [
    "import cmdline_helper as cmd    # NRPy+: Multi-platform Python command-line interface\n",
    "cmd.output_Jupyter_notebook_to_LaTeXed_PDF(\"Tutorial-LaTeX_SymPy_Conversion\")"
   ]
  }
 ],
 "metadata": {
  "file_extension": ".py",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.0"
  },
  "mimetype": "text/x-python",
  "name": "python",
  "npconvert_exporter": "python",
  "pygments_lexer": "ipython3",
  "version": 3
 },
 "nbformat": 4,
 "nbformat_minor": 2
}