{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation of the Julia Tropical Algebra Toolbox and its usage within Jupyter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Tropical Algebra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The algebra (max,+) (pronounced max-plus) redefines the addition and multiplication operators of classical algebra by respectively the maximum operators noted $\\oplus$ and addition noted $\\otimes$ in the domain of real numbers $\\mathbb{R}$ increased by the number minus infinity ($\\varepsilon = -\\infty$) which we call $\\mathbb{R}_{\\varepsilon} = \\mathbb{R} \\cup \\{ -\\infty \\}$. Its algebraic structure is that of a selective-invertible dioid according to the Gondran-Minoux classification (this structure is more frequently called idempotent semi-field) $(\\mathbb{R}_{\\varepsilon}, \\oplus, \\otimes)$.\n",
    "\n",
    "$$\\forall a,b \\in \\mathbb{R}_{\\varepsilon}: a \\oplus b \\triangleq \\max(a,b)$$\n",
    "$$\\forall a,b \\in \\mathbb{R}_{\\varepsilon}: a \\otimes b \\triangleq a + b$$\n",
    "\n",
    "Algebra (min,+) (pronounced min-plus) redefines the addition and multiplication operators of classical algebra by respectively the minimum operators noted $\\oplus$ and addition noted $\\otimes$ in the domain of real numbers $\\mathbb{R}$ increased by the number plus infinity ($\\varepsilon = +\\infty$) which is called $\\mathbb{R}_{\\varepsilon} = \\mathbb{R} \\cup \\{ +\\infty \\}$. Its algebraic structure is that of a selective-invertible dioid according to the Gondran-Minoux classification (this structure is more frequently called idempotent semi-field) $(\\mathbb{R}_{\\varepsilon}, \\oplus, \\otimes)$.\n",
    "\n",
    "$$\\forall a,b \\in \\mathbb{R}_{\\varepsilon}: a \\oplus b \\triangleq \\min(a,b)$$\n",
    "$$\\forall a,b \\in \\mathbb{R}_{\\varepsilon}: a \\otimes b \\triangleq a + b$$\n",
    "\n",
    "Max-Plus or Min-Plus algebras are sometimes referred to as tropical.\n",
    "\n",
    "The interest of matrix calculation in this algebra is taught as early as the 1960s by J. Kuntzman in his network theory. It is used in many fields Operational research (network theory), Physics (Quantification), Probability (Cramer transform), Automation (discrete event systems), Computer science (automata theory, Petri nets), Mathematics (algebraic geometry ). You can consult the [bibliography](../docs/src/bibliography.md) for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Toolkits for Tropical Algebra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One of the first Max-Plus toolkits available was provided by [INRIA](https://www.inria.fr) with the Scilab software which became [ScicosLab](http://www.scicoslab.org) (fork) and then its replacement [NSP](https://cermics.enpc.fr/~jpc/nsp-tiddly/mine.html). The essential purpose of this toolkit is to facilitate matrix calculations in this algebra and takes advantage of the book [SYNCHRONIZATION AND LINEARITY: An Algebra for Discrete Event Systems](https://www.rocq.inria.fr/metalau/cohen/SED/book-online.html).\n",
    "\n",
    "Since Scilab is no longer maintained by their original authors (retried), the Max-Plus toolbox is also no longer maintained. This current [GitHub MaxPlus.jl repository](https://github.com/Lecrapouille/MaxPlus.jl) is offering you a port for the Julia language. This toolbox is also available directly within the Julia's packager system with the command `] add MaxPlus`. Note that initially, this toolbox was only to focus on the (max,+) algebra (since Silab only focus on max+ and this project was a pure portage) but one thing leading to another, functions for algebra (min,+) have been introduced (with version >= 0.3.0) but the name of the package `MaxPlus.jl` hasn't changed.\n",
    "\n",
    "For information, there is another Julia package [TropicalNumbers.jl](https://github.com/TensorBFS/TropicalNumbers.jl) (in active development) as well as a toolbox for Matlab http://www.stanczyk.pro/mpa/ (whose development seems to be abandoned). But none of them is a port of the Scilab toolbox.\n",
    "\n",
    "This current document will only show how to install the `MaxPlus.jl` toolbox and use it inside a Jupyter notebook document. The following tutorials will show you the different functions offered by this toolbox while introducing the basics of (max,+) and (min,+) algebras as well as applications related to these algebras."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing Julia Max-Plus.jl Toolbox"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This Max-Plus toolkit should work with all versions of Julia even the obsolete ones (v0.4, v0.7). Some versions of Julia bring fixes (on sparse matrices: v1.3), others bring regressions (v1.0: identity matrix; v1.4: sparse matrix matrix product with full matrix; v1.5: display of sparse matrices as well as dense matrices). Other bugs are old (> 3 years) and are not yet totally fixed (on version 1.8) but fixes are automatically applied with this Max-Plus package. They may affect other packages you will use. For more information, see the file `fallbacks.jl`. Normally the version of Julia >= 1.9 should contain all fixes for detected bugs by the author of this toolbox.\n",
    "\n",
    "First let's check Julia's version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "v\"1.8.1\""
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "VERSION"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To install the Max-Plus Julia toolbox, you have several options. The following codes do not work directly from this Jupyter document, but works well inside the Julia interactive mode REPL:\n",
    "\n",
    "\n",
    "- Either from the Julia package manager. This will install the stable version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This does not work with Jupyter! This will only works within the REPL:\n",
    "# using Pkg; Pkg.add(\"MaxPlus\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Either, you can download the source code version from [GitHub](https://github.com/Lecrapouille/MaxPlus.jl):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This does not work with Jupyter! This will only works within the REPL:\n",
    "# using Pkg; Pkg.add(PackageSpec(url=\"https://github.com/Lecrapouille/MaxPlus.jl\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Either, my preferred solution for peopling desiring to help developint this toolbox. From a Linux console download:\n",
    "\n",
    "```\n",
    "git clone https://github.com/Lecrapouille/MaxPlus.jl\n",
    "cd MaxPlus.jl\n",
    "julia\n",
    "```\n",
    "\n",
    "**It is important to be correctly placed in the MaxPlus.jl root folder!**\n",
    "\n",
    "Then, inside Julia REPL, invoke the Julia package system `]` and type the following line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This does not work with Jupyter! This will only works within the REPL:\n",
    "# (@v1.8) pkg> add ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use Max-Plus from a Jupyter document\n",
    "\n",
    "Since the Max-Plus package has been installed in your Julia system, it can be used from the Julia REPL via `using MaxPlus` but it will be more pleasant to use it in a Jupyter document. To do this, simply launch a Jupyter notebook from the REPL before the toolkit loads. Here are the commands to type from your REPL from the root folder `MaxPlus.jl`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# From the Julia REPL:\n",
    "# using IJulia\n",
    "# notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a new Jupyter document, remember to check that your document is connected to Julia. Then in this created Jupyter document, load the Max-Plus toolkit from the `MaxPlus.jl` folder:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mPrecompiling MaxPlus [41177cfe-c387-11e9-2806-edd030e4594e]\n"
     ]
    }
   ],
   "source": [
    "push!(LOAD_PATH, pwd())\n",
    "using MaxPlus"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's type in our first Max-Plus number:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(max,+) 5"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "MP(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's type in our first Min-Plus number:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(min,+) 5"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "MI(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This toolbox allows to generate code $\\LaTeX$ via the `Base.show`. In Jupyter, this mode seems to be the one used by default, but here, we prefer to keep the display in plain text. To do this, you must first type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "Base.show(io::IO, ::MIME\"text/latex\", x::MP) = show(io, MIME\"text/plain\", x)\n",
    "Base.show(io::IO, ::MIME\"text/latex\", A::MPAbstractVecOrMat) = show(io, MIME\"text/plain\", A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Next Tutorials\n",
    "\n",
    "If you see the expecteed results, you can continue with other tutorials introducing you the API of the toolbox as well as the different tropical algebras."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.8.1",
   "language": "julia",
   "name": "julia-1.8"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.8.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}