"""
Writing mathematical expressions
================================
An introduction to writing mathematical expressions in Matplotlib.
You can use a subset TeX markup in any matplotlib text string by
placing it inside a pair of dollar signs ($).
Note that you do not need to have TeX installed, since matplotlib
ships its own TeX expression parser, layout engine and fonts. The
layout engine is a fairly direct adaptation of the layout algorithms
in Donald Knuth's TeX, so the quality is quite good (matplotlib also
provides a ``usetex`` option for those who do want to call out to TeX
to generate their text (see :ref:`sphx_glr_tutorials_text_usetex.py`).
"""
###############################################################################
# Any text element can use math text. You should use raw strings (precede the
# quotes with an ``'r'``), and surround the math text with dollar signs ($), as in
# TeX. Regular text and mathtext can be interleaved within the same string.
# Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts
# (from (La)TeX), `STIX `_ fonts (with are designed
# to blend well with Times), or a Unicode font that you provide. The mathtext
# font can be selected with the customization variable ``mathtext.fontset`` (see
# :ref:`sphx_glr_tutorials_introductory_customizing.py`)
#
# .. note::
# On `"narrow" `_ builds
# of Python, if you use the STIX fonts you should also set
# ``ps.fonttype`` and ``pdf.fonttype`` to 3 (the default), not 42.
# Otherwise `some characters will not be visible
# `_.
#
# Here is a simple example::
#
# # plain text
# plt.title('alpha > beta')
#
# produces "alpha > beta".
#
# Whereas this::
#
# # math text
# plt.title(r'$\alpha > \beta$')
#
# produces ":math:`\alpha > \beta`".
#
# .. note::
# Mathtext should be placed between a pair of dollar signs ($). To
# make it easy to display monetary values, e.g., "$100.00", if a
# single dollar sign is present in the entire string, it will be
# displayed verbatim as a dollar sign. This is a small change from
# regular TeX, where the dollar sign in non-math text would have to
# be escaped ('\\\$').
#
# .. note::
# While the syntax inside the pair of dollar signs ($) aims to be
# TeX-like, the text outside does not. In particular, characters
# such as::
#
# # $ % & ~ _ ^ \ { } \( \) \[ \]
#
# have special meaning outside of math mode in TeX. Therefore, these
# characters will behave differently depending on the rcParam
# ``text.usetex`` flag. See the :ref:`usetex tutorial
# ` for more information.
#
# Subscripts and superscripts
# ---------------------------
#
# To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::
#
# r'$\alpha_i > \beta_i$'
#
# .. math::
#
# \alpha_i > \beta_i
#
# Some symbols automatically put their sub/superscripts under and over
# the operator. For example, to write the sum of :math:`x_i` from :math:`0` to
# :math:`\infty`, you could do::
#
# r'$\sum_{i=0}^\infty x_i$'
#
# .. math::
#
# \sum_{i=0}^\infty x_i
#
# Fractions, binomials and stacked numbers
# ----------------------------------------
#
# Fractions, binomials and stacked numbers can be created with the
# ``\frac{}{}``, ``\binom{}{}`` and ``\stackrel{}{}`` commands,
# respectively::
#
# r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$'
#
# produces
#
# .. math::
#
# \frac{3}{4} \binom{3}{4} \stackrel{3}{4}
#
# Fractions can be arbitrarily nested::
#
# r'$\frac{5 - \frac{1}{x}}{4}$'
#
# produces
#
# .. math::
#
# \frac{5 - \frac{1}{x}}{4}
#
# Note that special care needs to be taken to place parentheses and brackets around
# fractions. Doing things the obvious way produces brackets that are
# too small::
#
# r'$(\frac{5 - \frac{1}{x}}{4})$'
#
# .. math ::
#
# (\frac{5 - \frac{1}{x}}{4})
#
# The solution is to precede the bracket with ``\left`` and ``\right``
# to inform the parser that those brackets encompass the entire object.::
#
# r'$\left(\frac{5 - \frac{1}{x}}{4}\right)$'
#
# .. math ::
#
# \left(\frac{5 - \frac{1}{x}}{4}\right)
#
# Radicals
# --------
#
# Radicals can be produced with the ``\sqrt[]{}`` command. For example::
#
# r'$\sqrt{2}$'
#
# .. math ::
#
# \sqrt{2}
#
# Any base can (optionally) be provided inside square brackets. Note
# that the base must be a simple expression, and can not contain layout
# commands such as fractions or sub/superscripts::
#
# r'$\sqrt[3]{x}$'
#
# .. math ::
#
# \sqrt[3]{x}
#
# .. _mathtext-fonts:
#
# Fonts
# -----
#
# The default font is *italics* for mathematical symbols.
#
# .. note::
#
# This default can be changed using the ``mathtext.default`` rcParam.
# This is useful, for example, to use the same font as regular
# non-math text for math text, by setting it to ``regular``.
#
# To change fonts, e.g., to write "sin" in a Roman font, enclose the text
# in a font command::
#
# r'$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$'
#
# .. math::
#
# s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)
#
# More conveniently, many commonly used function names that are typeset in a
# Roman font have shortcuts. So the expression above could be written
# as follows::
#
# r'$s(t) = \mathcal{A}\sin(2 \omega t)$'
#
# .. math::
#
# s(t) = \mathcal{A}\sin(2 \omega t)
#
# Here "s" and "t" are variable in italics font (default), "sin" is in
# Roman font, and the amplitude "A" is in calligraphy font. Note in the
# example above the caligraphy ``A`` is squished into the ``sin``. You
# can use a spacing command to add a little whitespace between them::
#
# s(t) = \mathcal{A}\/\sin(2 \omega t)
#
# .. math::
#
# s(t) = \mathcal{A}\/\sin(2 \omega t)
#
# The choices available with all fonts are:
#
# ============================ ==================================
# Command Result
# ============================ ==================================
# ``\mathrm{Roman}`` :math:`\mathrm{Roman}`
# ``\mathit{Italic}`` :math:`\mathit{Italic}`
# ``\mathtt{Typewriter}`` :math:`\mathtt{Typewriter}`
# ``\mathcal{CALLIGRAPHY}`` :math:`\mathcal{CALLIGRAPHY}`
# ============================ ==================================
#
# .. role:: math-stix(math)
# :fontset: stix
#
# When using the `STIX `_ fonts, you also have the choice of:
#
# ====================================== =========================================
# Command Result
# ====================================== =========================================
# ``\mathbb{blackboard}`` :math-stix:`\mathbb{blackboard}`
# ``\mathrm{\mathbb{blackboard}}`` :math-stix:`\mathrm{\mathbb{blackboard}}`
# ``\mathfrak{Fraktur}`` :math-stix:`\mathfrak{Fraktur}`
# ``\mathsf{sansserif}`` :math-stix:`\mathsf{sansserif}`
# ``\mathrm{\mathsf{sansserif}}`` :math-stix:`\mathrm{\mathsf{sansserif}}`
# ====================================== =========================================
#
# .. htmlonly::
#
# ====================================== =========================================
# ``\mathcircled{circled}`` :math-stix:`\mathcircled{circled}`
# ====================================== =========================================
#
# There are also three global "font sets" to choose from, which are
# selected using the ``mathtext.fontset`` parameter in
# :ref:`matplotlibrc `.
#
# ``cm``: **Computer Modern (TeX)**
#
# .. image:: ../../_static/cm_fontset.png
#
# ``stix``: **STIX** (designed to blend well with Times)
#
# .. image:: ../../_static/stix_fontset.png
#
# ``stixsans``: **STIX sans-serif**
#
# .. image:: ../../_static/stixsans_fontset.png
#
# Additionally, you can use ``\mathdefault{...}`` or its alias
# ``\mathregular{...}`` to use the font used for regular text outside of
# mathtext. There are a number of limitations to this approach, most
# notably that far fewer symbols will be available, but it can be useful
# to make math expressions blend well with other text in the plot.
#
# Custom fonts
# ~~~~~~~~~~~~
#
# mathtext also provides a way to use custom fonts for math. This
# method is fairly tricky to use, and should be considered an
# experimental feature for patient users only. By setting the rcParam
# ``mathtext.fontset`` to ``custom``, you can then set the following
# parameters, which control which font file to use for a particular set
# of math characters.
#
# ============================== =================================
# Parameter Corresponds to
# ============================== =================================
# ``mathtext.it`` ``\mathit{}`` or default italic
# ``mathtext.rm`` ``\mathrm{}`` Roman (upright)
# ``mathtext.tt`` ``\mathtt{}`` Typewriter (monospace)
# ``mathtext.bf`` ``\mathbf{}`` bold italic
# ``mathtext.cal`` ``\mathcal{}`` calligraphic
# ``mathtext.sf`` ``\mathsf{}`` sans-serif
# ============================== =================================
#
# Each parameter should be set to a fontconfig font descriptor (as
# defined in the yet-to-be-written font chapter).
#
# .. TODO: Link to font chapter
#
# The fonts used should have a Unicode mapping in order to find any
# non-Latin characters, such as Greek. If you want to use a math symbol
# that is not contained in your custom fonts, you can set the rcParam
# ``mathtext.fallback_to_cm`` to ``True`` which will cause the mathtext
# system to use characters from the default Computer Modern fonts
# whenever a particular character can not be found in the custom font.
#
# Note that the math glyphs specified in Unicode have evolved over time,
# and many fonts may not have glyphs in the correct place for mathtext.
#
# Accents
# -------
#
# An accent command may precede any symbol to add an accent above it.
# There are long and short forms for some of them.
#
# ============================== =================================
# Command Result
# ============================== =================================
# ``\acute a`` or ``\'a`` :math:`\acute a`
# ``\bar a`` :math:`\bar a`
# ``\breve a`` :math:`\breve a`
# ``\ddot a`` or ``\''a`` :math:`\ddot a`
# ``\dot a`` or ``\.a`` :math:`\dot a`
# ``\grave a`` or ``\`a`` :math:`\grave a`
# ``\hat a`` or ``\^a`` :math:`\hat a`
# ``\tilde a`` or ``\~a`` :math:`\tilde a`
# ``\vec a`` :math:`\vec a`
# ``\overline{abc}`` :math:`\overline{abc}`
# ============================== =================================
#
# In addition, there are two special accents that automatically adjust
# to the width of the symbols below:
#
# ============================== =================================
# Command Result
# ============================== =================================
# ``\widehat{xyz}`` :math:`\widehat{xyz}`
# ``\widetilde{xyz}`` :math:`\widetilde{xyz}`
# ============================== =================================
#
# Care should be taken when putting accents on lower-case i's and j's.
# Note that in the following ``\imath`` is used to avoid the extra dot
# over the i::
#
# r"$\hat i\ \ \hat \imath$"
#
# .. math::
#
# \hat i\ \ \hat \imath
#
# Symbols
# -------
#
# You can also use a large number of the TeX symbols, as in ``\infty``,
# ``\leftarrow``, ``\sum``, ``\int``.
#
# .. math_symbol_table::
#
# If a particular symbol does not have a name (as is true of many of the
# more obscure symbols in the STIX fonts), Unicode characters can
# also be used::
#
# ur'$\u23ce$'
#
# Example
# -------
#
# Here is an example illustrating many of these features in context.
#
# .. figure:: ../../gallery/pyplots/images/sphx_glr_pyplot_mathtext_001.png
# :target: ../../gallery/pyplots/pyplot_mathtext.html
# :align: center
# :scale: 50
#
# Pyplot Mathtext