diff --git a/lib/python3.12/site-packages/matplotlib/__init__.py b/lib/python3.12/site-packages/matplotlib/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..5f964e0b34dea11f572136a3bb6e3d9968ebe754
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/__init__.py
@@ -0,0 +1,1576 @@
+"""
+An object-oriented plotting library.
+
+A procedural interface is provided by the companion pyplot module,
+which may be imported directly, e.g.::
+
+    import matplotlib.pyplot as plt
+
+or using ipython::
+
+    ipython
+
+at your terminal, followed by::
+
+    In [1]: %matplotlib
+    In [2]: import matplotlib.pyplot as plt
+
+at the ipython shell prompt.
+
+For the most part, direct use of the explicit object-oriented library is
+encouraged when programming; the implicit pyplot interface is primarily for
+working interactively. The exceptions to this suggestion are the pyplot
+functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and
+`.pyplot.savefig`, which can greatly simplify scripting.  See
+:ref:`api_interfaces` for an explanation of the tradeoffs between the implicit
+and explicit interfaces.
+
+Modules include:
+
+:mod:`matplotlib.axes`
+    The `~.axes.Axes` class.  Most pyplot functions are wrappers for
+    `~.axes.Axes` methods.  The axes module is the highest level of OO
+    access to the library.
+
+:mod:`matplotlib.figure`
+    The `.Figure` class.
+
+:mod:`matplotlib.artist`
+    The `.Artist` base class for all classes that draw things.
+
+:mod:`matplotlib.lines`
+    The `.Line2D` class for drawing lines and markers.
+
+:mod:`matplotlib.patches`
+    Classes for drawing polygons.
+
+:mod:`matplotlib.text`
+    The `.Text` and `.Annotation` classes.
+
+:mod:`matplotlib.image`
+    The `.AxesImage` and `.FigureImage` classes.
+
+:mod:`matplotlib.collections`
+    Classes for efficient drawing of groups of lines or polygons.
+
+:mod:`matplotlib.colors`
+    Color specifications and making colormaps.
+
+:mod:`matplotlib.cm`
+    Colormaps, and the `.ScalarMappable` mixin class for providing color
+    mapping functionality to other classes.
+
+:mod:`matplotlib.ticker`
+    Calculation of tick mark locations and formatting of tick labels.
+
+:mod:`matplotlib.backends`
+    A subpackage with modules for various GUI libraries and output formats.
+
+The base matplotlib namespace includes:
+
+`~matplotlib.rcParams`
+    Default configuration settings; their defaults may be overridden using
+    a :file:`matplotlibrc` file.
+
+`~matplotlib.use`
+    Setting the Matplotlib backend.  This should be called before any
+    figure is created, because it is not possible to switch between
+    different GUI backends after that.
+
+The following environment variables can be used to customize the behavior:
+
+:envvar:`MPLBACKEND`
+    This optional variable can be set to choose the Matplotlib backend. See
+    :ref:`what-is-a-backend`.
+
+:envvar:`MPLCONFIGDIR`
+    This is the directory used to store user customizations to
+    Matplotlib, as well as some caches to improve performance. If
+    :envvar:`MPLCONFIGDIR` is not defined, :file:`{HOME}/.config/matplotlib`
+    and :file:`{HOME}/.cache/matplotlib` are used on Linux, and
+    :file:`{HOME}/.matplotlib` on other platforms, if they are
+    writable. Otherwise, the Python standard library's `tempfile.gettempdir`
+    is used to find a base directory in which the :file:`matplotlib`
+    subdirectory is created.
+
+Matplotlib was initially written by John D. Hunter (1968-2012) and is now
+developed and maintained by a host of others.
+
+Occasionally the internal documentation (python docstrings) will refer
+to MATLAB®, a registered trademark of The MathWorks, Inc.
+
+"""
+
+__all__ = [
+    "__bibtex__",
+    "__version__",
+    "__version_info__",
+    "set_loglevel",
+    "ExecutableNotFoundError",
+    "get_configdir",
+    "get_cachedir",
+    "get_data_path",
+    "matplotlib_fname",
+    "MatplotlibDeprecationWarning",
+    "RcParams",
+    "rc_params",
+    "rc_params_from_file",
+    "rcParamsDefault",
+    "rcParams",
+    "rcParamsOrig",
+    "defaultParams",
+    "rc",
+    "rcdefaults",
+    "rc_file_defaults",
+    "rc_file",
+    "rc_context",
+    "use",
+    "get_backend",
+    "interactive",
+    "is_interactive",
+    "colormaps",
+    "multivar_colormaps",
+    "bivar_colormaps",
+    "color_sequences",
+]
+
+
+import atexit
+from collections import namedtuple
+from collections.abc import MutableMapping
+import contextlib
+import functools
+import importlib
+import inspect
+from inspect import Parameter
+import locale
+import logging
+import os
+from pathlib import Path
+import pprint
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from packaging.version import parse as parse_version
+
+# cbook must import matplotlib only within function
+# definitions, so it is safe to import from it here.
+from . import _api, _version, cbook, _docstring, rcsetup
+from matplotlib._api import MatplotlibDeprecationWarning
+from matplotlib.rcsetup import cycler  # noqa: F401
+
+
+_log = logging.getLogger(__name__)
+
+__bibtex__ = r"""@Article{Hunter:2007,
+  Author    = {Hunter, J. D.},
+  Title     = {Matplotlib: A 2D graphics environment},
+  Journal   = {Computing in Science \& Engineering},
+  Volume    = {9},
+  Number    = {3},
+  Pages     = {90--95},
+  abstract  = {Matplotlib is a 2D graphics package used for Python
+  for application development, interactive scripting, and
+  publication-quality image generation across user
+  interfaces and operating systems.},
+  publisher = {IEEE COMPUTER SOC},
+  year      = 2007
+}"""
+
+# modelled after sys.version_info
+_VersionInfo = namedtuple('_VersionInfo',
+                          'major, minor, micro, releaselevel, serial')
+
+
+def _parse_to_version_info(version_str):
+    """
+    Parse a version string to a namedtuple analogous to sys.version_info.
+
+    See:
+    https://packaging.pypa.io/en/latest/version.html#packaging.version.parse
+    https://docs.python.org/3/library/sys.html#sys.version_info
+    """
+    v = parse_version(version_str)
+    if v.pre is None and v.post is None and v.dev is None:
+        return _VersionInfo(v.major, v.minor, v.micro, 'final', 0)
+    elif v.dev is not None:
+        return _VersionInfo(v.major, v.minor, v.micro, 'alpha', v.dev)
+    elif v.pre is not None:
+        releaselevel = {
+            'a': 'alpha',
+            'b': 'beta',
+            'rc': 'candidate'}.get(v.pre[0], 'alpha')
+        return _VersionInfo(v.major, v.minor, v.micro, releaselevel, v.pre[1])
+    else:
+        # fallback for v.post: guess-next-dev scheme from setuptools_scm
+        return _VersionInfo(v.major, v.minor, v.micro + 1, 'alpha', v.post)
+
+
+def _get_version():
+    """Return the version string used for __version__."""
+    # Only shell out to a git subprocess if really needed, i.e. when we are in
+    # a matplotlib git repo but not in a shallow clone, such as those used by
+    # CI, as the latter would trigger a warning from setuptools_scm.
+    root = Path(__file__).resolve().parents[2]
+    if ((root / ".matplotlib-repo").exists()
+            and (root / ".git").exists()
+            and not (root / ".git/shallow").exists()):
+        try:
+            import setuptools_scm
+        except ImportError:
+            pass
+        else:
+            return setuptools_scm.get_version(
+                root=root,
+                dist_name="matplotlib",
+                version_scheme="release-branch-semver",
+                local_scheme="node-and-date",
+                fallback_version=_version.version,
+            )
+    # Get the version from the _version.py file if not in repo or setuptools_scm is
+    # unavailable.
+    return _version.version
+
+
+@_api.caching_module_getattr
+class __getattr__:
+    __version__ = property(lambda self: _get_version())
+    __version_info__ = property(
+        lambda self: _parse_to_version_info(self.__version__))
+
+
+def _check_versions():
+
+    # Quickfix to ensure Microsoft Visual C++ redistributable
+    # DLLs are loaded before importing kiwisolver
+    from . import ft2font  # noqa: F401
+
+    for modname, minver in [
+            ("cycler", "0.10"),
+            ("dateutil", "2.7"),
+            ("kiwisolver", "1.3.1"),
+            ("numpy", "1.23"),
+            ("pyparsing", "2.3.1"),
+    ]:
+        module = importlib.import_module(modname)
+        if parse_version(module.__version__) < parse_version(minver):
+            raise ImportError(f"Matplotlib requires {modname}>={minver}; "
+                              f"you have {module.__version__}")
+
+
+_check_versions()
+
+
+# The decorator ensures this always returns the same handler (and it is only
+# attached once).
+@functools.cache
+def _ensure_handler():
+    """
+    The first time this function is called, attach a `StreamHandler` using the
+    same format as `logging.basicConfig` to the Matplotlib root logger.
+
+    Return this handler every time this function is called.
+    """
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(logging.BASIC_FORMAT))
+    _log.addHandler(handler)
+    return handler
+
+
+def set_loglevel(level):
+    """
+    Configure Matplotlib's logging levels.
+
+    Matplotlib uses the standard library `logging` framework under the root
+    logger 'matplotlib'.  This is a helper function to:
+
+    - set Matplotlib's root logger level
+    - set the root logger handler's level, creating the handler
+      if it does not exist yet
+
+    Typically, one should call ``set_loglevel("info")`` or
+    ``set_loglevel("debug")`` to get additional debugging information.
+
+    Users or applications that are installing their own logging handlers
+    may want to directly manipulate ``logging.getLogger('matplotlib')`` rather
+    than use this function.
+
+    Parameters
+    ----------
+    level : {"notset", "debug", "info", "warning", "error", "critical"}
+        The log level of the handler.
+
+    Notes
+    -----
+    The first time this function is called, an additional handler is attached
+    to Matplotlib's root handler; this handler is reused every time and this
+    function simply manipulates the logger and handler's level.
+
+    """
+    _log.setLevel(level.upper())
+    _ensure_handler().setLevel(level.upper())
+
+
+def _logged_cached(fmt, func=None):
+    """
+    Decorator that logs a function's return value, and memoizes that value.
+
+    After ::
+
+        @_logged_cached(fmt)
+        def func(): ...
+
+    the first call to *func* will log its return value at the DEBUG level using
+    %-format string *fmt*, and memoize it; later calls to *func* will directly
+    return that value.
+    """
+    if func is None:  # Return the actual decorator.
+        return functools.partial(_logged_cached, fmt)
+
+    called = False
+    ret = None
+
+    @functools.wraps(func)
+    def wrapper(**kwargs):
+        nonlocal called, ret
+        if not called:
+            ret = func(**kwargs)
+            called = True
+            _log.debug(fmt, ret)
+        return ret
+
+    return wrapper
+
+
+_ExecInfo = namedtuple("_ExecInfo", "executable raw_version version")
+
+
+class ExecutableNotFoundError(FileNotFoundError):
+    """
+    Error raised when an executable that Matplotlib optionally
+    depends on can't be found.
+    """
+    pass
+
+
+@functools.cache
+def _get_executable_info(name):
+    """
+    Get the version of some executable that Matplotlib optionally depends on.
+
+    .. warning::
+       The list of executables that this function supports is set according to
+       Matplotlib's internal needs, and may change without notice.
+
+    Parameters
+    ----------
+    name : str
+        The executable to query.  The following values are currently supported:
+        "dvipng", "gs", "inkscape", "magick", "pdftocairo", "pdftops".  This
+        list is subject to change without notice.
+
+    Returns
+    -------
+    tuple
+        A namedtuple with fields ``executable`` (`str`) and ``version``
+        (`packaging.Version`, or ``None`` if the version cannot be determined).
+
+    Raises
+    ------
+    ExecutableNotFoundError
+        If the executable is not found or older than the oldest version
+        supported by Matplotlib.  For debugging purposes, it is also
+        possible to "hide" an executable from Matplotlib by adding it to the
+        :envvar:`_MPLHIDEEXECUTABLES` environment variable (a comma-separated
+        list), which must be set prior to any calls to this function.
+    ValueError
+        If the executable is not one that we know how to query.
+    """
+
+    def impl(args, regex, min_ver=None, ignore_exit_code=False):
+        # Execute the subprocess specified by args; capture stdout and stderr.
+        # Search for a regex match in the output; if the match succeeds, the
+        # first group of the match is the version.
+        # Return an _ExecInfo if the executable exists, and has a version of
+        # at least min_ver (if set); else, raise ExecutableNotFoundError.
+        try:
+            output = subprocess.check_output(
+                args, stderr=subprocess.STDOUT,
+                text=True, errors="replace")
+        except subprocess.CalledProcessError as _cpe:
+            if ignore_exit_code:
+                output = _cpe.output
+            else:
+                raise ExecutableNotFoundError(str(_cpe)) from _cpe
+        except OSError as _ose:
+            raise ExecutableNotFoundError(str(_ose)) from _ose
+        match = re.search(regex, output)
+        if match:
+            raw_version = match.group(1)
+            version = parse_version(raw_version)
+            if min_ver is not None and version < parse_version(min_ver):
+                raise ExecutableNotFoundError(
+                    f"You have {args[0]} version {version} but the minimum "
+                    f"version supported by Matplotlib is {min_ver}")
+            return _ExecInfo(args[0], raw_version, version)
+        else:
+            raise ExecutableNotFoundError(
+                f"Failed to determine the version of {args[0]} from "
+                f"{' '.join(args)}, which output {output}")
+
+    if name in os.environ.get("_MPLHIDEEXECUTABLES", "").split(","):
+        raise ExecutableNotFoundError(f"{name} was hidden")
+
+    if name == "dvipng":
+        return impl(["dvipng", "-version"], "(?m)^dvipng(?: .*)? (.+)", "1.6")
+    elif name == "gs":
+        execs = (["gswin32c", "gswin64c", "mgs", "gs"]  # "mgs" for miktex.
+                 if sys.platform == "win32" else
+                 ["gs"])
+        for e in execs:
+            try:
+                return impl([e, "--version"], "(.*)", "9")
+            except ExecutableNotFoundError:
+                pass
+        message = "Failed to find a Ghostscript installation"
+        raise ExecutableNotFoundError(message)
+    elif name == "inkscape":
+        try:
+            # Try headless option first (needed for Inkscape version < 1.0):
+            return impl(["inkscape", "--without-gui", "-V"],
+                        "Inkscape ([^ ]*)")
+        except ExecutableNotFoundError:
+            pass  # Suppress exception chaining.
+        # If --without-gui is not accepted, we may be using Inkscape >= 1.0 so
+        # try without it:
+        return impl(["inkscape", "-V"], "Inkscape ([^ ]*)")
+    elif name == "magick":
+        if sys.platform == "win32":
+            # Check the registry to avoid confusing ImageMagick's convert with
+            # Windows's builtin convert.exe.
+            import winreg
+            binpath = ""
+            for flag in [0, winreg.KEY_WOW64_32KEY, winreg.KEY_WOW64_64KEY]:
+                try:
+                    with winreg.OpenKeyEx(
+                            winreg.HKEY_LOCAL_MACHINE,
+                            r"Software\Imagemagick\Current",
+                            0, winreg.KEY_QUERY_VALUE | flag) as hkey:
+                        binpath = winreg.QueryValueEx(hkey, "BinPath")[0]
+                except OSError:
+                    pass
+            path = None
+            if binpath:
+                for name in ["convert.exe", "magick.exe"]:
+                    candidate = Path(binpath, name)
+                    if candidate.exists():
+                        path = str(candidate)
+                        break
+            if path is None:
+                raise ExecutableNotFoundError(
+                    "Failed to find an ImageMagick installation")
+        else:
+            path = "convert"
+        info = impl([path, "--version"], r"^Version: ImageMagick (\S*)")
+        if info.raw_version == "7.0.10-34":
+            # https://github.com/ImageMagick/ImageMagick/issues/2720
+            raise ExecutableNotFoundError(
+                f"You have ImageMagick {info.version}, which is unsupported")
+        return info
+    elif name == "pdftocairo":
+        return impl(["pdftocairo", "-v"], "pdftocairo version (.*)")
+    elif name == "pdftops":
+        info = impl(["pdftops", "-v"], "^pdftops version (.*)",
+                    ignore_exit_code=True)
+        if info and not (
+                3 <= info.version.major or
+                # poppler version numbers.
+                parse_version("0.9") <= info.version < parse_version("1.0")):
+            raise ExecutableNotFoundError(
+                f"You have pdftops version {info.version} but the minimum "
+                f"version supported by Matplotlib is 3.0")
+        return info
+    else:
+        raise ValueError(f"Unknown executable: {name!r}")
+
+
+def _get_xdg_config_dir():
+    """
+    Return the XDG configuration directory, according to the XDG base
+    directory spec:
+
+    https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+    """
+    return os.environ.get('XDG_CONFIG_HOME') or str(Path.home() / ".config")
+
+
+def _get_xdg_cache_dir():
+    """
+    Return the XDG cache directory, according to the XDG base directory spec:
+
+    https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+    """
+    return os.environ.get('XDG_CACHE_HOME') or str(Path.home() / ".cache")
+
+
+def _get_config_or_cache_dir(xdg_base_getter):
+    configdir = os.environ.get('MPLCONFIGDIR')
+    if configdir:
+        configdir = Path(configdir)
+    elif sys.platform.startswith(('linux', 'freebsd')):
+        # Only call _xdg_base_getter here so that MPLCONFIGDIR is tried first,
+        # as _xdg_base_getter can throw.
+        configdir = Path(xdg_base_getter(), "matplotlib")
+    else:
+        configdir = Path.home() / ".matplotlib"
+    # Resolve the path to handle potential issues with inaccessible symlinks.
+    configdir = configdir.resolve()
+    try:
+        configdir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _log.warning("mkdir -p failed for path %s: %s", configdir, exc)
+    else:
+        if os.access(str(configdir), os.W_OK) and configdir.is_dir():
+            return str(configdir)
+        _log.warning("%s is not a writable directory", configdir)
+    # If the config or cache directory cannot be created or is not a writable
+    # directory, create a temporary one.
+    try:
+        tmpdir = tempfile.mkdtemp(prefix="matplotlib-")
+    except OSError as exc:
+        raise OSError(
+            f"Matplotlib requires access to a writable cache directory, but there "
+            f"was an issue with the default path ({configdir}), and a temporary "
+            f"directory could not be created; set the MPLCONFIGDIR environment "
+            f"variable to a writable directory") from exc
+    os.environ["MPLCONFIGDIR"] = tmpdir
+    atexit.register(shutil.rmtree, tmpdir)
+    _log.warning(
+        "Matplotlib created a temporary cache directory at %s because there was "
+        "an issue with the default path (%s); it is highly recommended to set the "
+        "MPLCONFIGDIR environment variable to a writable directory, in particular to "
+        "speed up the import of Matplotlib and to better support multiprocessing.",
+        tmpdir, configdir)
+    return tmpdir
+
+
+@_logged_cached('CONFIGDIR=%s')
+def get_configdir():
+    """
+    Return the string path of the configuration directory.
+
+    The directory is chosen as follows:
+
+    1. If the MPLCONFIGDIR environment variable is supplied, choose that.
+    2. On Linux, follow the XDG specification and look first in
+       ``$XDG_CONFIG_HOME``, if defined, or ``$HOME/.config``.  On other
+       platforms, choose ``$HOME/.matplotlib``.
+    3. If the chosen directory exists and is writable, use that as the
+       configuration directory.
+    4. Else, create a temporary directory, and use it as the configuration
+       directory.
+    """
+    return _get_config_or_cache_dir(_get_xdg_config_dir)
+
+
+@_logged_cached('CACHEDIR=%s')
+def get_cachedir():
+    """
+    Return the string path of the cache directory.
+
+    The procedure used to find the directory is the same as for
+    `get_configdir`, except using ``$XDG_CACHE_HOME``/``$HOME/.cache`` instead.
+    """
+    return _get_config_or_cache_dir(_get_xdg_cache_dir)
+
+
+@_logged_cached('matplotlib data path: %s')
+def get_data_path():
+    """Return the path to Matplotlib data."""
+    return str(Path(__file__).with_name("mpl-data"))
+
+
+def matplotlib_fname():
+    """
+    Get the location of the config file.
+
+    The file location is determined in the following order
+
+    - ``$PWD/matplotlibrc``
+    - ``$MATPLOTLIBRC`` if it is not a directory
+    - ``$MATPLOTLIBRC/matplotlibrc``
+    - ``$MPLCONFIGDIR/matplotlibrc``
+    - On Linux,
+        - ``$XDG_CONFIG_HOME/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME``
+          is defined)
+        - or ``$HOME/.config/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME``
+          is not defined)
+    - On other platforms,
+      - ``$HOME/.matplotlib/matplotlibrc`` if ``$HOME`` is defined
+    - Lastly, it looks in ``$MATPLOTLIBDATA/matplotlibrc``, which should always
+      exist.
+    """
+
+    def gen_candidates():
+        # rely on down-stream code to make absolute.  This protects us
+        # from having to directly get the current working directory
+        # which can fail if the user has ended up with a cwd that is
+        # non-existent.
+        yield 'matplotlibrc'
+        try:
+            matplotlibrc = os.environ['MATPLOTLIBRC']
+        except KeyError:
+            pass
+        else:
+            yield matplotlibrc
+            yield os.path.join(matplotlibrc, 'matplotlibrc')
+        yield os.path.join(get_configdir(), 'matplotlibrc')
+        yield os.path.join(get_data_path(), 'matplotlibrc')
+
+    for fname in gen_candidates():
+        if os.path.exists(fname) and not os.path.isdir(fname):
+            return fname
+
+    raise RuntimeError("Could not find matplotlibrc file; your Matplotlib "
+                       "install is broken")
+
+
+# rcParams deprecated and automatically mapped to another key.
+# Values are tuples of (version, new_name, f_old2new, f_new2old).
+_deprecated_map = {}
+# rcParams deprecated; some can manually be mapped to another key.
+# Values are tuples of (version, new_name_or_None).
+_deprecated_ignore_map = {}
+# rcParams deprecated; can use None to suppress warnings; remain actually
+# listed in the rcParams.
+# Values are tuples of (version,)
+_deprecated_remain_as_none = {}
+
+
+@_docstring.Substitution(
+    "\n".join(map("- {}".format, sorted(rcsetup._validators, key=str.lower)))
+)
+class RcParams(MutableMapping, dict):
+    """
+    A dict-like key-value store for config parameters, including validation.
+
+    Validating functions are defined and associated with rc parameters in
+    :mod:`matplotlib.rcsetup`.
+
+    The list of rcParams is:
+
+    %s
+
+    See Also
+    --------
+    :ref:`customizing-with-matplotlibrc-files`
+    """
+
+    validate = rcsetup._validators
+
+    # validate values on the way in
+    def __init__(self, *args, **kwargs):
+        self.update(*args, **kwargs)
+
+    def _set(self, key, val):
+        """
+        Directly write data bypassing deprecation and validation logic.
+
+        Notes
+        -----
+        As end user or downstream library you almost always should use
+        ``rcParams[key] = val`` and not ``_set()``.
+
+        There are only very few special cases that need direct data access.
+        These cases previously used ``dict.__setitem__(rcParams, key, val)``,
+        which is now deprecated and replaced by ``rcParams._set(key, val)``.
+
+        Even though private, we guarantee API stability for ``rcParams._set``,
+        i.e. it is subject to Matplotlib's API and deprecation policy.
+
+        :meta public:
+        """
+        dict.__setitem__(self, key, val)
+
+    def _get(self, key):
+        """
+        Directly read data bypassing deprecation, backend and validation
+        logic.
+
+        Notes
+        -----
+        As end user or downstream library you almost always should use
+        ``val = rcParams[key]`` and not ``_get()``.
+
+        There are only very few special cases that need direct data access.
+        These cases previously used ``dict.__getitem__(rcParams, key, val)``,
+        which is now deprecated and replaced by ``rcParams._get(key)``.
+
+        Even though private, we guarantee API stability for ``rcParams._get``,
+        i.e. it is subject to Matplotlib's API and deprecation policy.
+
+        :meta public:
+        """
+        return dict.__getitem__(self, key)
+
+    def _update_raw(self, other_params):
+        """
+        Directly update the data from *other_params*, bypassing deprecation,
+        backend and validation logic on both sides.
+
+        This ``rcParams._update_raw(params)`` replaces the previous pattern
+        ``dict.update(rcParams, params)``.
+
+        Parameters
+        ----------
+        other_params : dict or `.RcParams`
+            The input mapping from which to update.
+        """
+        if isinstance(other_params, RcParams):
+            other_params = dict.items(other_params)
+        dict.update(self, other_params)
+
+    def _ensure_has_backend(self):
+        """
+        Ensure that a "backend" entry exists.
+
+        Normally, the default matplotlibrc file contains *no* entry for "backend" (the
+        corresponding line starts with ##, not #; we fill in _auto_backend_sentinel
+        in that case.  However, packagers can set a different default backend
+        (resulting in a normal `#backend: foo` line) in which case we should *not*
+        fill in _auto_backend_sentinel.
+        """
+        dict.setdefault(self, "backend", rcsetup._auto_backend_sentinel)
+
+    def __setitem__(self, key, val):
+        try:
+            if key in _deprecated_map:
+                version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
+                _api.warn_deprecated(
+                    version, name=key, obj_type="rcparam", alternative=alt_key)
+                key = alt_key
+                val = alt_val(val)
+            elif key in _deprecated_remain_as_none and val is not None:
+                version, = _deprecated_remain_as_none[key]
+                _api.warn_deprecated(version, name=key, obj_type="rcparam")
+            elif key in _deprecated_ignore_map:
+                version, alt_key = _deprecated_ignore_map[key]
+                _api.warn_deprecated(
+                    version, name=key, obj_type="rcparam", alternative=alt_key)
+                return
+            elif key == 'backend':
+                if val is rcsetup._auto_backend_sentinel:
+                    if 'backend' in self:
+                        return
+            try:
+                cval = self.validate[key](val)
+            except ValueError as ve:
+                raise ValueError(f"Key {key}: {ve}") from None
+            self._set(key, cval)
+        except KeyError as err:
+            raise KeyError(
+                f"{key} is not a valid rc parameter (see rcParams.keys() for "
+                f"a list of valid parameters)") from err
+
+    def __getitem__(self, key):
+        if key in _deprecated_map:
+            version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
+            _api.warn_deprecated(
+                version, name=key, obj_type="rcparam", alternative=alt_key)
+            return inverse_alt(self._get(alt_key))
+
+        elif key in _deprecated_ignore_map:
+            version, alt_key = _deprecated_ignore_map[key]
+            _api.warn_deprecated(
+                version, name=key, obj_type="rcparam", alternative=alt_key)
+            return self._get(alt_key) if alt_key else None
+
+        # In theory, this should only ever be used after the global rcParams
+        # has been set up, but better be safe e.g. in presence of breakpoints.
+        elif key == "backend" and self is globals().get("rcParams"):
+            val = self._get(key)
+            if val is rcsetup._auto_backend_sentinel:
+                from matplotlib import pyplot as plt
+                plt.switch_backend(rcsetup._auto_backend_sentinel)
+
+        return self._get(key)
+
+    def _get_backend_or_none(self):
+        """Get the requested backend, if any, without triggering resolution."""
+        backend = self._get("backend")
+        return None if backend is rcsetup._auto_backend_sentinel else backend
+
+    def __repr__(self):
+        class_name = self.__class__.__name__
+        indent = len(class_name) + 1
+        with _api.suppress_matplotlib_deprecation_warning():
+            repr_split = pprint.pformat(dict(self), indent=1,
+                                        width=80 - indent).split('\n')
+        repr_indented = ('\n' + ' ' * indent).join(repr_split)
+        return f'{class_name}({repr_indented})'
+
+    def __str__(self):
+        return '\n'.join(map('{0[0]}: {0[1]}'.format, sorted(self.items())))
+
+    def __iter__(self):
+        """Yield sorted list of keys."""
+        with _api.suppress_matplotlib_deprecation_warning():
+            yield from sorted(dict.__iter__(self))
+
+    def __len__(self):
+        return dict.__len__(self)
+
+    def find_all(self, pattern):
+        """
+        Return the subset of this RcParams dictionary whose keys match,
+        using :func:`re.search`, the given ``pattern``.
+
+        .. note::
+
+            Changes to the returned dictionary are *not* propagated to
+            the parent RcParams dictionary.
+
+        """
+        pattern_re = re.compile(pattern)
+        return RcParams((key, value)
+                        for key, value in self.items()
+                        if pattern_re.search(key))
+
+    def copy(self):
+        """Copy this RcParams instance."""
+        rccopy = RcParams()
+        for k in self:  # Skip deprecations and revalidation.
+            rccopy._set(k, self._get(k))
+        return rccopy
+
+
+def rc_params(fail_on_error=False):
+    """Construct a `RcParams` instance from the default Matplotlib rc file."""
+    return rc_params_from_file(matplotlib_fname(), fail_on_error)
+
+
+@functools.cache
+def _get_ssl_context():
+    try:
+        import certifi
+    except ImportError:
+        _log.debug("Could not import certifi.")
+        return None
+    import ssl
+    return ssl.create_default_context(cafile=certifi.where())
+
+
+@contextlib.contextmanager
+def _open_file_or_url(fname):
+    if (isinstance(fname, str)
+            and fname.startswith(('http://', 'https://', 'ftp://', 'file:'))):
+        import urllib.request
+        ssl_ctx = _get_ssl_context()
+        if ssl_ctx is None:
+            _log.debug(
+                "Could not get certifi ssl context, https may not work."
+            )
+        with urllib.request.urlopen(fname, context=ssl_ctx) as f:
+            yield (line.decode('utf-8') for line in f)
+    else:
+        fname = os.path.expanduser(fname)
+        with open(fname, encoding='utf-8') as f:
+            yield f
+
+
+def _rc_params_in_file(fname, transform=lambda x: x, fail_on_error=False):
+    """
+    Construct a `RcParams` instance from file *fname*.
+
+    Unlike `rc_params_from_file`, the configuration class only contains the
+    parameters specified in the file (i.e. default values are not filled in).
+
+    Parameters
+    ----------
+    fname : path-like
+        The loaded file.
+    transform : callable, default: the identity function
+        A function called on each individual line of the file to transform it,
+        before further parsing.
+    fail_on_error : bool, default: False
+        Whether invalid entries should result in an exception or a warning.
+    """
+    import matplotlib as mpl
+    rc_temp = {}
+    with _open_file_or_url(fname) as fd:
+        try:
+            for line_no, line in enumerate(fd, 1):
+                line = transform(line)
+                strippedline = cbook._strip_comment(line)
+                if not strippedline:
+                    continue
+                tup = strippedline.split(':', 1)
+                if len(tup) != 2:
+                    _log.warning('Missing colon in file %r, line %d (%r)',
+                                 fname, line_no, line.rstrip('\n'))
+                    continue
+                key, val = tup
+                key = key.strip()
+                val = val.strip()
+                if val.startswith('"') and val.endswith('"'):
+                    val = val[1:-1]  # strip double quotes
+                if key in rc_temp:
+                    _log.warning('Duplicate key in file %r, line %d (%r)',
+                                 fname, line_no, line.rstrip('\n'))
+                rc_temp[key] = (val, line, line_no)
+        except UnicodeDecodeError:
+            _log.warning('Cannot decode configuration file %r as utf-8.',
+                         fname)
+            raise
+
+    config = RcParams()
+
+    for key, (val, line, line_no) in rc_temp.items():
+        if key in rcsetup._validators:
+            if fail_on_error:
+                config[key] = val  # try to convert to proper type or raise
+            else:
+                try:
+                    config[key] = val  # try to convert to proper type or skip
+                except Exception as msg:
+                    _log.warning('Bad value in file %r, line %d (%r): %s',
+                                 fname, line_no, line.rstrip('\n'), msg)
+        elif key in _deprecated_ignore_map:
+            version, alt_key = _deprecated_ignore_map[key]
+            _api.warn_deprecated(
+                version, name=key, alternative=alt_key, obj_type='rcparam',
+                addendum="Please update your matplotlibrc.")
+        else:
+            # __version__ must be looked up as an attribute to trigger the
+            # module-level __getattr__.
+            version = ('main' if '.post' in mpl.__version__
+                       else f'v{mpl.__version__}')
+            _log.warning("""
+Bad key %(key)s in file %(fname)s, line %(line_no)s (%(line)r)
+You probably need to get an updated matplotlibrc file from
+https://github.com/matplotlib/matplotlib/blob/%(version)s/lib/matplotlib/mpl-data/matplotlibrc
+or from the matplotlib source distribution""",
+                         dict(key=key, fname=fname, line_no=line_no,
+                              line=line.rstrip('\n'), version=version))
+    return config
+
+
+def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
+    """
+    Construct a `RcParams` from file *fname*.
+
+    Parameters
+    ----------
+    fname : str or path-like
+        A file with Matplotlib rc settings.
+    fail_on_error : bool
+        If True, raise an error when the parser fails to convert a parameter.
+    use_default_template : bool
+        If True, initialize with default parameters before updating with those
+        in the given file. If False, the configuration class only contains the
+        parameters specified in the file. (Useful for updating dicts.)
+    """
+    config_from_file = _rc_params_in_file(fname, fail_on_error=fail_on_error)
+
+    if not use_default_template:
+        return config_from_file
+
+    with _api.suppress_matplotlib_deprecation_warning():
+        config = RcParams({**rcParamsDefault, **config_from_file})
+
+    if "".join(config['text.latex.preamble']):
+        _log.info("""
+*****************************************************************
+You have the following UNSUPPORTED LaTeX preamble customizations:
+%s
+Please do not ask for support with these customizations active.
+*****************************************************************
+""", '\n'.join(config['text.latex.preamble']))
+    _log.debug('loaded rc file %s', fname)
+
+    return config
+
+
+rcParamsDefault = _rc_params_in_file(
+    cbook._get_data_path("matplotlibrc"),
+    # Strip leading comment.
+    transform=lambda line: line[1:] if line.startswith("#") else line,
+    fail_on_error=True)
+rcParamsDefault._update_raw(rcsetup._hardcoded_defaults)
+rcParamsDefault._ensure_has_backend()
+
+rcParams = RcParams()  # The global instance.
+rcParams._update_raw(rcParamsDefault)
+rcParams._update_raw(_rc_params_in_file(matplotlib_fname()))
+rcParamsOrig = rcParams.copy()
+with _api.suppress_matplotlib_deprecation_warning():
+    # This also checks that all rcParams are indeed listed in the template.
+    # Assigning to rcsetup.defaultParams is left only for backcompat.
+    defaultParams = rcsetup.defaultParams = {
+        # We want to resolve deprecated rcParams, but not backend...
+        key: [(rcsetup._auto_backend_sentinel if key == "backend" else
+               rcParamsDefault[key]),
+              validator]
+        for key, validator in rcsetup._validators.items()}
+if rcParams['axes.formatter.use_locale']:
+    locale.setlocale(locale.LC_ALL, '')
+
+
+def rc(group, **kwargs):
+    """
+    Set the current `.rcParams`.  *group* is the grouping for the rc, e.g.,
+    for ``lines.linewidth`` the group is ``lines``, for
+    ``axes.facecolor``, the group is ``axes``, and so on.  Group may
+    also be a list or tuple of group names, e.g., (*xtick*, *ytick*).
+    *kwargs* is a dictionary attribute name/value pairs, e.g.,::
+
+      rc('lines', linewidth=2, color='r')
+
+    sets the current `.rcParams` and is equivalent to::
+
+      rcParams['lines.linewidth'] = 2
+      rcParams['lines.color'] = 'r'
+
+    The following aliases are available to save typing for interactive users:
+
+    =====   =================
+    Alias   Property
+    =====   =================
+    'lw'    'linewidth'
+    'ls'    'linestyle'
+    'c'     'color'
+    'fc'    'facecolor'
+    'ec'    'edgecolor'
+    'mew'   'markeredgewidth'
+    'aa'    'antialiased'
+    =====   =================
+
+    Thus you could abbreviate the above call as::
+
+          rc('lines', lw=2, c='r')
+
+    Note you can use python's kwargs dictionary facility to store
+    dictionaries of default parameters.  e.g., you can customize the
+    font rc as follows::
+
+      font = {'family' : 'monospace',
+              'weight' : 'bold',
+              'size'   : 'larger'}
+      rc('font', **font)  # pass in the font dict as kwargs
+
+    This enables you to easily switch between several configurations.  Use
+    ``matplotlib.style.use('default')`` or :func:`~matplotlib.rcdefaults` to
+    restore the default `.rcParams` after changes.
+
+    Notes
+    -----
+    Similar functionality is available by using the normal dict interface, i.e.
+    ``rcParams.update({"lines.linewidth": 2, ...})`` (but ``rcParams.update``
+    does not support abbreviations or grouping).
+    """
+
+    aliases = {
+        'lw':  'linewidth',
+        'ls':  'linestyle',
+        'c':   'color',
+        'fc':  'facecolor',
+        'ec':  'edgecolor',
+        'mew': 'markeredgewidth',
+        'aa':  'antialiased',
+        }
+
+    if isinstance(group, str):
+        group = (group,)
+    for g in group:
+        for k, v in kwargs.items():
+            name = aliases.get(k) or k
+            key = f'{g}.{name}'
+            try:
+                rcParams[key] = v
+            except KeyError as err:
+                raise KeyError(('Unrecognized key "%s" for group "%s" and '
+                                'name "%s"') % (key, g, name)) from err
+
+
+def rcdefaults():
+    """
+    Restore the `.rcParams` from Matplotlib's internal default style.
+
+    Style-blacklisted `.rcParams` (defined in
+    ``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
+
+    See Also
+    --------
+    matplotlib.rc_file_defaults
+        Restore the `.rcParams` from the rc file originally loaded by
+        Matplotlib.
+    matplotlib.style.use
+        Use a specific style file.  Call ``style.use('default')`` to restore
+        the default style.
+    """
+    # Deprecation warnings were already handled when creating rcParamsDefault,
+    # no need to reemit them here.
+    with _api.suppress_matplotlib_deprecation_warning():
+        from .style.core import STYLE_BLACKLIST
+        rcParams.clear()
+        rcParams.update({k: v for k, v in rcParamsDefault.items()
+                         if k not in STYLE_BLACKLIST})
+
+
+def rc_file_defaults():
+    """
+    Restore the `.rcParams` from the original rc file loaded by Matplotlib.
+
+    Style-blacklisted `.rcParams` (defined in
+    ``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
+    """
+    # Deprecation warnings were already handled when creating rcParamsOrig, no
+    # need to reemit them here.
+    with _api.suppress_matplotlib_deprecation_warning():
+        from .style.core import STYLE_BLACKLIST
+        rcParams.update({k: rcParamsOrig[k] for k in rcParamsOrig
+                         if k not in STYLE_BLACKLIST})
+
+
+def rc_file(fname, *, use_default_template=True):
+    """
+    Update `.rcParams` from file.
+
+    Style-blacklisted `.rcParams` (defined in
+    ``matplotlib.style.core.STYLE_BLACKLIST``) are not updated.
+
+    Parameters
+    ----------
+    fname : str or path-like
+        A file with Matplotlib rc settings.
+
+    use_default_template : bool
+        If True, initialize with default parameters before updating with those
+        in the given file. If False, the current configuration persists
+        and only the parameters specified in the file are updated.
+    """
+    # Deprecation warnings were already handled in rc_params_from_file, no need
+    # to reemit them here.
+    with _api.suppress_matplotlib_deprecation_warning():
+        from .style.core import STYLE_BLACKLIST
+        rc_from_file = rc_params_from_file(
+            fname, use_default_template=use_default_template)
+        rcParams.update({k: rc_from_file[k] for k in rc_from_file
+                         if k not in STYLE_BLACKLIST})
+
+
+@contextlib.contextmanager
+def rc_context(rc=None, fname=None):
+    """
+    Return a context manager for temporarily changing rcParams.
+
+    The :rc:`backend` will not be reset by the context manager.
+
+    rcParams changed both through the context manager invocation and
+    in the body of the context will be reset on context exit.
+
+    Parameters
+    ----------
+    rc : dict
+        The rcParams to temporarily set.
+    fname : str or path-like
+        A file with Matplotlib rc settings. If both *fname* and *rc* are given,
+        settings from *rc* take precedence.
+
+    See Also
+    --------
+    :ref:`customizing-with-matplotlibrc-files`
+
+    Examples
+    --------
+    Passing explicit values via a dict::
+
+        with mpl.rc_context({'interactive': False}):
+            fig, ax = plt.subplots()
+            ax.plot(range(3), range(3))
+            fig.savefig('example.png')
+            plt.close(fig)
+
+    Loading settings from a file::
+
+         with mpl.rc_context(fname='print.rc'):
+             plt.plot(x, y)  # uses 'print.rc'
+
+    Setting in the context body::
+
+        with mpl.rc_context():
+            # will be reset
+            mpl.rcParams['lines.linewidth'] = 5
+            plt.plot(x, y)
+
+    """
+    orig = dict(rcParams.copy())
+    del orig['backend']
+    try:
+        if fname:
+            rc_file(fname)
+        if rc:
+            rcParams.update(rc)
+        yield
+    finally:
+        rcParams._update_raw(orig)  # Revert to the original rcs.
+
+
+def use(backend, *, force=True):
+    """
+    Select the backend used for rendering and GUI integration.
+
+    If pyplot is already imported, `~matplotlib.pyplot.switch_backend` is used
+    and if the new backend is different than the current backend, all Figures
+    will be closed.
+
+    Parameters
+    ----------
+    backend : str
+        The backend to switch to.  This can either be one of the standard
+        backend names, which are case-insensitive:
+
+        - interactive backends:
+          GTK3Agg, GTK3Cairo, GTK4Agg, GTK4Cairo, MacOSX, nbAgg, notebook, QtAgg,
+          QtCairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo, Qt5Agg, Qt5Cairo
+
+        - non-interactive backends:
+          agg, cairo, pdf, pgf, ps, svg, template
+
+        or a string of the form: ``module://my.module.name``.
+
+        notebook is a synonym for nbAgg.
+
+        Switching to an interactive backend is not possible if an unrelated
+        event loop has already been started (e.g., switching to GTK3Agg if a
+        TkAgg window has already been opened).  Switching to a non-interactive
+        backend is always possible.
+
+    force : bool, default: True
+        If True (the default), raise an `ImportError` if the backend cannot be
+        set up (either because it fails to import, or because an incompatible
+        GUI interactive framework is already running); if False, silently
+        ignore the failure.
+
+    See Also
+    --------
+    :ref:`backends`
+    matplotlib.get_backend
+    matplotlib.pyplot.switch_backend
+
+    """
+    name = rcsetup.validate_backend(backend)
+    # don't (prematurely) resolve the "auto" backend setting
+    if rcParams._get_backend_or_none() == name:
+        # Nothing to do if the requested backend is already set
+        pass
+    else:
+        # if pyplot is not already imported, do not import it.  Doing
+        # so may trigger a `plt.switch_backend` to the _default_ backend
+        # before we get a chance to change to the one the user just requested
+        plt = sys.modules.get('matplotlib.pyplot')
+        # if pyplot is imported, then try to change backends
+        if plt is not None:
+            try:
+                # we need this import check here to re-raise if the
+                # user does not have the libraries to support their
+                # chosen backend installed.
+                plt.switch_backend(name)
+            except ImportError:
+                if force:
+                    raise
+        # if we have not imported pyplot, then we can set the rcParam
+        # value which will be respected when the user finally imports
+        # pyplot
+        else:
+            rcParams['backend'] = backend
+    # if the user has asked for a given backend, do not helpfully
+    # fallback
+    rcParams['backend_fallback'] = False
+
+
+if os.environ.get('MPLBACKEND'):
+    rcParams['backend'] = os.environ.get('MPLBACKEND')
+
+
+def get_backend(*, auto_select=True):
+    """
+    Return the name of the current backend.
+
+    Parameters
+    ----------
+    auto_select : bool, default: True
+        Whether to trigger backend resolution if no backend has been
+        selected so far. If True, this ensures that a valid backend
+        is returned. If False, this returns None if no backend has been
+        selected so far.
+
+        .. versionadded:: 3.10
+
+        .. admonition:: Provisional
+
+           The *auto_select* flag is provisional. It may be changed or removed
+           without prior warning.
+
+    See Also
+    --------
+    matplotlib.use
+    """
+    if auto_select:
+        return rcParams['backend']
+    else:
+        backend = rcParams._get('backend')
+        if backend is rcsetup._auto_backend_sentinel:
+            return None
+        else:
+            return backend
+
+
+def interactive(b):
+    """
+    Set whether to redraw after every plotting command (e.g. `.pyplot.xlabel`).
+    """
+    rcParams['interactive'] = b
+
+
+def is_interactive():
+    """
+    Return whether to redraw after every plotting command.
+
+    .. note::
+
+        This function is only intended for use in backends. End users should
+        use `.pyplot.isinteractive` instead.
+    """
+    return rcParams['interactive']
+
+
+def _val_or_rc(val, rc_name):
+    """
+    If *val* is None, return ``mpl.rcParams[rc_name]``, otherwise return val.
+    """
+    return val if val is not None else rcParams[rc_name]
+
+
+def _init_tests():
+    # The version of FreeType to install locally for running the tests. This must match
+    # the value in `meson.build`.
+    LOCAL_FREETYPE_VERSION = '2.6.1'
+
+    from matplotlib import ft2font
+    if (ft2font.__freetype_version__ != LOCAL_FREETYPE_VERSION or
+            ft2font.__freetype_build_type__ != 'local'):
+        _log.warning(
+            "Matplotlib is not built with the correct FreeType version to run tests.  "
+            "Rebuild without setting system-freetype=true in Meson setup options.  "
+            "Expect many image comparison failures below.  "
+            "Expected freetype version %s.  "
+            "Found freetype version %s.  "
+            "Freetype build type is %slocal.",
+            LOCAL_FREETYPE_VERSION,
+            ft2font.__freetype_version__,
+            "" if ft2font.__freetype_build_type__ == 'local' else "not ")
+
+
+def _replacer(data, value):
+    """
+    Either returns ``data[value]`` or passes ``data`` back, converts either to
+    a sequence.
+    """
+    try:
+        # if key isn't a string don't bother
+        if isinstance(value, str):
+            # try to use __getitem__
+            value = data[value]
+    except Exception:
+        # key does not exist, silently fall back to key
+        pass
+    return cbook.sanitize_sequence(value)
+
+
+def _label_from_arg(y, default_name):
+    try:
+        return y.name
+    except AttributeError:
+        if isinstance(default_name, str):
+            return default_name
+    return None
+
+
+def _add_data_doc(docstring, replace_names):
+    """
+    Add documentation for a *data* field to the given docstring.
+
+    Parameters
+    ----------
+    docstring : str
+        The input docstring.
+    replace_names : list of str or None
+        The list of parameter names which arguments should be replaced by
+        ``data[name]`` (if ``data[name]`` does not throw an exception).  If
+        None, replacement is attempted for all arguments.
+
+    Returns
+    -------
+    str
+        The augmented docstring.
+    """
+    if (docstring is None
+            or replace_names is not None and len(replace_names) == 0):
+        return docstring
+    docstring = inspect.cleandoc(docstring)
+
+    data_doc = ("""\
+    If given, all parameters also accept a string ``s``, which is
+    interpreted as ``data[s]`` if ``s`` is a key in ``data``."""
+                if replace_names is None else f"""\
+    If given, the following parameters also accept a string ``s``, which is
+    interpreted as ``data[s]`` if ``s`` is a key in ``data``:
+
+    {', '.join(map('*{}*'.format, replace_names))}""")
+    # using string replacement instead of formatting has the advantages
+    # 1) simpler indent handling
+    # 2) prevent problems with formatting characters '{', '%' in the docstring
+    if _log.level <= logging.DEBUG:
+        # test_data_parameter_replacement() tests against these log messages
+        # make sure to keep message and test in sync
+        if "data : indexable object, optional" not in docstring:
+            _log.debug("data parameter docstring error: no data parameter")
+        if 'DATA_PARAMETER_PLACEHOLDER' not in docstring:
+            _log.debug("data parameter docstring error: missing placeholder")
+    return docstring.replace('    DATA_PARAMETER_PLACEHOLDER', data_doc)
+
+
+def _preprocess_data(func=None, *, replace_names=None, label_namer=None):
+    """
+    A decorator to add a 'data' kwarg to a function.
+
+    When applied::
+
+        @_preprocess_data()
+        def func(ax, *args, **kwargs): ...
+
+    the signature is modified to ``decorated(ax, *args, data=None, **kwargs)``
+    with the following behavior:
+
+    - if called with ``data=None``, forward the other arguments to ``func``;
+    - otherwise, *data* must be a mapping; for any argument passed in as a
+      string ``name``, replace the argument by ``data[name]`` (if this does not
+      throw an exception), then forward the arguments to ``func``.
+
+    In either case, any argument that is a `MappingView` is also converted to a
+    list.
+
+    Parameters
+    ----------
+    replace_names : list of str or None, default: None
+        The list of parameter names for which lookup into *data* should be
+        attempted. If None, replacement is attempted for all arguments.
+    label_namer : str, default: None
+        If set e.g. to "namer" (which must be a kwarg in the function's
+        signature -- not as ``**kwargs``), if the *namer* argument passed in is
+        a (string) key of *data* and no *label* kwarg is passed, then use the
+        (string) value of the *namer* as *label*. ::
+
+            @_preprocess_data(label_namer="foo")
+            def func(foo, label=None): ...
+
+            func("key", data={"key": value})
+            # is equivalent to
+            func.__wrapped__(value, label="key")
+    """
+
+    if func is None:  # Return the actual decorator.
+        return functools.partial(
+            _preprocess_data,
+            replace_names=replace_names, label_namer=label_namer)
+
+    sig = inspect.signature(func)
+    varargs_name = None
+    varkwargs_name = None
+    arg_names = []
+    params = list(sig.parameters.values())
+    for p in params:
+        if p.kind is Parameter.VAR_POSITIONAL:
+            varargs_name = p.name
+        elif p.kind is Parameter.VAR_KEYWORD:
+            varkwargs_name = p.name
+        else:
+            arg_names.append(p.name)
+    data_param = Parameter("data", Parameter.KEYWORD_ONLY, default=None)
+    if varkwargs_name:
+        params.insert(-1, data_param)
+    else:
+        params.append(data_param)
+    new_sig = sig.replace(parameters=params)
+    arg_names = arg_names[1:]  # remove the first "ax" / self arg
+
+    assert {*arg_names}.issuperset(replace_names or []) or varkwargs_name, (
+        "Matplotlib internal error: invalid replace_names "
+        f"({replace_names!r}) for {func.__name__!r}")
+    assert label_namer is None or label_namer in arg_names, (
+        "Matplotlib internal error: invalid label_namer "
+        f"({label_namer!r}) for {func.__name__!r}")
+
+    @functools.wraps(func)
+    def inner(ax, *args, data=None, **kwargs):
+        if data is None:
+            return func(
+                ax,
+                *map(cbook.sanitize_sequence, args),
+                **{k: cbook.sanitize_sequence(v) for k, v in kwargs.items()})
+
+        bound = new_sig.bind(ax, *args, **kwargs)
+        auto_label = (bound.arguments.get(label_namer)
+                      or bound.kwargs.get(label_namer))
+
+        for k, v in bound.arguments.items():
+            if k == varkwargs_name:
+                for k1, v1 in v.items():
+                    if replace_names is None or k1 in replace_names:
+                        v[k1] = _replacer(data, v1)
+            elif k == varargs_name:
+                if replace_names is None:
+                    bound.arguments[k] = tuple(_replacer(data, v1) for v1 in v)
+            else:
+                if replace_names is None or k in replace_names:
+                    bound.arguments[k] = _replacer(data, v)
+
+        new_args = bound.args
+        new_kwargs = bound.kwargs
+
+        args_and_kwargs = {**bound.arguments, **bound.kwargs}
+        if label_namer and "label" not in args_and_kwargs:
+            new_kwargs["label"] = _label_from_arg(
+                args_and_kwargs.get(label_namer), auto_label)
+
+        return func(*new_args, **new_kwargs)
+
+    inner.__doc__ = _add_data_doc(inner.__doc__, replace_names)
+    inner.__signature__ = new_sig
+    return inner
+
+
+_log.debug('interactive is %s', is_interactive())
+_log.debug('platform is %s', sys.platform)
+
+
+@_api.deprecated("3.10", alternative="matplotlib.cbook.sanitize_sequence")
+def sanitize_sequence(data):
+    return cbook.sanitize_sequence(data)
+
+
+@_api.deprecated("3.10", alternative="matplotlib.rcsetup.validate_backend")
+def validate_backend(s):
+    return rcsetup.validate_backend(s)
+
+
+# workaround: we must defer colormaps import to after loading rcParams, because
+# colormap creation depends on rcParams
+from matplotlib.cm import _colormaps as colormaps  # noqa: E402
+from matplotlib.cm import _multivar_colormaps as multivar_colormaps  # noqa: E402
+from matplotlib.cm import _bivar_colormaps as bivar_colormaps  # noqa: E402
+from matplotlib.colors import _color_sequences as color_sequences  # noqa: E402
diff --git a/lib/python3.12/site-packages/matplotlib/__init__.pyi b/lib/python3.12/site-packages/matplotlib/__init__.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..88058ffd7def28740b4942d3851a5f43e49b086a
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/__init__.pyi
@@ -0,0 +1,124 @@
+__all__ = [
+    "__bibtex__",
+    "__version__",
+    "__version_info__",
+    "set_loglevel",
+    "ExecutableNotFoundError",
+    "get_configdir",
+    "get_cachedir",
+    "get_data_path",
+    "matplotlib_fname",
+    "MatplotlibDeprecationWarning",
+    "RcParams",
+    "rc_params",
+    "rc_params_from_file",
+    "rcParamsDefault",
+    "rcParams",
+    "rcParamsOrig",
+    "defaultParams",
+    "rc",
+    "rcdefaults",
+    "rc_file_defaults",
+    "rc_file",
+    "rc_context",
+    "use",
+    "get_backend",
+    "interactive",
+    "is_interactive",
+    "colormaps",
+    "color_sequences",
+]
+
+import os
+from pathlib import Path
+
+from collections.abc import Callable, Generator
+import contextlib
+from packaging.version import Version
+
+from matplotlib._api import MatplotlibDeprecationWarning
+from typing import Any, Literal, NamedTuple, overload
+
+class _VersionInfo(NamedTuple):
+    major: int
+    minor: int
+    micro: int
+    releaselevel: str
+    serial: int
+
+__bibtex__: str
+__version__: str
+__version_info__: _VersionInfo
+
+def set_loglevel(level: str) -> None: ...
+
+class _ExecInfo(NamedTuple):
+    executable: str
+    raw_version: str
+    version: Version
+
+class ExecutableNotFoundError(FileNotFoundError): ...
+
+def _get_executable_info(name: str) -> _ExecInfo: ...
+def get_configdir() -> str: ...
+def get_cachedir() -> str: ...
+def get_data_path() -> str: ...
+def matplotlib_fname() -> str: ...
+
+class RcParams(dict[str, Any]):
+    validate: dict[str, Callable]
+    def __init__(self, *args, **kwargs) -> None: ...
+    def _set(self, key: str, val: Any) -> None: ...
+    def _get(self, key: str) -> Any: ...
+
+    def _update_raw(self, other_params: dict | RcParams) -> None: ...
+
+    def _ensure_has_backend(self) -> None: ...
+    def __setitem__(self, key: str, val: Any) -> None: ...
+    def __getitem__(self, key: str) -> Any: ...
+    def __iter__(self) -> Generator[str, None, None]: ...
+    def __len__(self) -> int: ...
+    def find_all(self, pattern: str) -> RcParams: ...
+    def copy(self) -> RcParams: ...
+
+def rc_params(fail_on_error: bool = ...) -> RcParams: ...
+def rc_params_from_file(
+    fname: str | Path | os.PathLike,
+    fail_on_error: bool = ...,
+    use_default_template: bool = ...,
+) -> RcParams: ...
+
+rcParamsDefault: RcParams
+rcParams: RcParams
+rcParamsOrig: RcParams
+defaultParams: dict[str, Any]
+
+def rc(group: str, **kwargs) -> None: ...
+def rcdefaults() -> None: ...
+def rc_file_defaults() -> None: ...
+def rc_file(
+    fname: str | Path | os.PathLike, *, use_default_template: bool = ...
+) -> None: ...
+@contextlib.contextmanager
+def rc_context(
+    rc: dict[str, Any] | None = ..., fname: str | Path | os.PathLike | None = ...
+) -> Generator[None, None, None]: ...
+def use(backend: str, *, force: bool = ...) -> None: ...
+@overload
+def get_backend(*, auto_select: Literal[True] = True) -> str: ...
+@overload
+def get_backend(*, auto_select: Literal[False]) -> str | None: ...
+def interactive(b: bool) -> None: ...
+def is_interactive() -> bool: ...
+
+def _preprocess_data(
+    func: Callable | None = ...,
+    *,
+    replace_names: list[str] | None = ...,
+    label_namer: str | None = ...
+) -> Callable: ...
+
+from matplotlib.cm import _colormaps as colormaps  # noqa: E402
+from matplotlib.cm import _multivar_colormaps as multivar_colormaps  # noqa: E402
+from matplotlib.cm import _bivar_colormaps as bivar_colormaps  # noqa: E402
+from matplotlib.colors import _color_sequences as color_sequences  # noqa: E402
diff --git a/lib/python3.12/site-packages/matplotlib/_blocking_input.py b/lib/python3.12/site-packages/matplotlib/_blocking_input.py
new file mode 100644
index 0000000000000000000000000000000000000000..45f0775714431e73c283fede1f0cf12d7eaabb8d
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_blocking_input.py
@@ -0,0 +1,30 @@
+def blocking_input_loop(figure, event_names, timeout, handler):
+    """
+    Run *figure*'s event loop while listening to interactive events.
+
+    The events listed in *event_names* are passed to *handler*.
+
+    This function is used to implement `.Figure.waitforbuttonpress`,
+    `.Figure.ginput`, and `.Axes.clabel`.
+
+    Parameters
+    ----------
+    figure : `~matplotlib.figure.Figure`
+    event_names : list of str
+        The names of the events passed to *handler*.
+    timeout : float
+        If positive, the event loop is stopped after *timeout* seconds.
+    handler : Callable[[Event], Any]
+        Function called for each event; it can force an early exit of the event
+        loop by calling ``canvas.stop_event_loop()``.
+    """
+    if figure.canvas.manager:
+        figure.show()  # Ensure that the figure is shown if we are managing it.
+    # Connect the events to the on_event function call.
+    cids = [figure.canvas.mpl_connect(name, handler) for name in event_names]
+    try:
+        figure.canvas.start_event_loop(timeout)  # Start event loop.
+    finally:  # Run even on exception like ctrl-c.
+        # Disconnect the callbacks.
+        for cid in cids:
+            figure.canvas.mpl_disconnect(cid)
diff --git a/lib/python3.12/site-packages/matplotlib/_c_internal_utils.pyi b/lib/python3.12/site-packages/matplotlib/_c_internal_utils.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..ccc172cde27a35ad930cc618b86fdf5c8d44728e
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_c_internal_utils.pyi
@@ -0,0 +1,8 @@
+def display_is_valid() -> bool: ...
+def xdisplay_is_valid() -> bool: ...
+
+def Win32_GetForegroundWindow() -> int | None: ...
+def Win32_SetForegroundWindow(hwnd: int) -> None: ...
+def Win32_SetProcessDpiAwareness_max() -> None: ...
+def Win32_SetCurrentProcessExplicitAppUserModelID(appid: str) -> None: ...
+def Win32_GetCurrentProcessExplicitAppUserModelID() -> str | None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/_cm.py b/lib/python3.12/site-packages/matplotlib/_cm.py
new file mode 100644
index 0000000000000000000000000000000000000000..b942d1697934789f26c522b3e7592671540919a6
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_cm.py
@@ -0,0 +1,1460 @@
+"""
+Nothing here but dictionaries for generating LinearSegmentedColormaps,
+and a dictionary of these dictionaries.
+
+Documentation for each is in pyplot.colormaps().  Please update this
+with the purpose and type of your colormap if you add data for one here.
+"""
+
+from functools import partial
+
+import numpy as np
+
+_binary_data = {
+    'red':    ((0., 1., 1.), (1., 0., 0.)),
+    'green':  ((0., 1., 1.), (1., 0., 0.)),
+    'blue':   ((0., 1., 1.), (1., 0., 0.))
+    }
+
+_autumn_data = {'red':   ((0., 1.0, 1.0), (1.0, 1.0, 1.0)),
+                'green': ((0., 0., 0.), (1.0, 1.0, 1.0)),
+                'blue':  ((0., 0., 0.), (1.0, 0., 0.))}
+
+_bone_data = {'red':   ((0., 0., 0.),
+                        (0.746032, 0.652778, 0.652778),
+                        (1.0, 1.0, 1.0)),
+              'green': ((0., 0., 0.),
+                        (0.365079, 0.319444, 0.319444),
+                        (0.746032, 0.777778, 0.777778),
+                        (1.0, 1.0, 1.0)),
+              'blue':  ((0., 0., 0.),
+                        (0.365079, 0.444444, 0.444444),
+                        (1.0, 1.0, 1.0))}
+
+_cool_data = {'red':   ((0., 0., 0.), (1.0, 1.0, 1.0)),
+              'green': ((0., 1., 1.), (1.0, 0.,  0.)),
+              'blue':  ((0., 1., 1.), (1.0, 1.,  1.))}
+
+_copper_data = {'red':   ((0., 0., 0.),
+                          (0.809524, 1.000000, 1.000000),
+                          (1.0, 1.0, 1.0)),
+                'green': ((0., 0., 0.),
+                          (1.0, 0.7812, 0.7812)),
+                'blue':  ((0., 0., 0.),
+                          (1.0, 0.4975, 0.4975))}
+
+def _flag_red(x): return 0.75 * np.sin((x * 31.5 + 0.25) * np.pi) + 0.5
+def _flag_green(x): return np.sin(x * 31.5 * np.pi)
+def _flag_blue(x): return 0.75 * np.sin((x * 31.5 - 0.25) * np.pi) + 0.5
+_flag_data = {'red': _flag_red, 'green': _flag_green, 'blue': _flag_blue}
+
+def _prism_red(x): return 0.75 * np.sin((x * 20.9 + 0.25) * np.pi) + 0.67
+def _prism_green(x): return 0.75 * np.sin((x * 20.9 - 0.25) * np.pi) + 0.33
+def _prism_blue(x): return -1.1 * np.sin((x * 20.9) * np.pi)
+_prism_data = {'red': _prism_red, 'green': _prism_green, 'blue': _prism_blue}
+
+def _ch_helper(gamma, s, r, h, p0, p1, x):
+    """Helper function for generating picklable cubehelix colormaps."""
+    # Apply gamma factor to emphasise low or high intensity values
+    xg = x ** gamma
+    # Calculate amplitude and angle of deviation from the black to white
+    # diagonal in the plane of constant perceived intensity.
+    a = h * xg * (1 - xg) / 2
+    phi = 2 * np.pi * (s / 3 + r * x)
+    return xg + a * (p0 * np.cos(phi) + p1 * np.sin(phi))
+
+def cubehelix(gamma=1.0, s=0.5, r=-1.5, h=1.0):
+    """
+    Return custom data dictionary of (r, g, b) conversion functions, which can
+    be used with `.ColormapRegistry.register`, for the cubehelix color scheme.
+
+    Unlike most other color schemes cubehelix was designed by D.A. Green to
+    be monotonically increasing in terms of perceived brightness.
+    Also, when printed on a black and white postscript printer, the scheme
+    results in a greyscale with monotonically increasing brightness.
+    This color scheme is named cubehelix because the (r, g, b) values produced
+    can be visualised as a squashed helix around the diagonal in the
+    (r, g, b) color cube.
+
+    For a unit color cube (i.e. 3D coordinates for (r, g, b) each in the
+    range 0 to 1) the color scheme starts at (r, g, b) = (0, 0, 0), i.e. black,
+    and finishes at (r, g, b) = (1, 1, 1), i.e. white. For some fraction *x*,
+    between 0 and 1, the color is the corresponding grey value at that
+    fraction along the black to white diagonal (x, x, x) plus a color
+    element. This color element is calculated in a plane of constant
+    perceived intensity and controlled by the following parameters.
+
+    Parameters
+    ----------
+    gamma : float, default: 1
+        Gamma factor emphasizing either low intensity values (gamma < 1), or
+        high intensity values (gamma > 1).
+    s : float, default: 0.5 (purple)
+        The starting color.
+    r : float, default: -1.5
+        The number of r, g, b rotations in color that are made from the start
+        to the end of the color scheme.  The default of -1.5 corresponds to ->
+        B -> G -> R -> B.
+    h : float, default: 1
+        The hue, i.e. how saturated the colors are. If this parameter is zero
+        then the color scheme is purely a greyscale.
+    """
+    return {'red': partial(_ch_helper, gamma, s, r, h, -0.14861, 1.78277),
+            'green': partial(_ch_helper, gamma, s, r, h, -0.29227, -0.90649),
+            'blue': partial(_ch_helper, gamma, s, r, h, 1.97294, 0.0)}
+
+_cubehelix_data = cubehelix()
+
+_bwr_data = ((0.0, 0.0, 1.0), (1.0, 1.0, 1.0), (1.0, 0.0, 0.0))
+_brg_data = ((0.0, 0.0, 1.0), (1.0, 0.0, 0.0), (0.0, 1.0, 0.0))
+
+# Gnuplot palette functions
+def _g0(x): return 0
+def _g1(x): return 0.5
+def _g2(x): return 1
+def _g3(x): return x
+def _g4(x): return x ** 2
+def _g5(x): return x ** 3
+def _g6(x): return x ** 4
+def _g7(x): return np.sqrt(x)
+def _g8(x): return np.sqrt(np.sqrt(x))
+def _g9(x): return np.sin(x * np.pi / 2)
+def _g10(x): return np.cos(x * np.pi / 2)
+def _g11(x): return np.abs(x - 0.5)
+def _g12(x): return (2 * x - 1) ** 2
+def _g13(x): return np.sin(x * np.pi)
+def _g14(x): return np.abs(np.cos(x * np.pi))
+def _g15(x): return np.sin(x * 2 * np.pi)
+def _g16(x): return np.cos(x * 2 * np.pi)
+def _g17(x): return np.abs(np.sin(x * 2 * np.pi))
+def _g18(x): return np.abs(np.cos(x * 2 * np.pi))
+def _g19(x): return np.abs(np.sin(x * 4 * np.pi))
+def _g20(x): return np.abs(np.cos(x * 4 * np.pi))
+def _g21(x): return 3 * x
+def _g22(x): return 3 * x - 1
+def _g23(x): return 3 * x - 2
+def _g24(x): return np.abs(3 * x - 1)
+def _g25(x): return np.abs(3 * x - 2)
+def _g26(x): return (3 * x - 1) / 2
+def _g27(x): return (3 * x - 2) / 2
+def _g28(x): return np.abs((3 * x - 1) / 2)
+def _g29(x): return np.abs((3 * x - 2) / 2)
+def _g30(x): return x / 0.32 - 0.78125
+def _g31(x): return 2 * x - 0.84
+def _g32(x):
+    ret = np.zeros(len(x))
+    m = (x < 0.25)
+    ret[m] = 4 * x[m]
+    m = (x >= 0.25) & (x < 0.92)
+    ret[m] = -2 * x[m] + 1.84
+    m = (x >= 0.92)
+    ret[m] = x[m] / 0.08 - 11.5
+    return ret
+def _g33(x): return np.abs(2 * x - 0.5)
+def _g34(x): return 2 * x
+def _g35(x): return 2 * x - 0.5
+def _g36(x): return 2 * x - 1
+
+gfunc = {i: globals()[f"_g{i}"] for i in range(37)}
+
+_gnuplot_data = {
+        'red': gfunc[7],
+        'green': gfunc[5],
+        'blue': gfunc[15],
+}
+
+_gnuplot2_data = {
+        'red': gfunc[30],
+        'green': gfunc[31],
+        'blue': gfunc[32],
+}
+
+_ocean_data = {
+        'red': gfunc[23],
+        'green': gfunc[28],
+        'blue': gfunc[3],
+}
+
+_afmhot_data = {
+        'red': gfunc[34],
+        'green': gfunc[35],
+        'blue': gfunc[36],
+}
+
+_rainbow_data = {
+        'red': gfunc[33],
+        'green': gfunc[13],
+        'blue': gfunc[10],
+}
+
+_seismic_data = (
+        (0.0, 0.0, 0.3), (0.0, 0.0, 1.0),
+        (1.0, 1.0, 1.0), (1.0, 0.0, 0.0),
+        (0.5, 0.0, 0.0))
+
+_terrain_data = (
+        (0.00, (0.2, 0.2, 0.6)),
+        (0.15, (0.0, 0.6, 1.0)),
+        (0.25, (0.0, 0.8, 0.4)),
+        (0.50, (1.0, 1.0, 0.6)),
+        (0.75, (0.5, 0.36, 0.33)),
+        (1.00, (1.0, 1.0, 1.0)))
+
+_gray_data = {'red':   ((0., 0, 0), (1., 1, 1)),
+              'green': ((0., 0, 0), (1., 1, 1)),
+              'blue':  ((0., 0, 0), (1., 1, 1))}
+
+_hot_data = {'red':   ((0., 0.0416, 0.0416),
+                       (0.365079, 1.000000, 1.000000),
+                       (1.0, 1.0, 1.0)),
+             'green': ((0., 0., 0.),
+                       (0.365079, 0.000000, 0.000000),
+                       (0.746032, 1.000000, 1.000000),
+                       (1.0, 1.0, 1.0)),
+             'blue':  ((0., 0., 0.),
+                       (0.746032, 0.000000, 0.000000),
+                       (1.0, 1.0, 1.0))}
+
+_hsv_data = {'red':   ((0., 1., 1.),
+                       (0.158730, 1.000000, 1.000000),
+                       (0.174603, 0.968750, 0.968750),
+                       (0.333333, 0.031250, 0.031250),
+                       (0.349206, 0.000000, 0.000000),
+                       (0.666667, 0.000000, 0.000000),
+                       (0.682540, 0.031250, 0.031250),
+                       (0.841270, 0.968750, 0.968750),
+                       (0.857143, 1.000000, 1.000000),
+                       (1.0, 1.0, 1.0)),
+             'green': ((0., 0., 0.),
+                       (0.158730, 0.937500, 0.937500),
+                       (0.174603, 1.000000, 1.000000),
+                       (0.507937, 1.000000, 1.000000),
+                       (0.666667, 0.062500, 0.062500),
+                       (0.682540, 0.000000, 0.000000),
+                       (1.0, 0., 0.)),
+             'blue':  ((0., 0., 0.),
+                       (0.333333, 0.000000, 0.000000),
+                       (0.349206, 0.062500, 0.062500),
+                       (0.507937, 1.000000, 1.000000),
+                       (0.841270, 1.000000, 1.000000),
+                       (0.857143, 0.937500, 0.937500),
+                       (1.0, 0.09375, 0.09375))}
+
+_jet_data = {'red':   ((0.00, 0, 0),
+                       (0.35, 0, 0),
+                       (0.66, 1, 1),
+                       (0.89, 1, 1),
+                       (1.00, 0.5, 0.5)),
+             'green': ((0.000, 0, 0),
+                       (0.125, 0, 0),
+                       (0.375, 1, 1),
+                       (0.640, 1, 1),
+                       (0.910, 0, 0),
+                       (1.000, 0, 0)),
+             'blue':  ((0.00, 0.5, 0.5),
+                       (0.11, 1, 1),
+                       (0.34, 1, 1),
+                       (0.65, 0, 0),
+                       (1.00, 0, 0))}
+
+_pink_data = {'red':   ((0., 0.1178, 0.1178), (0.015873, 0.195857, 0.195857),
+                        (0.031746, 0.250661, 0.250661),
+                        (0.047619, 0.295468, 0.295468),
+                        (0.063492, 0.334324, 0.334324),
+                        (0.079365, 0.369112, 0.369112),
+                        (0.095238, 0.400892, 0.400892),
+                        (0.111111, 0.430331, 0.430331),
+                        (0.126984, 0.457882, 0.457882),
+                        (0.142857, 0.483867, 0.483867),
+                        (0.158730, 0.508525, 0.508525),
+                        (0.174603, 0.532042, 0.532042),
+                        (0.190476, 0.554563, 0.554563),
+                        (0.206349, 0.576204, 0.576204),
+                        (0.222222, 0.597061, 0.597061),
+                        (0.238095, 0.617213, 0.617213),
+                        (0.253968, 0.636729, 0.636729),
+                        (0.269841, 0.655663, 0.655663),
+                        (0.285714, 0.674066, 0.674066),
+                        (0.301587, 0.691980, 0.691980),
+                        (0.317460, 0.709441, 0.709441),
+                        (0.333333, 0.726483, 0.726483),
+                        (0.349206, 0.743134, 0.743134),
+                        (0.365079, 0.759421, 0.759421),
+                        (0.380952, 0.766356, 0.766356),
+                        (0.396825, 0.773229, 0.773229),
+                        (0.412698, 0.780042, 0.780042),
+                        (0.428571, 0.786796, 0.786796),
+                        (0.444444, 0.793492, 0.793492),
+                        (0.460317, 0.800132, 0.800132),
+                        (0.476190, 0.806718, 0.806718),
+                        (0.492063, 0.813250, 0.813250),
+                        (0.507937, 0.819730, 0.819730),
+                        (0.523810, 0.826160, 0.826160),
+                        (0.539683, 0.832539, 0.832539),
+                        (0.555556, 0.838870, 0.838870),
+                        (0.571429, 0.845154, 0.845154),
+                        (0.587302, 0.851392, 0.851392),
+                        (0.603175, 0.857584, 0.857584),
+                        (0.619048, 0.863731, 0.863731),
+                        (0.634921, 0.869835, 0.869835),
+                        (0.650794, 0.875897, 0.875897),
+                        (0.666667, 0.881917, 0.881917),
+                        (0.682540, 0.887896, 0.887896),
+                        (0.698413, 0.893835, 0.893835),
+                        (0.714286, 0.899735, 0.899735),
+                        (0.730159, 0.905597, 0.905597),
+                        (0.746032, 0.911421, 0.911421),
+                        (0.761905, 0.917208, 0.917208),
+                        (0.777778, 0.922958, 0.922958),
+                        (0.793651, 0.928673, 0.928673),
+                        (0.809524, 0.934353, 0.934353),
+                        (0.825397, 0.939999, 0.939999),
+                        (0.841270, 0.945611, 0.945611),
+                        (0.857143, 0.951190, 0.951190),
+                        (0.873016, 0.956736, 0.956736),
+                        (0.888889, 0.962250, 0.962250),
+                        (0.904762, 0.967733, 0.967733),
+                        (0.920635, 0.973185, 0.973185),
+                        (0.936508, 0.978607, 0.978607),
+                        (0.952381, 0.983999, 0.983999),
+                        (0.968254, 0.989361, 0.989361),
+                        (0.984127, 0.994695, 0.994695), (1.0, 1.0, 1.0)),
+              'green': ((0., 0., 0.), (0.015873, 0.102869, 0.102869),
+                        (0.031746, 0.145479, 0.145479),
+                        (0.047619, 0.178174, 0.178174),
+                        (0.063492, 0.205738, 0.205738),
+                        (0.079365, 0.230022, 0.230022),
+                        (0.095238, 0.251976, 0.251976),
+                        (0.111111, 0.272166, 0.272166),
+                        (0.126984, 0.290957, 0.290957),
+                        (0.142857, 0.308607, 0.308607),
+                        (0.158730, 0.325300, 0.325300),
+                        (0.174603, 0.341178, 0.341178),
+                        (0.190476, 0.356348, 0.356348),
+                        (0.206349, 0.370899, 0.370899),
+                        (0.222222, 0.384900, 0.384900),
+                        (0.238095, 0.398410, 0.398410),
+                        (0.253968, 0.411476, 0.411476),
+                        (0.269841, 0.424139, 0.424139),
+                        (0.285714, 0.436436, 0.436436),
+                        (0.301587, 0.448395, 0.448395),
+                        (0.317460, 0.460044, 0.460044),
+                        (0.333333, 0.471405, 0.471405),
+                        (0.349206, 0.482498, 0.482498),
+                        (0.365079, 0.493342, 0.493342),
+                        (0.380952, 0.517549, 0.517549),
+                        (0.396825, 0.540674, 0.540674),
+                        (0.412698, 0.562849, 0.562849),
+                        (0.428571, 0.584183, 0.584183),
+                        (0.444444, 0.604765, 0.604765),
+                        (0.460317, 0.624669, 0.624669),
+                        (0.476190, 0.643958, 0.643958),
+                        (0.492063, 0.662687, 0.662687),
+                        (0.507937, 0.680900, 0.680900),
+                        (0.523810, 0.698638, 0.698638),
+                        (0.539683, 0.715937, 0.715937),
+                        (0.555556, 0.732828, 0.732828),
+                        (0.571429, 0.749338, 0.749338),
+                        (0.587302, 0.765493, 0.765493),
+                        (0.603175, 0.781313, 0.781313),
+                        (0.619048, 0.796819, 0.796819),
+                        (0.634921, 0.812029, 0.812029),
+                        (0.650794, 0.826960, 0.826960),
+                        (0.666667, 0.841625, 0.841625),
+                        (0.682540, 0.856040, 0.856040),
+                        (0.698413, 0.870216, 0.870216),
+                        (0.714286, 0.884164, 0.884164),
+                        (0.730159, 0.897896, 0.897896),
+                        (0.746032, 0.911421, 0.911421),
+                        (0.761905, 0.917208, 0.917208),
+                        (0.777778, 0.922958, 0.922958),
+                        (0.793651, 0.928673, 0.928673),
+                        (0.809524, 0.934353, 0.934353),
+                        (0.825397, 0.939999, 0.939999),
+                        (0.841270, 0.945611, 0.945611),
+                        (0.857143, 0.951190, 0.951190),
+                        (0.873016, 0.956736, 0.956736),
+                        (0.888889, 0.962250, 0.962250),
+                        (0.904762, 0.967733, 0.967733),
+                        (0.920635, 0.973185, 0.973185),
+                        (0.936508, 0.978607, 0.978607),
+                        (0.952381, 0.983999, 0.983999),
+                        (0.968254, 0.989361, 0.989361),
+                        (0.984127, 0.994695, 0.994695), (1.0, 1.0, 1.0)),
+              'blue':  ((0., 0., 0.), (0.015873, 0.102869, 0.102869),
+                        (0.031746, 0.145479, 0.145479),
+                        (0.047619, 0.178174, 0.178174),
+                        (0.063492, 0.205738, 0.205738),
+                        (0.079365, 0.230022, 0.230022),
+                        (0.095238, 0.251976, 0.251976),
+                        (0.111111, 0.272166, 0.272166),
+                        (0.126984, 0.290957, 0.290957),
+                        (0.142857, 0.308607, 0.308607),
+                        (0.158730, 0.325300, 0.325300),
+                        (0.174603, 0.341178, 0.341178),
+                        (0.190476, 0.356348, 0.356348),
+                        (0.206349, 0.370899, 0.370899),
+                        (0.222222, 0.384900, 0.384900),
+                        (0.238095, 0.398410, 0.398410),
+                        (0.253968, 0.411476, 0.411476),
+                        (0.269841, 0.424139, 0.424139),
+                        (0.285714, 0.436436, 0.436436),
+                        (0.301587, 0.448395, 0.448395),
+                        (0.317460, 0.460044, 0.460044),
+                        (0.333333, 0.471405, 0.471405),
+                        (0.349206, 0.482498, 0.482498),
+                        (0.365079, 0.493342, 0.493342),
+                        (0.380952, 0.503953, 0.503953),
+                        (0.396825, 0.514344, 0.514344),
+                        (0.412698, 0.524531, 0.524531),
+                        (0.428571, 0.534522, 0.534522),
+                        (0.444444, 0.544331, 0.544331),
+                        (0.460317, 0.553966, 0.553966),
+                        (0.476190, 0.563436, 0.563436),
+                        (0.492063, 0.572750, 0.572750),
+                        (0.507937, 0.581914, 0.581914),
+                        (0.523810, 0.590937, 0.590937),
+                        (0.539683, 0.599824, 0.599824),
+                        (0.555556, 0.608581, 0.608581),
+                        (0.571429, 0.617213, 0.617213),
+                        (0.587302, 0.625727, 0.625727),
+                        (0.603175, 0.634126, 0.634126),
+                        (0.619048, 0.642416, 0.642416),
+                        (0.634921, 0.650600, 0.650600),
+                        (0.650794, 0.658682, 0.658682),
+                        (0.666667, 0.666667, 0.666667),
+                        (0.682540, 0.674556, 0.674556),
+                        (0.698413, 0.682355, 0.682355),
+                        (0.714286, 0.690066, 0.690066),
+                        (0.730159, 0.697691, 0.697691),
+                        (0.746032, 0.705234, 0.705234),
+                        (0.761905, 0.727166, 0.727166),
+                        (0.777778, 0.748455, 0.748455),
+                        (0.793651, 0.769156, 0.769156),
+                        (0.809524, 0.789314, 0.789314),
+                        (0.825397, 0.808969, 0.808969),
+                        (0.841270, 0.828159, 0.828159),
+                        (0.857143, 0.846913, 0.846913),
+                        (0.873016, 0.865261, 0.865261),
+                        (0.888889, 0.883229, 0.883229),
+                        (0.904762, 0.900837, 0.900837),
+                        (0.920635, 0.918109, 0.918109),
+                        (0.936508, 0.935061, 0.935061),
+                        (0.952381, 0.951711, 0.951711),
+                        (0.968254, 0.968075, 0.968075),
+                        (0.984127, 0.984167, 0.984167), (1.0, 1.0, 1.0))}
+
+_spring_data = {'red':   ((0., 1., 1.), (1.0, 1.0, 1.0)),
+                'green': ((0., 0., 0.), (1.0, 1.0, 1.0)),
+                'blue':  ((0., 1., 1.), (1.0, 0.0, 0.0))}
+
+
+_summer_data = {'red':   ((0., 0., 0.), (1.0, 1.0, 1.0)),
+                'green': ((0., 0.5, 0.5), (1.0, 1.0, 1.0)),
+                'blue':  ((0., 0.4, 0.4), (1.0, 0.4, 0.4))}
+
+
+_winter_data = {'red':   ((0., 0., 0.), (1.0, 0.0, 0.0)),
+                'green': ((0., 0., 0.), (1.0, 1.0, 1.0)),
+                'blue':  ((0., 1., 1.), (1.0, 0.5, 0.5))}
+
+_nipy_spectral_data = {
+    'red': [
+        (0.0, 0.0, 0.0), (0.05, 0.4667, 0.4667),
+        (0.10, 0.5333, 0.5333), (0.15, 0.0, 0.0),
+        (0.20, 0.0, 0.0), (0.25, 0.0, 0.0),
+        (0.30, 0.0, 0.0), (0.35, 0.0, 0.0),
+        (0.40, 0.0, 0.0), (0.45, 0.0, 0.0),
+        (0.50, 0.0, 0.0), (0.55, 0.0, 0.0),
+        (0.60, 0.0, 0.0), (0.65, 0.7333, 0.7333),
+        (0.70, 0.9333, 0.9333), (0.75, 1.0, 1.0),
+        (0.80, 1.0, 1.0), (0.85, 1.0, 1.0),
+        (0.90, 0.8667, 0.8667), (0.95, 0.80, 0.80),
+        (1.0, 0.80, 0.80),
+    ],
+    'green': [
+        (0.0, 0.0, 0.0), (0.05, 0.0, 0.0),
+        (0.10, 0.0, 0.0), (0.15, 0.0, 0.0),
+        (0.20, 0.0, 0.0), (0.25, 0.4667, 0.4667),
+        (0.30, 0.6000, 0.6000), (0.35, 0.6667, 0.6667),
+        (0.40, 0.6667, 0.6667), (0.45, 0.6000, 0.6000),
+        (0.50, 0.7333, 0.7333), (0.55, 0.8667, 0.8667),
+        (0.60, 1.0, 1.0), (0.65, 1.0, 1.0),
+        (0.70, 0.9333, 0.9333), (0.75, 0.8000, 0.8000),
+        (0.80, 0.6000, 0.6000), (0.85, 0.0, 0.0),
+        (0.90, 0.0, 0.0), (0.95, 0.0, 0.0),
+        (1.0, 0.80, 0.80),
+    ],
+    'blue': [
+        (0.0, 0.0, 0.0), (0.05, 0.5333, 0.5333),
+        (0.10, 0.6000, 0.6000), (0.15, 0.6667, 0.6667),
+        (0.20, 0.8667, 0.8667), (0.25, 0.8667, 0.8667),
+        (0.30, 0.8667, 0.8667), (0.35, 0.6667, 0.6667),
+        (0.40, 0.5333, 0.5333), (0.45, 0.0, 0.0),
+        (0.5, 0.0, 0.0), (0.55, 0.0, 0.0),
+        (0.60, 0.0, 0.0), (0.65, 0.0, 0.0),
+        (0.70, 0.0, 0.0), (0.75, 0.0, 0.0),
+        (0.80, 0.0, 0.0), (0.85, 0.0, 0.0),
+        (0.90, 0.0, 0.0), (0.95, 0.0, 0.0),
+        (1.0, 0.80, 0.80),
+    ],
+}
+
+
+# 34 colormaps based on color specifications and designs
+# developed by Cynthia Brewer (https://colorbrewer2.org/).
+# The ColorBrewer palettes have been included under the terms
+# of an Apache-stype license (for details, see the file
+# LICENSE_COLORBREWER in the license directory of the matplotlib
+# source distribution).
+
+# RGB values taken from Brewer's Excel sheet, divided by 255
+
+_Blues_data = (
+    (0.96862745098039216,  0.98431372549019602,  1.0                ),
+    (0.87058823529411766,  0.92156862745098034,  0.96862745098039216),
+    (0.77647058823529413,  0.85882352941176465,  0.93725490196078431),
+    (0.61960784313725492,  0.792156862745098  ,  0.88235294117647056),
+    (0.41960784313725491,  0.68235294117647061,  0.83921568627450982),
+    (0.25882352941176473,  0.5725490196078431 ,  0.77647058823529413),
+    (0.12941176470588237,  0.44313725490196076,  0.70980392156862748),
+    (0.03137254901960784,  0.31764705882352939,  0.61176470588235299),
+    (0.03137254901960784,  0.18823529411764706,  0.41960784313725491)
+    )
+
+_BrBG_data = (
+    (0.32941176470588235,  0.18823529411764706,  0.0196078431372549 ),
+    (0.5490196078431373 ,  0.31764705882352939,  0.0392156862745098 ),
+    (0.74901960784313726,  0.50588235294117645,  0.17647058823529413),
+    (0.87450980392156863,  0.76078431372549016,  0.49019607843137253),
+    (0.96470588235294119,  0.90980392156862744,  0.76470588235294112),
+    (0.96078431372549022,  0.96078431372549022,  0.96078431372549022),
+    (0.7803921568627451 ,  0.91764705882352937,  0.89803921568627454),
+    (0.50196078431372548,  0.80392156862745101,  0.75686274509803919),
+    (0.20784313725490197,  0.59215686274509804,  0.5607843137254902 ),
+    (0.00392156862745098,  0.4                ,  0.36862745098039218),
+    (0.0                ,  0.23529411764705882,  0.18823529411764706)
+    )
+
+_BuGn_data = (
+    (0.96862745098039216,  0.9882352941176471 ,  0.99215686274509807),
+    (0.89803921568627454,  0.96078431372549022,  0.97647058823529409),
+    (0.8                ,  0.92549019607843142,  0.90196078431372551),
+    (0.6                ,  0.84705882352941175,  0.78823529411764703),
+    (0.4                ,  0.76078431372549016,  0.64313725490196083),
+    (0.25490196078431371,  0.68235294117647061,  0.46274509803921571),
+    (0.13725490196078433,  0.54509803921568623,  0.27058823529411763),
+    (0.0                ,  0.42745098039215684,  0.17254901960784313),
+    (0.0                ,  0.26666666666666666,  0.10588235294117647)
+    )
+
+_BuPu_data = (
+    (0.96862745098039216,  0.9882352941176471 ,  0.99215686274509807),
+    (0.8784313725490196 ,  0.92549019607843142,  0.95686274509803926),
+    (0.74901960784313726,  0.82745098039215681,  0.90196078431372551),
+    (0.61960784313725492,  0.73725490196078436,  0.85490196078431369),
+    (0.5490196078431373 ,  0.58823529411764708,  0.77647058823529413),
+    (0.5490196078431373 ,  0.41960784313725491,  0.69411764705882351),
+    (0.53333333333333333,  0.25490196078431371,  0.61568627450980395),
+    (0.50588235294117645,  0.05882352941176471,  0.48627450980392156),
+    (0.30196078431372547,  0.0                ,  0.29411764705882354)
+    )
+
+_GnBu_data = (
+    (0.96862745098039216,  0.9882352941176471 ,  0.94117647058823528),
+    (0.8784313725490196 ,  0.95294117647058818,  0.85882352941176465),
+    (0.8                ,  0.92156862745098034,  0.77254901960784317),
+    (0.6588235294117647 ,  0.8666666666666667 ,  0.70980392156862748),
+    (0.4823529411764706 ,  0.8                ,  0.7686274509803922 ),
+    (0.30588235294117649,  0.70196078431372544,  0.82745098039215681),
+    (0.16862745098039217,  0.5490196078431373 ,  0.74509803921568629),
+    (0.03137254901960784,  0.40784313725490196,  0.67450980392156867),
+    (0.03137254901960784,  0.25098039215686274,  0.50588235294117645)
+    )
+
+_Greens_data = (
+    (0.96862745098039216,  0.9882352941176471 ,  0.96078431372549022),
+    (0.89803921568627454,  0.96078431372549022,  0.8784313725490196 ),
+    (0.7803921568627451 ,  0.9137254901960784 ,  0.75294117647058822),
+    (0.63137254901960782,  0.85098039215686272,  0.60784313725490191),
+    (0.45490196078431372,  0.7686274509803922 ,  0.46274509803921571),
+    (0.25490196078431371,  0.6705882352941176 ,  0.36470588235294116),
+    (0.13725490196078433,  0.54509803921568623,  0.27058823529411763),
+    (0.0                ,  0.42745098039215684,  0.17254901960784313),
+    (0.0                ,  0.26666666666666666,  0.10588235294117647)
+    )
+
+_Greys_data = (
+    (1.0                ,  1.0                ,  1.0                ),
+    (0.94117647058823528,  0.94117647058823528,  0.94117647058823528),
+    (0.85098039215686272,  0.85098039215686272,  0.85098039215686272),
+    (0.74117647058823533,  0.74117647058823533,  0.74117647058823533),
+    (0.58823529411764708,  0.58823529411764708,  0.58823529411764708),
+    (0.45098039215686275,  0.45098039215686275,  0.45098039215686275),
+    (0.32156862745098042,  0.32156862745098042,  0.32156862745098042),
+    (0.14509803921568629,  0.14509803921568629,  0.14509803921568629),
+    (0.0                ,  0.0                ,  0.0                )
+    )
+
+_Oranges_data = (
+    (1.0                ,  0.96078431372549022,  0.92156862745098034),
+    (0.99607843137254903,  0.90196078431372551,  0.80784313725490198),
+    (0.99215686274509807,  0.81568627450980391,  0.63529411764705879),
+    (0.99215686274509807,  0.68235294117647061,  0.41960784313725491),
+    (0.99215686274509807,  0.55294117647058827,  0.23529411764705882),
+    (0.94509803921568625,  0.41176470588235292,  0.07450980392156863),
+    (0.85098039215686272,  0.28235294117647058,  0.00392156862745098),
+    (0.65098039215686276,  0.21176470588235294,  0.01176470588235294),
+    (0.49803921568627452,  0.15294117647058825,  0.01568627450980392)
+    )
+
+_OrRd_data = (
+    (1.0                ,  0.96862745098039216,  0.92549019607843142),
+    (0.99607843137254903,  0.90980392156862744,  0.78431372549019607),
+    (0.99215686274509807,  0.83137254901960789,  0.61960784313725492),
+    (0.99215686274509807,  0.73333333333333328,  0.51764705882352946),
+    (0.9882352941176471 ,  0.55294117647058827,  0.34901960784313724),
+    (0.93725490196078431,  0.396078431372549  ,  0.28235294117647058),
+    (0.84313725490196079,  0.18823529411764706,  0.12156862745098039),
+    (0.70196078431372544,  0.0                ,  0.0                ),
+    (0.49803921568627452,  0.0                ,  0.0                )
+    )
+
+_PiYG_data = (
+    (0.55686274509803924,  0.00392156862745098,  0.32156862745098042),
+    (0.77254901960784317,  0.10588235294117647,  0.49019607843137253),
+    (0.87058823529411766,  0.46666666666666667,  0.68235294117647061),
+    (0.94509803921568625,  0.71372549019607845,  0.85490196078431369),
+    (0.99215686274509807,  0.8784313725490196 ,  0.93725490196078431),
+    (0.96862745098039216,  0.96862745098039216,  0.96862745098039216),
+    (0.90196078431372551,  0.96078431372549022,  0.81568627450980391),
+    (0.72156862745098038,  0.88235294117647056,  0.52549019607843139),
+    (0.49803921568627452,  0.73725490196078436,  0.25490196078431371),
+    (0.30196078431372547,  0.5725490196078431 ,  0.12941176470588237),
+    (0.15294117647058825,  0.39215686274509803,  0.09803921568627451)
+    )
+
+_PRGn_data = (
+    (0.25098039215686274,  0.0                ,  0.29411764705882354),
+    (0.46274509803921571,  0.16470588235294117,  0.51372549019607838),
+    (0.6                ,  0.4392156862745098 ,  0.6705882352941176 ),
+    (0.76078431372549016,  0.6470588235294118 ,  0.81176470588235294),
+    (0.90588235294117647,  0.83137254901960789,  0.90980392156862744),
+    (0.96862745098039216,  0.96862745098039216,  0.96862745098039216),
+    (0.85098039215686272,  0.94117647058823528,  0.82745098039215681),
+    (0.65098039215686276,  0.85882352941176465,  0.62745098039215685),
+    (0.35294117647058826,  0.68235294117647061,  0.38039215686274508),
+    (0.10588235294117647,  0.47058823529411764,  0.21568627450980393),
+    (0.0                ,  0.26666666666666666,  0.10588235294117647)
+    )
+
+_PuBu_data = (
+    (1.0                ,  0.96862745098039216,  0.98431372549019602),
+    (0.92549019607843142,  0.90588235294117647,  0.94901960784313721),
+    (0.81568627450980391,  0.81960784313725488,  0.90196078431372551),
+    (0.65098039215686276,  0.74117647058823533,  0.85882352941176465),
+    (0.45490196078431372,  0.66274509803921566,  0.81176470588235294),
+    (0.21176470588235294,  0.56470588235294117,  0.75294117647058822),
+    (0.0196078431372549 ,  0.4392156862745098 ,  0.69019607843137254),
+    (0.01568627450980392,  0.35294117647058826,  0.55294117647058827),
+    (0.00784313725490196,  0.2196078431372549 ,  0.34509803921568627)
+    )
+
+_PuBuGn_data = (
+    (1.0                ,  0.96862745098039216,  0.98431372549019602),
+    (0.92549019607843142,  0.88627450980392153,  0.94117647058823528),
+    (0.81568627450980391,  0.81960784313725488,  0.90196078431372551),
+    (0.65098039215686276,  0.74117647058823533,  0.85882352941176465),
+    (0.40392156862745099,  0.66274509803921566,  0.81176470588235294),
+    (0.21176470588235294,  0.56470588235294117,  0.75294117647058822),
+    (0.00784313725490196,  0.50588235294117645,  0.54117647058823526),
+    (0.00392156862745098,  0.42352941176470588,  0.34901960784313724),
+    (0.00392156862745098,  0.27450980392156865,  0.21176470588235294)
+    )
+
+_PuOr_data = (
+    (0.49803921568627452,  0.23137254901960785,  0.03137254901960784),
+    (0.70196078431372544,  0.34509803921568627,  0.02352941176470588),
+    (0.8784313725490196 ,  0.50980392156862742,  0.07843137254901961),
+    (0.99215686274509807,  0.72156862745098038,  0.38823529411764707),
+    (0.99607843137254903,  0.8784313725490196 ,  0.71372549019607845),
+    (0.96862745098039216,  0.96862745098039216,  0.96862745098039216),
+    (0.84705882352941175,  0.85490196078431369,  0.92156862745098034),
+    (0.69803921568627447,  0.6705882352941176 ,  0.82352941176470584),
+    (0.50196078431372548,  0.45098039215686275,  0.67450980392156867),
+    (0.32941176470588235,  0.15294117647058825,  0.53333333333333333),
+    (0.17647058823529413,  0.0                ,  0.29411764705882354)
+    )
+
+_PuRd_data = (
+    (0.96862745098039216,  0.95686274509803926,  0.97647058823529409),
+    (0.90588235294117647,  0.88235294117647056,  0.93725490196078431),
+    (0.83137254901960789,  0.72549019607843135,  0.85490196078431369),
+    (0.78823529411764703,  0.58039215686274515,  0.7803921568627451 ),
+    (0.87450980392156863,  0.396078431372549  ,  0.69019607843137254),
+    (0.90588235294117647,  0.16078431372549021,  0.54117647058823526),
+    (0.80784313725490198,  0.07058823529411765,  0.33725490196078434),
+    (0.59607843137254901,  0.0                ,  0.2627450980392157 ),
+    (0.40392156862745099,  0.0                ,  0.12156862745098039)
+    )
+
+_Purples_data = (
+    (0.9882352941176471 ,  0.98431372549019602,  0.99215686274509807),
+    (0.93725490196078431,  0.92941176470588238,  0.96078431372549022),
+    (0.85490196078431369,  0.85490196078431369,  0.92156862745098034),
+    (0.73725490196078436,  0.74117647058823533,  0.86274509803921573),
+    (0.61960784313725492,  0.60392156862745094,  0.78431372549019607),
+    (0.50196078431372548,  0.49019607843137253,  0.72941176470588232),
+    (0.41568627450980394,  0.31764705882352939,  0.63921568627450975),
+    (0.32941176470588235,  0.15294117647058825,  0.5607843137254902 ),
+    (0.24705882352941178,  0.0                ,  0.49019607843137253)
+    )
+
+_RdBu_data = (
+    (0.40392156862745099,  0.0                ,  0.12156862745098039),
+    (0.69803921568627447,  0.09411764705882353,  0.16862745098039217),
+    (0.83921568627450982,  0.37647058823529411,  0.30196078431372547),
+    (0.95686274509803926,  0.6470588235294118 ,  0.50980392156862742),
+    (0.99215686274509807,  0.85882352941176465,  0.7803921568627451 ),
+    (0.96862745098039216,  0.96862745098039216,  0.96862745098039216),
+    (0.81960784313725488,  0.89803921568627454,  0.94117647058823528),
+    (0.5725490196078431 ,  0.77254901960784317,  0.87058823529411766),
+    (0.2627450980392157 ,  0.57647058823529407,  0.76470588235294112),
+    (0.12941176470588237,  0.4                ,  0.67450980392156867),
+    (0.0196078431372549 ,  0.18823529411764706,  0.38039215686274508)
+    )
+
+_RdGy_data = (
+    (0.40392156862745099,  0.0                ,  0.12156862745098039),
+    (0.69803921568627447,  0.09411764705882353,  0.16862745098039217),
+    (0.83921568627450982,  0.37647058823529411,  0.30196078431372547),
+    (0.95686274509803926,  0.6470588235294118 ,  0.50980392156862742),
+    (0.99215686274509807,  0.85882352941176465,  0.7803921568627451 ),
+    (1.0                ,  1.0                ,  1.0                ),
+    (0.8784313725490196 ,  0.8784313725490196 ,  0.8784313725490196 ),
+    (0.72941176470588232,  0.72941176470588232,  0.72941176470588232),
+    (0.52941176470588236,  0.52941176470588236,  0.52941176470588236),
+    (0.30196078431372547,  0.30196078431372547,  0.30196078431372547),
+    (0.10196078431372549,  0.10196078431372549,  0.10196078431372549)
+    )
+
+_RdPu_data = (
+    (1.0                ,  0.96862745098039216,  0.95294117647058818),
+    (0.99215686274509807,  0.8784313725490196 ,  0.86666666666666667),
+    (0.9882352941176471 ,  0.77254901960784317,  0.75294117647058822),
+    (0.98039215686274506,  0.62352941176470589,  0.70980392156862748),
+    (0.96862745098039216,  0.40784313725490196,  0.63137254901960782),
+    (0.86666666666666667,  0.20392156862745098,  0.59215686274509804),
+    (0.68235294117647061,  0.00392156862745098,  0.49411764705882355),
+    (0.47843137254901963,  0.00392156862745098,  0.46666666666666667),
+    (0.28627450980392155,  0.0                ,  0.41568627450980394)
+    )
+
+_RdYlBu_data = (
+    (0.6470588235294118 , 0.0                 , 0.14901960784313725),
+    (0.84313725490196079, 0.18823529411764706 , 0.15294117647058825),
+    (0.95686274509803926, 0.42745098039215684 , 0.2627450980392157 ),
+    (0.99215686274509807, 0.68235294117647061 , 0.38039215686274508),
+    (0.99607843137254903, 0.8784313725490196  , 0.56470588235294117),
+    (1.0                , 1.0                 , 0.74901960784313726),
+    (0.8784313725490196 , 0.95294117647058818 , 0.97254901960784312),
+    (0.6705882352941176 , 0.85098039215686272 , 0.9137254901960784 ),
+    (0.45490196078431372, 0.67843137254901964 , 0.81960784313725488),
+    (0.27058823529411763, 0.45882352941176469 , 0.70588235294117652),
+    (0.19215686274509805, 0.21176470588235294 , 0.58431372549019611)
+    )
+
+_RdYlGn_data = (
+    (0.6470588235294118 , 0.0                 , 0.14901960784313725),
+    (0.84313725490196079, 0.18823529411764706 , 0.15294117647058825),
+    (0.95686274509803926, 0.42745098039215684 , 0.2627450980392157 ),
+    (0.99215686274509807, 0.68235294117647061 , 0.38039215686274508),
+    (0.99607843137254903, 0.8784313725490196  , 0.54509803921568623),
+    (1.0                , 1.0                 , 0.74901960784313726),
+    (0.85098039215686272, 0.93725490196078431 , 0.54509803921568623),
+    (0.65098039215686276, 0.85098039215686272 , 0.41568627450980394),
+    (0.4                , 0.74117647058823533 , 0.38823529411764707),
+    (0.10196078431372549, 0.59607843137254901 , 0.31372549019607843),
+    (0.0                , 0.40784313725490196 , 0.21568627450980393)
+    )
+
+_Reds_data = (
+    (1.0                , 0.96078431372549022 , 0.94117647058823528),
+    (0.99607843137254903, 0.8784313725490196  , 0.82352941176470584),
+    (0.9882352941176471 , 0.73333333333333328 , 0.63137254901960782),
+    (0.9882352941176471 , 0.5725490196078431  , 0.44705882352941179),
+    (0.98431372549019602, 0.41568627450980394 , 0.29019607843137257),
+    (0.93725490196078431, 0.23137254901960785 , 0.17254901960784313),
+    (0.79607843137254897, 0.094117647058823528, 0.11372549019607843),
+    (0.6470588235294118 , 0.058823529411764705, 0.08235294117647058),
+    (0.40392156862745099, 0.0                 , 0.05098039215686274)
+    )
+
+_Spectral_data = (
+    (0.61960784313725492, 0.003921568627450980, 0.25882352941176473),
+    (0.83529411764705885, 0.24313725490196078 , 0.30980392156862746),
+    (0.95686274509803926, 0.42745098039215684 , 0.2627450980392157 ),
+    (0.99215686274509807, 0.68235294117647061 , 0.38039215686274508),
+    (0.99607843137254903, 0.8784313725490196  , 0.54509803921568623),
+    (1.0                , 1.0                 , 0.74901960784313726),
+    (0.90196078431372551, 0.96078431372549022 , 0.59607843137254901),
+    (0.6705882352941176 , 0.8666666666666667  , 0.64313725490196083),
+    (0.4                , 0.76078431372549016 , 0.6470588235294118 ),
+    (0.19607843137254902, 0.53333333333333333 , 0.74117647058823533),
+    (0.36862745098039218, 0.30980392156862746 , 0.63529411764705879)
+    )
+
+_YlGn_data = (
+    (1.0                , 1.0                 , 0.89803921568627454),
+    (0.96862745098039216, 0.9882352941176471  , 0.72549019607843135),
+    (0.85098039215686272, 0.94117647058823528 , 0.63921568627450975),
+    (0.67843137254901964, 0.8666666666666667  , 0.55686274509803924),
+    (0.47058823529411764, 0.77647058823529413 , 0.47450980392156861),
+    (0.25490196078431371, 0.6705882352941176  , 0.36470588235294116),
+    (0.13725490196078433, 0.51764705882352946 , 0.2627450980392157 ),
+    (0.0                , 0.40784313725490196 , 0.21568627450980393),
+    (0.0                , 0.27058823529411763 , 0.16078431372549021)
+    )
+
+_YlGnBu_data = (
+    (1.0                , 1.0                 , 0.85098039215686272),
+    (0.92941176470588238, 0.97254901960784312 , 0.69411764705882351),
+    (0.7803921568627451 , 0.9137254901960784  , 0.70588235294117652),
+    (0.49803921568627452, 0.80392156862745101 , 0.73333333333333328),
+    (0.25490196078431371, 0.71372549019607845 , 0.7686274509803922 ),
+    (0.11372549019607843, 0.56862745098039214 , 0.75294117647058822),
+    (0.13333333333333333, 0.36862745098039218 , 0.6588235294117647 ),
+    (0.14509803921568629, 0.20392156862745098 , 0.58039215686274515),
+    (0.03137254901960784, 0.11372549019607843 , 0.34509803921568627)
+    )
+
+_YlOrBr_data = (
+    (1.0                , 1.0                 , 0.89803921568627454),
+    (1.0                , 0.96862745098039216 , 0.73725490196078436),
+    (0.99607843137254903, 0.8901960784313725  , 0.56862745098039214),
+    (0.99607843137254903, 0.7686274509803922  , 0.30980392156862746),
+    (0.99607843137254903, 0.6                 , 0.16078431372549021),
+    (0.92549019607843142, 0.4392156862745098  , 0.07843137254901961),
+    (0.8                , 0.29803921568627451 , 0.00784313725490196),
+    (0.6                , 0.20392156862745098 , 0.01568627450980392),
+    (0.4                , 0.14509803921568629 , 0.02352941176470588)
+    )
+
+_YlOrRd_data = (
+    (1.0                , 1.0                 , 0.8                ),
+    (1.0                , 0.92941176470588238 , 0.62745098039215685),
+    (0.99607843137254903, 0.85098039215686272 , 0.46274509803921571),
+    (0.99607843137254903, 0.69803921568627447 , 0.29803921568627451),
+    (0.99215686274509807, 0.55294117647058827 , 0.23529411764705882),
+    (0.9882352941176471 , 0.30588235294117649 , 0.16470588235294117),
+    (0.8901960784313725 , 0.10196078431372549 , 0.10980392156862745),
+    (0.74117647058823533, 0.0                 , 0.14901960784313725),
+    (0.50196078431372548, 0.0                 , 0.14901960784313725)
+    )
+
+
+# ColorBrewer's qualitative maps, implemented using ListedColormap
+# for use with mpl.colors.NoNorm
+
+_Accent_data = (
+    (0.49803921568627452, 0.78823529411764703, 0.49803921568627452),
+    (0.74509803921568629, 0.68235294117647061, 0.83137254901960789),
+    (0.99215686274509807, 0.75294117647058822, 0.52549019607843139),
+    (1.0,                 1.0,                 0.6                ),
+    (0.2196078431372549,  0.42352941176470588, 0.69019607843137254),
+    (0.94117647058823528, 0.00784313725490196, 0.49803921568627452),
+    (0.74901960784313726, 0.35686274509803922, 0.09019607843137254),
+    (0.4,                 0.4,                 0.4                ),
+    )
+
+_Dark2_data = (
+    (0.10588235294117647, 0.61960784313725492, 0.46666666666666667),
+    (0.85098039215686272, 0.37254901960784315, 0.00784313725490196),
+    (0.45882352941176469, 0.4392156862745098,  0.70196078431372544),
+    (0.90588235294117647, 0.16078431372549021, 0.54117647058823526),
+    (0.4,                 0.65098039215686276, 0.11764705882352941),
+    (0.90196078431372551, 0.6705882352941176,  0.00784313725490196),
+    (0.65098039215686276, 0.46274509803921571, 0.11372549019607843),
+    (0.4,                 0.4,                 0.4                ),
+    )
+
+_Paired_data = (
+    (0.65098039215686276, 0.80784313725490198, 0.8901960784313725 ),
+    (0.12156862745098039, 0.47058823529411764, 0.70588235294117652),
+    (0.69803921568627447, 0.87450980392156863, 0.54117647058823526),
+    (0.2,                 0.62745098039215685, 0.17254901960784313),
+    (0.98431372549019602, 0.60392156862745094, 0.6                ),
+    (0.8901960784313725,  0.10196078431372549, 0.10980392156862745),
+    (0.99215686274509807, 0.74901960784313726, 0.43529411764705883),
+    (1.0,                 0.49803921568627452, 0.0                ),
+    (0.792156862745098,   0.69803921568627447, 0.83921568627450982),
+    (0.41568627450980394, 0.23921568627450981, 0.60392156862745094),
+    (1.0,                 1.0,                 0.6                ),
+    (0.69411764705882351, 0.34901960784313724, 0.15686274509803921),
+    )
+
+_Pastel1_data = (
+    (0.98431372549019602, 0.70588235294117652, 0.68235294117647061),
+    (0.70196078431372544, 0.80392156862745101, 0.8901960784313725 ),
+    (0.8,                 0.92156862745098034, 0.77254901960784317),
+    (0.87058823529411766, 0.79607843137254897, 0.89411764705882357),
+    (0.99607843137254903, 0.85098039215686272, 0.65098039215686276),
+    (1.0,                 1.0,                 0.8                ),
+    (0.89803921568627454, 0.84705882352941175, 0.74117647058823533),
+    (0.99215686274509807, 0.85490196078431369, 0.92549019607843142),
+    (0.94901960784313721, 0.94901960784313721, 0.94901960784313721),
+    )
+
+_Pastel2_data = (
+    (0.70196078431372544, 0.88627450980392153, 0.80392156862745101),
+    (0.99215686274509807, 0.80392156862745101, 0.67450980392156867),
+    (0.79607843137254897, 0.83529411764705885, 0.90980392156862744),
+    (0.95686274509803926, 0.792156862745098,   0.89411764705882357),
+    (0.90196078431372551, 0.96078431372549022, 0.78823529411764703),
+    (1.0,                 0.94901960784313721, 0.68235294117647061),
+    (0.94509803921568625, 0.88627450980392153, 0.8                ),
+    (0.8,                 0.8,                 0.8                ),
+    )
+
+_Set1_data = (
+    (0.89411764705882357, 0.10196078431372549, 0.10980392156862745),
+    (0.21568627450980393, 0.49411764705882355, 0.72156862745098038),
+    (0.30196078431372547, 0.68627450980392157, 0.29019607843137257),
+    (0.59607843137254901, 0.30588235294117649, 0.63921568627450975),
+    (1.0,                 0.49803921568627452, 0.0                ),
+    (1.0,                 1.0,                 0.2                ),
+    (0.65098039215686276, 0.33725490196078434, 0.15686274509803921),
+    (0.96862745098039216, 0.50588235294117645, 0.74901960784313726),
+    (0.6,                 0.6,                 0.6),
+    )
+
+_Set2_data = (
+    (0.4,                 0.76078431372549016, 0.6470588235294118 ),
+    (0.9882352941176471,  0.55294117647058827, 0.3843137254901961 ),
+    (0.55294117647058827, 0.62745098039215685, 0.79607843137254897),
+    (0.90588235294117647, 0.54117647058823526, 0.76470588235294112),
+    (0.65098039215686276, 0.84705882352941175, 0.32941176470588235),
+    (1.0,                 0.85098039215686272, 0.18431372549019609),
+    (0.89803921568627454, 0.7686274509803922,  0.58039215686274515),
+    (0.70196078431372544, 0.70196078431372544, 0.70196078431372544),
+    )
+
+_Set3_data = (
+    (0.55294117647058827, 0.82745098039215681, 0.7803921568627451 ),
+    (1.0,                 1.0,                 0.70196078431372544),
+    (0.74509803921568629, 0.72941176470588232, 0.85490196078431369),
+    (0.98431372549019602, 0.50196078431372548, 0.44705882352941179),
+    (0.50196078431372548, 0.69411764705882351, 0.82745098039215681),
+    (0.99215686274509807, 0.70588235294117652, 0.3843137254901961 ),
+    (0.70196078431372544, 0.87058823529411766, 0.41176470588235292),
+    (0.9882352941176471,  0.80392156862745101, 0.89803921568627454),
+    (0.85098039215686272, 0.85098039215686272, 0.85098039215686272),
+    (0.73725490196078436, 0.50196078431372548, 0.74117647058823533),
+    (0.8,                 0.92156862745098034, 0.77254901960784317),
+    (1.0,                 0.92941176470588238, 0.43529411764705883),
+    )
+
+
+# The next 7 palettes are from the Yorick scientific visualization package,
+# an evolution of the GIST package, both by David H. Munro.
+# They are released under a BSD-like license (see LICENSE_YORICK in
+# the license directory of the matplotlib source distribution).
+#
+# Most palette functions have been reduced to simple function descriptions
+# by Reinier Heeres, since the rgb components were mostly straight lines.
+# gist_earth_data and gist_ncar_data were simplified by a script and some
+# manual effort.
+
+_gist_earth_data = {
+    'red': (
+        (0.0, 0.0, 0.0000),
+        (0.2824, 0.1882, 0.1882),
+        (0.4588, 0.2714, 0.2714),
+        (0.5490, 0.4719, 0.4719),
+        (0.6980, 0.7176, 0.7176),
+        (0.7882, 0.7553, 0.7553),
+        (1.0000, 0.9922, 0.9922),
+    ),
+    'green': (
+        (0.0, 0.0, 0.0000),
+        (0.0275, 0.0000, 0.0000),
+        (0.1098, 0.1893, 0.1893),
+        (0.1647, 0.3035, 0.3035),
+        (0.2078, 0.3841, 0.3841),
+        (0.2824, 0.5020, 0.5020),
+        (0.5216, 0.6397, 0.6397),
+        (0.6980, 0.7171, 0.7171),
+        (0.7882, 0.6392, 0.6392),
+        (0.7922, 0.6413, 0.6413),
+        (0.8000, 0.6447, 0.6447),
+        (0.8078, 0.6481, 0.6481),
+        (0.8157, 0.6549, 0.6549),
+        (0.8667, 0.6991, 0.6991),
+        (0.8745, 0.7103, 0.7103),
+        (0.8824, 0.7216, 0.7216),
+        (0.8902, 0.7323, 0.7323),
+        (0.8980, 0.7430, 0.7430),
+        (0.9412, 0.8275, 0.8275),
+        (0.9569, 0.8635, 0.8635),
+        (0.9647, 0.8816, 0.8816),
+        (0.9961, 0.9733, 0.9733),
+        (1.0000, 0.9843, 0.9843),
+    ),
+    'blue': (
+        (0.0, 0.0, 0.0000),
+        (0.0039, 0.1684, 0.1684),
+        (0.0078, 0.2212, 0.2212),
+        (0.0275, 0.4329, 0.4329),
+        (0.0314, 0.4549, 0.4549),
+        (0.2824, 0.5004, 0.5004),
+        (0.4667, 0.2748, 0.2748),
+        (0.5451, 0.3205, 0.3205),
+        (0.7843, 0.3961, 0.3961),
+        (0.8941, 0.6651, 0.6651),
+        (1.0000, 0.9843, 0.9843),
+    )
+}
+
+_gist_gray_data = {
+        'red': gfunc[3],
+        'green': gfunc[3],
+        'blue': gfunc[3],
+}
+
+def _gist_heat_red(x): return 1.5 * x
+def _gist_heat_green(x): return 2 * x - 1
+def _gist_heat_blue(x): return 4 * x - 3
+_gist_heat_data = {
+    'red': _gist_heat_red, 'green': _gist_heat_green, 'blue': _gist_heat_blue}
+
+_gist_ncar_data = {
+    'red': (
+        (0.0, 0.0, 0.0000),
+        (0.3098, 0.0000, 0.0000),
+        (0.3725, 0.3993, 0.3993),
+        (0.4235, 0.5003, 0.5003),
+        (0.5333, 1.0000, 1.0000),
+        (0.7922, 1.0000, 1.0000),
+        (0.8471, 0.6218, 0.6218),
+        (0.8980, 0.9235, 0.9235),
+        (1.0000, 0.9961, 0.9961),
+    ),
+    'green': (
+        (0.0, 0.0, 0.0000),
+        (0.0510, 0.3722, 0.3722),
+        (0.1059, 0.0000, 0.0000),
+        (0.1569, 0.7202, 0.7202),
+        (0.1608, 0.7537, 0.7537),
+        (0.1647, 0.7752, 0.7752),
+        (0.2157, 1.0000, 1.0000),
+        (0.2588, 0.9804, 0.9804),
+        (0.2706, 0.9804, 0.9804),
+        (0.3176, 1.0000, 1.0000),
+        (0.3686, 0.8081, 0.8081),
+        (0.4275, 1.0000, 1.0000),
+        (0.5216, 1.0000, 1.0000),
+        (0.6314, 0.7292, 0.7292),
+        (0.6863, 0.2796, 0.2796),
+        (0.7451, 0.0000, 0.0000),
+        (0.7922, 0.0000, 0.0000),
+        (0.8431, 0.1753, 0.1753),
+        (0.8980, 0.5000, 0.5000),
+        (1.0000, 0.9725, 0.9725),
+    ),
+    'blue': (
+        (0.0, 0.5020, 0.5020),
+        (0.0510, 0.0222, 0.0222),
+        (0.1098, 1.0000, 1.0000),
+        (0.2039, 1.0000, 1.0000),
+        (0.2627, 0.6145, 0.6145),
+        (0.3216, 0.0000, 0.0000),
+        (0.4157, 0.0000, 0.0000),
+        (0.4745, 0.2342, 0.2342),
+        (0.5333, 0.0000, 0.0000),
+        (0.5804, 0.0000, 0.0000),
+        (0.6314, 0.0549, 0.0549),
+        (0.6902, 0.0000, 0.0000),
+        (0.7373, 0.0000, 0.0000),
+        (0.7922, 0.9738, 0.9738),
+        (0.8000, 1.0000, 1.0000),
+        (0.8431, 1.0000, 1.0000),
+        (0.8980, 0.9341, 0.9341),
+        (1.0000, 0.9961, 0.9961),
+    )
+}
+
+_gist_rainbow_data = (
+        (0.000, (1.00, 0.00, 0.16)),
+        (0.030, (1.00, 0.00, 0.00)),
+        (0.215, (1.00, 1.00, 0.00)),
+        (0.400, (0.00, 1.00, 0.00)),
+        (0.586, (0.00, 1.00, 1.00)),
+        (0.770, (0.00, 0.00, 1.00)),
+        (0.954, (1.00, 0.00, 1.00)),
+        (1.000, (1.00, 0.00, 0.75))
+)
+
+_gist_stern_data = {
+        'red': (
+            (0.000, 0.000, 0.000), (0.0547, 1.000, 1.000),
+            (0.250, 0.027, 0.250),  # (0.2500, 0.250, 0.250),
+            (1.000, 1.000, 1.000)),
+        'green': ((0, 0, 0), (1, 1, 1)),
+        'blue': (
+            (0.000, 0.000, 0.000), (0.500, 1.000, 1.000),
+            (0.735, 0.000, 0.000), (1.000, 1.000, 1.000))
+}
+
+def _gist_yarg(x): return 1 - x
+_gist_yarg_data = {'red': _gist_yarg, 'green': _gist_yarg, 'blue': _gist_yarg}
+
+# This bipolar colormap was generated from CoolWarmFloat33.csv of
+# "Diverging Color Maps for Scientific Visualization" by Kenneth Moreland.
+# <http://www.kennethmoreland.com/color-maps/>
+_coolwarm_data = {
+    'red': [
+        (0.0, 0.2298057, 0.2298057),
+        (0.03125, 0.26623388, 0.26623388),
+        (0.0625, 0.30386891, 0.30386891),
+        (0.09375, 0.342804478, 0.342804478),
+        (0.125, 0.38301334, 0.38301334),
+        (0.15625, 0.424369608, 0.424369608),
+        (0.1875, 0.46666708, 0.46666708),
+        (0.21875, 0.509635204, 0.509635204),
+        (0.25, 0.552953156, 0.552953156),
+        (0.28125, 0.596262162, 0.596262162),
+        (0.3125, 0.639176211, 0.639176211),
+        (0.34375, 0.681291281, 0.681291281),
+        (0.375, 0.722193294, 0.722193294),
+        (0.40625, 0.761464949, 0.761464949),
+        (0.4375, 0.798691636, 0.798691636),
+        (0.46875, 0.833466556, 0.833466556),
+        (0.5, 0.865395197, 0.865395197),
+        (0.53125, 0.897787179, 0.897787179),
+        (0.5625, 0.924127593, 0.924127593),
+        (0.59375, 0.944468518, 0.944468518),
+        (0.625, 0.958852946, 0.958852946),
+        (0.65625, 0.96732803, 0.96732803),
+        (0.6875, 0.969954137, 0.969954137),
+        (0.71875, 0.966811177, 0.966811177),
+        (0.75, 0.958003065, 0.958003065),
+        (0.78125, 0.943660866, 0.943660866),
+        (0.8125, 0.923944917, 0.923944917),
+        (0.84375, 0.89904617, 0.89904617),
+        (0.875, 0.869186849, 0.869186849),
+        (0.90625, 0.834620542, 0.834620542),
+        (0.9375, 0.795631745, 0.795631745),
+        (0.96875, 0.752534934, 0.752534934),
+        (1.0, 0.705673158, 0.705673158)],
+    'green': [
+        (0.0, 0.298717966, 0.298717966),
+        (0.03125, 0.353094838, 0.353094838),
+        (0.0625, 0.406535296, 0.406535296),
+        (0.09375, 0.458757618, 0.458757618),
+        (0.125, 0.50941904, 0.50941904),
+        (0.15625, 0.558148092, 0.558148092),
+        (0.1875, 0.604562568, 0.604562568),
+        (0.21875, 0.648280772, 0.648280772),
+        (0.25, 0.688929332, 0.688929332),
+        (0.28125, 0.726149107, 0.726149107),
+        (0.3125, 0.759599947, 0.759599947),
+        (0.34375, 0.788964712, 0.788964712),
+        (0.375, 0.813952739, 0.813952739),
+        (0.40625, 0.834302879, 0.834302879),
+        (0.4375, 0.849786142, 0.849786142),
+        (0.46875, 0.860207984, 0.860207984),
+        (0.5, 0.86541021, 0.86541021),
+        (0.53125, 0.848937047, 0.848937047),
+        (0.5625, 0.827384882, 0.827384882),
+        (0.59375, 0.800927443, 0.800927443),
+        (0.625, 0.769767752, 0.769767752),
+        (0.65625, 0.734132809, 0.734132809),
+        (0.6875, 0.694266682, 0.694266682),
+        (0.71875, 0.650421156, 0.650421156),
+        (0.75, 0.602842431, 0.602842431),
+        (0.78125, 0.551750968, 0.551750968),
+        (0.8125, 0.49730856, 0.49730856),
+        (0.84375, 0.439559467, 0.439559467),
+        (0.875, 0.378313092, 0.378313092),
+        (0.90625, 0.312874446, 0.312874446),
+        (0.9375, 0.24128379, 0.24128379),
+        (0.96875, 0.157246067, 0.157246067),
+        (1.0, 0.01555616, 0.01555616)],
+    'blue': [
+        (0.0, 0.753683153, 0.753683153),
+        (0.03125, 0.801466763, 0.801466763),
+        (0.0625, 0.84495867, 0.84495867),
+        (0.09375, 0.883725899, 0.883725899),
+        (0.125, 0.917387822, 0.917387822),
+        (0.15625, 0.945619588, 0.945619588),
+        (0.1875, 0.968154911, 0.968154911),
+        (0.21875, 0.98478814, 0.98478814),
+        (0.25, 0.995375608, 0.995375608),
+        (0.28125, 0.999836203, 0.999836203),
+        (0.3125, 0.998151185, 0.998151185),
+        (0.34375, 0.990363227, 0.990363227),
+        (0.375, 0.976574709, 0.976574709),
+        (0.40625, 0.956945269, 0.956945269),
+        (0.4375, 0.931688648, 0.931688648),
+        (0.46875, 0.901068838, 0.901068838),
+        (0.5, 0.865395561, 0.865395561),
+        (0.53125, 0.820880546, 0.820880546),
+        (0.5625, 0.774508472, 0.774508472),
+        (0.59375, 0.726736146, 0.726736146),
+        (0.625, 0.678007945, 0.678007945),
+        (0.65625, 0.628751763, 0.628751763),
+        (0.6875, 0.579375448, 0.579375448),
+        (0.71875, 0.530263762, 0.530263762),
+        (0.75, 0.481775914, 0.481775914),
+        (0.78125, 0.434243684, 0.434243684),
+        (0.8125, 0.387970225, 0.387970225),
+        (0.84375, 0.343229596, 0.343229596),
+        (0.875, 0.300267182, 0.300267182),
+        (0.90625, 0.259301199, 0.259301199),
+        (0.9375, 0.220525627, 0.220525627),
+        (0.96875, 0.184115123, 0.184115123),
+        (1.0, 0.150232812, 0.150232812)]
+    }
+
+# Implementation of Carey Rappaport's CMRmap.
+# See `A Color Map for Effective Black-and-White Rendering of Color-Scale
+# Images' by Carey Rappaport
+# https://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m
+_CMRmap_data = {'red':    ((0.000, 0.00, 0.00),
+                           (0.125, 0.15, 0.15),
+                           (0.250, 0.30, 0.30),
+                           (0.375, 0.60, 0.60),
+                           (0.500, 1.00, 1.00),
+                           (0.625, 0.90, 0.90),
+                           (0.750, 0.90, 0.90),
+                           (0.875, 0.90, 0.90),
+                           (1.000, 1.00, 1.00)),
+                'green':  ((0.000, 0.00, 0.00),
+                           (0.125, 0.15, 0.15),
+                           (0.250, 0.15, 0.15),
+                           (0.375, 0.20, 0.20),
+                           (0.500, 0.25, 0.25),
+                           (0.625, 0.50, 0.50),
+                           (0.750, 0.75, 0.75),
+                           (0.875, 0.90, 0.90),
+                           (1.000, 1.00, 1.00)),
+                'blue':   ((0.000, 0.00, 0.00),
+                           (0.125, 0.50, 0.50),
+                           (0.250, 0.75, 0.75),
+                           (0.375, 0.50, 0.50),
+                           (0.500, 0.15, 0.15),
+                           (0.625, 0.00, 0.00),
+                           (0.750, 0.10, 0.10),
+                           (0.875, 0.50, 0.50),
+                           (1.000, 1.00, 1.00))}
+
+
+# An MIT licensed, colorblind-friendly heatmap from Wistia:
+#   https://github.com/wistia/heatmap-palette
+#   https://wistia.com/learn/culture/heatmaps-for-colorblindness
+#
+# >>> import matplotlib.colors as c
+# >>> colors = ["#e4ff7a", "#ffe81a", "#ffbd00", "#ffa000", "#fc7f00"]
+# >>> cm = c.LinearSegmentedColormap.from_list('wistia', colors)
+# >>> _wistia_data = cm._segmentdata
+# >>> del _wistia_data['alpha']
+#
+_wistia_data = {
+    'red': [(0.0, 0.8941176470588236, 0.8941176470588236),
+            (0.25, 1.0, 1.0),
+            (0.5, 1.0, 1.0),
+            (0.75, 1.0, 1.0),
+            (1.0, 0.9882352941176471, 0.9882352941176471)],
+    'green': [(0.0, 1.0, 1.0),
+              (0.25, 0.9098039215686274, 0.9098039215686274),
+              (0.5, 0.7411764705882353, 0.7411764705882353),
+              (0.75, 0.6274509803921569, 0.6274509803921569),
+              (1.0, 0.4980392156862745, 0.4980392156862745)],
+    'blue': [(0.0, 0.47843137254901963, 0.47843137254901963),
+             (0.25, 0.10196078431372549, 0.10196078431372549),
+             (0.5, 0.0, 0.0),
+             (0.75, 0.0, 0.0),
+             (1.0, 0.0, 0.0)],
+}
+
+
+# Categorical palettes from Vega:
+# https://github.com/vega/vega/wiki/Scales
+# (divided by 255)
+#
+
+_tab10_data = (
+    (0.12156862745098039, 0.4666666666666667,  0.7058823529411765  ),  # 1f77b4
+    (1.0,                 0.4980392156862745,  0.054901960784313725),  # ff7f0e
+    (0.17254901960784313, 0.6274509803921569,  0.17254901960784313 ),  # 2ca02c
+    (0.8392156862745098,  0.15294117647058825, 0.1568627450980392  ),  # d62728
+    (0.5803921568627451,  0.403921568627451,   0.7411764705882353  ),  # 9467bd
+    (0.5490196078431373,  0.33725490196078434, 0.29411764705882354 ),  # 8c564b
+    (0.8901960784313725,  0.4666666666666667,  0.7607843137254902  ),  # e377c2
+    (0.4980392156862745,  0.4980392156862745,  0.4980392156862745  ),  # 7f7f7f
+    (0.7372549019607844,  0.7411764705882353,  0.13333333333333333 ),  # bcbd22
+    (0.09019607843137255, 0.7450980392156863,  0.8117647058823529),    # 17becf
+)
+
+_tab20_data = (
+    (0.12156862745098039, 0.4666666666666667,  0.7058823529411765  ),  # 1f77b4
+    (0.6823529411764706,  0.7803921568627451,  0.9098039215686274  ),  # aec7e8
+    (1.0,                 0.4980392156862745,  0.054901960784313725),  # ff7f0e
+    (1.0,                 0.7333333333333333,  0.47058823529411764 ),  # ffbb78
+    (0.17254901960784313, 0.6274509803921569,  0.17254901960784313 ),  # 2ca02c
+    (0.596078431372549,   0.8745098039215686,  0.5411764705882353  ),  # 98df8a
+    (0.8392156862745098,  0.15294117647058825, 0.1568627450980392  ),  # d62728
+    (1.0,                 0.596078431372549,   0.5882352941176471  ),  # ff9896
+    (0.5803921568627451,  0.403921568627451,   0.7411764705882353  ),  # 9467bd
+    (0.7725490196078432,  0.6901960784313725,  0.8352941176470589  ),  # c5b0d5
+    (0.5490196078431373,  0.33725490196078434, 0.29411764705882354 ),  # 8c564b
+    (0.7686274509803922,  0.611764705882353,   0.5803921568627451  ),  # c49c94
+    (0.8901960784313725,  0.4666666666666667,  0.7607843137254902  ),  # e377c2
+    (0.9686274509803922,  0.7137254901960784,  0.8235294117647058  ),  # f7b6d2
+    (0.4980392156862745,  0.4980392156862745,  0.4980392156862745  ),  # 7f7f7f
+    (0.7803921568627451,  0.7803921568627451,  0.7803921568627451  ),  # c7c7c7
+    (0.7372549019607844,  0.7411764705882353,  0.13333333333333333 ),  # bcbd22
+    (0.8588235294117647,  0.8588235294117647,  0.5529411764705883  ),  # dbdb8d
+    (0.09019607843137255, 0.7450980392156863,  0.8117647058823529  ),  # 17becf
+    (0.6196078431372549,  0.8549019607843137,  0.8980392156862745),    # 9edae5
+)
+
+_tab20b_data = (
+    (0.2235294117647059,  0.23137254901960785, 0.4745098039215686 ),  # 393b79
+    (0.3215686274509804,  0.32941176470588235, 0.6392156862745098 ),  # 5254a3
+    (0.4196078431372549,  0.43137254901960786, 0.8117647058823529 ),  # 6b6ecf
+    (0.611764705882353,   0.6196078431372549,  0.8705882352941177 ),  # 9c9ede
+    (0.38823529411764707, 0.4745098039215686,  0.2235294117647059 ),  # 637939
+    (0.5490196078431373,  0.6352941176470588,  0.3215686274509804 ),  # 8ca252
+    (0.7098039215686275,  0.8117647058823529,  0.4196078431372549 ),  # b5cf6b
+    (0.807843137254902,   0.8588235294117647,  0.611764705882353  ),  # cedb9c
+    (0.5490196078431373,  0.42745098039215684, 0.19215686274509805),  # 8c6d31
+    (0.7411764705882353,  0.6196078431372549,  0.2235294117647059 ),  # bd9e39
+    (0.9058823529411765,  0.7294117647058823,  0.3215686274509804 ),  # e7ba52
+    (0.9058823529411765,  0.796078431372549,   0.5803921568627451 ),  # e7cb94
+    (0.5176470588235295,  0.23529411764705882, 0.2235294117647059 ),  # 843c39
+    (0.6784313725490196,  0.28627450980392155, 0.2901960784313726 ),  # ad494a
+    (0.8392156862745098,  0.3803921568627451,  0.4196078431372549 ),  # d6616b
+    (0.9058823529411765,  0.5882352941176471,  0.611764705882353  ),  # e7969c
+    (0.4823529411764706,  0.2549019607843137,  0.45098039215686275),  # 7b4173
+    (0.6470588235294118,  0.3176470588235294,  0.5803921568627451 ),  # a55194
+    (0.807843137254902,   0.42745098039215684, 0.7411764705882353 ),  # ce6dbd
+    (0.8705882352941177,  0.6196078431372549,  0.8392156862745098 ),  # de9ed6
+)
+
+_tab20c_data = (
+    (0.19215686274509805, 0.5098039215686274,  0.7411764705882353  ),  # 3182bd
+    (0.4196078431372549,  0.6823529411764706,  0.8392156862745098  ),  # 6baed6
+    (0.6196078431372549,  0.792156862745098,   0.8823529411764706  ),  # 9ecae1
+    (0.7764705882352941,  0.8588235294117647,  0.9372549019607843  ),  # c6dbef
+    (0.9019607843137255,  0.3333333333333333,  0.050980392156862744),  # e6550d
+    (0.9921568627450981,  0.5529411764705883,  0.23529411764705882 ),  # fd8d3c
+    (0.9921568627450981,  0.6823529411764706,  0.4196078431372549  ),  # fdae6b
+    (0.9921568627450981,  0.8156862745098039,  0.6352941176470588  ),  # fdd0a2
+    (0.19215686274509805, 0.6392156862745098,  0.32941176470588235 ),  # 31a354
+    (0.4549019607843137,  0.7686274509803922,  0.4627450980392157  ),  # 74c476
+    (0.6313725490196078,  0.8509803921568627,  0.6078431372549019  ),  # a1d99b
+    (0.7803921568627451,  0.9137254901960784,  0.7529411764705882  ),  # c7e9c0
+    (0.4588235294117647,  0.4196078431372549,  0.6941176470588235  ),  # 756bb1
+    (0.6196078431372549,  0.6039215686274509,  0.7843137254901961  ),  # 9e9ac8
+    (0.7372549019607844,  0.7411764705882353,  0.8627450980392157  ),  # bcbddc
+    (0.8549019607843137,  0.8549019607843137,  0.9215686274509803  ),  # dadaeb
+    (0.38823529411764707, 0.38823529411764707, 0.38823529411764707 ),  # 636363
+    (0.5882352941176471,  0.5882352941176471,  0.5882352941176471  ),  # 969696
+    (0.7411764705882353,  0.7411764705882353,  0.7411764705882353  ),  # bdbdbd
+    (0.8509803921568627,  0.8509803921568627,  0.8509803921568627  ),  # d9d9d9
+)
+
+
+_petroff10_data = (
+    (0.24705882352941178, 0.5647058823529412,  0.8549019607843137),    # 3f90da
+    (1.0,                 0.6627450980392157,  0.054901960784313725),  # ffa90e
+    (0.7411764705882353,  0.12156862745098039, 0.00392156862745098),   # bd1f01
+    (0.5803921568627451,  0.6431372549019608,  0.6352941176470588),    # 94a4a2
+    (0.5137254901960784,  0.17647058823529413, 0.7137254901960784),    # 832db6
+    (0.6627450980392157,  0.4196078431372549,  0.34901960784313724),   # a96b59
+    (0.9058823529411765,  0.38823529411764707, 0.0),                   # e76300
+    (0.7254901960784313,  0.6745098039215687,  0.4392156862745098),    # b9ac70
+    (0.44313725490196076, 0.4588235294117647,  0.5058823529411764),    # 717581
+    (0.5725490196078431,  0.8549019607843137,  0.8666666666666667),    # 92dadd
+)
+
+
+datad = {
+    'Blues': _Blues_data,
+    'BrBG': _BrBG_data,
+    'BuGn': _BuGn_data,
+    'BuPu': _BuPu_data,
+    'CMRmap': _CMRmap_data,
+    'GnBu': _GnBu_data,
+    'Greens': _Greens_data,
+    'Greys': _Greys_data,
+    'OrRd': _OrRd_data,
+    'Oranges': _Oranges_data,
+    'PRGn': _PRGn_data,
+    'PiYG': _PiYG_data,
+    'PuBu': _PuBu_data,
+    'PuBuGn': _PuBuGn_data,
+    'PuOr': _PuOr_data,
+    'PuRd': _PuRd_data,
+    'Purples': _Purples_data,
+    'RdBu': _RdBu_data,
+    'RdGy': _RdGy_data,
+    'RdPu': _RdPu_data,
+    'RdYlBu': _RdYlBu_data,
+    'RdYlGn': _RdYlGn_data,
+    'Reds': _Reds_data,
+    'Spectral': _Spectral_data,
+    'Wistia': _wistia_data,
+    'YlGn': _YlGn_data,
+    'YlGnBu': _YlGnBu_data,
+    'YlOrBr': _YlOrBr_data,
+    'YlOrRd': _YlOrRd_data,
+    'afmhot': _afmhot_data,
+    'autumn': _autumn_data,
+    'binary': _binary_data,
+    'bone': _bone_data,
+    'brg': _brg_data,
+    'bwr': _bwr_data,
+    'cool': _cool_data,
+    'coolwarm': _coolwarm_data,
+    'copper': _copper_data,
+    'cubehelix': _cubehelix_data,
+    'flag': _flag_data,
+    'gist_earth': _gist_earth_data,
+    'gist_gray': _gist_gray_data,
+    'gist_heat': _gist_heat_data,
+    'gist_ncar': _gist_ncar_data,
+    'gist_rainbow': _gist_rainbow_data,
+    'gist_stern': _gist_stern_data,
+    'gist_yarg': _gist_yarg_data,
+    'gnuplot': _gnuplot_data,
+    'gnuplot2': _gnuplot2_data,
+    'gray': _gray_data,
+    'hot': _hot_data,
+    'hsv': _hsv_data,
+    'jet': _jet_data,
+    'nipy_spectral': _nipy_spectral_data,
+    'ocean': _ocean_data,
+    'pink': _pink_data,
+    'prism': _prism_data,
+    'rainbow': _rainbow_data,
+    'seismic': _seismic_data,
+    'spring': _spring_data,
+    'summer': _summer_data,
+    'terrain': _terrain_data,
+    'winter': _winter_data,
+    # Qualitative
+    'Accent': {'listed': _Accent_data},
+    'Dark2': {'listed': _Dark2_data},
+    'Paired': {'listed': _Paired_data},
+    'Pastel1': {'listed': _Pastel1_data},
+    'Pastel2': {'listed': _Pastel2_data},
+    'Set1': {'listed': _Set1_data},
+    'Set2': {'listed': _Set2_data},
+    'Set3': {'listed': _Set3_data},
+    'tab10': {'listed': _tab10_data},
+    'tab20': {'listed': _tab20_data},
+    'tab20b': {'listed': _tab20b_data},
+    'tab20c': {'listed': _tab20c_data},
+}
diff --git a/lib/python3.12/site-packages/matplotlib/_cm_bivar.py b/lib/python3.12/site-packages/matplotlib/_cm_bivar.py
new file mode 100644
index 0000000000000000000000000000000000000000..53c0d48d7d6c5d3818a33df783a284e11c16662d
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_cm_bivar.py
@@ -0,0 +1,1312 @@
+# auto-generated by https://github.com/trygvrad/multivariate_colormaps
+# date: 2024-05-24
+
+import numpy as np
+from matplotlib.colors import SegmentedBivarColormap
+
+BiPeak = np.array(
+    [0.000, 0.674, 0.931, 0.000, 0.680, 0.922, 0.000, 0.685, 0.914, 0.000,
+     0.691, 0.906, 0.000, 0.696, 0.898, 0.000, 0.701, 0.890, 0.000, 0.706,
+     0.882, 0.000, 0.711, 0.875, 0.000, 0.715, 0.867, 0.000, 0.720, 0.860,
+     0.000, 0.725, 0.853, 0.000, 0.729, 0.845, 0.000, 0.733, 0.838, 0.000,
+     0.737, 0.831, 0.000, 0.741, 0.824, 0.000, 0.745, 0.816, 0.000, 0.749,
+     0.809, 0.000, 0.752, 0.802, 0.000, 0.756, 0.794, 0.000, 0.759, 0.787,
+     0.000, 0.762, 0.779, 0.000, 0.765, 0.771, 0.000, 0.767, 0.764, 0.000,
+     0.770, 0.755, 0.000, 0.772, 0.747, 0.000, 0.774, 0.739, 0.000, 0.776,
+     0.730, 0.000, 0.777, 0.721, 0.000, 0.779, 0.712, 0.021, 0.780, 0.702,
+     0.055, 0.781, 0.693, 0.079, 0.782, 0.682, 0.097, 0.782, 0.672, 0.111,
+     0.782, 0.661, 0.122, 0.782, 0.650, 0.132, 0.782, 0.639, 0.140, 0.781,
+     0.627, 0.147, 0.781, 0.615, 0.154, 0.780, 0.602, 0.159, 0.778, 0.589,
+     0.164, 0.777, 0.576, 0.169, 0.775, 0.563, 0.173, 0.773, 0.549, 0.177,
+     0.771, 0.535, 0.180, 0.768, 0.520, 0.184, 0.766, 0.505, 0.187, 0.763,
+     0.490, 0.190, 0.760, 0.474, 0.193, 0.756, 0.458, 0.196, 0.753, 0.442,
+     0.200, 0.749, 0.425, 0.203, 0.745, 0.408, 0.206, 0.741, 0.391, 0.210,
+     0.736, 0.373, 0.213, 0.732, 0.355, 0.216, 0.727, 0.337, 0.220, 0.722,
+     0.318, 0.224, 0.717, 0.298, 0.227, 0.712, 0.278, 0.231, 0.707, 0.258,
+     0.235, 0.701, 0.236, 0.239, 0.696, 0.214, 0.242, 0.690, 0.190, 0.246,
+     0.684, 0.165, 0.250, 0.678, 0.136, 0.000, 0.675, 0.934, 0.000, 0.681,
+     0.925, 0.000, 0.687, 0.917, 0.000, 0.692, 0.909, 0.000, 0.697, 0.901,
+     0.000, 0.703, 0.894, 0.000, 0.708, 0.886, 0.000, 0.713, 0.879, 0.000,
+     0.718, 0.872, 0.000, 0.722, 0.864, 0.000, 0.727, 0.857, 0.000, 0.731,
+     0.850, 0.000, 0.736, 0.843, 0.000, 0.740, 0.836, 0.000, 0.744, 0.829,
+     0.000, 0.748, 0.822, 0.000, 0.752, 0.815, 0.000, 0.755, 0.808, 0.000,
+     0.759, 0.800, 0.000, 0.762, 0.793, 0.000, 0.765, 0.786, 0.000, 0.768,
+     0.778, 0.000, 0.771, 0.770, 0.000, 0.773, 0.762, 0.051, 0.776, 0.754,
+     0.087, 0.778, 0.746, 0.111, 0.780, 0.737, 0.131, 0.782, 0.728, 0.146,
+     0.783, 0.719, 0.159, 0.784, 0.710, 0.171, 0.785, 0.700, 0.180, 0.786,
+     0.690, 0.189, 0.786, 0.680, 0.196, 0.787, 0.669, 0.202, 0.787, 0.658,
+     0.208, 0.786, 0.647, 0.213, 0.786, 0.635, 0.217, 0.785, 0.623, 0.221,
+     0.784, 0.610, 0.224, 0.782, 0.597, 0.227, 0.781, 0.584, 0.230, 0.779,
+     0.570, 0.232, 0.777, 0.556, 0.234, 0.775, 0.542, 0.236, 0.772, 0.527,
+     0.238, 0.769, 0.512, 0.240, 0.766, 0.497, 0.242, 0.763, 0.481, 0.244,
+     0.760, 0.465, 0.246, 0.756, 0.448, 0.248, 0.752, 0.432, 0.250, 0.748,
+     0.415, 0.252, 0.744, 0.397, 0.254, 0.739, 0.379, 0.256, 0.735, 0.361,
+     0.259, 0.730, 0.343, 0.261, 0.725, 0.324, 0.264, 0.720, 0.304, 0.266,
+     0.715, 0.284, 0.269, 0.709, 0.263, 0.271, 0.704, 0.242, 0.274, 0.698,
+     0.220, 0.277, 0.692, 0.196, 0.280, 0.686, 0.170, 0.283, 0.680, 0.143,
+     0.000, 0.676, 0.937, 0.000, 0.682, 0.928, 0.000, 0.688, 0.920, 0.000,
+     0.694, 0.913, 0.000, 0.699, 0.905, 0.000, 0.704, 0.897, 0.000, 0.710,
+     0.890, 0.000, 0.715, 0.883, 0.000, 0.720, 0.876, 0.000, 0.724, 0.869,
+     0.000, 0.729, 0.862, 0.000, 0.734, 0.855, 0.000, 0.738, 0.848, 0.000,
+     0.743, 0.841, 0.000, 0.747, 0.834, 0.000, 0.751, 0.827, 0.000, 0.755,
+     0.820, 0.000, 0.759, 0.813, 0.000, 0.762, 0.806, 0.003, 0.766, 0.799,
+     0.066, 0.769, 0.792, 0.104, 0.772, 0.784, 0.131, 0.775, 0.777, 0.152,
+     0.777, 0.769, 0.170, 0.780, 0.761, 0.185, 0.782, 0.753, 0.198, 0.784,
+     0.744, 0.209, 0.786, 0.736, 0.219, 0.787, 0.727, 0.228, 0.788, 0.717,
+     0.236, 0.789, 0.708, 0.243, 0.790, 0.698, 0.249, 0.791, 0.688, 0.254,
+     0.791, 0.677, 0.259, 0.791, 0.666, 0.263, 0.791, 0.654, 0.266, 0.790,
+     0.643, 0.269, 0.789, 0.631, 0.272, 0.788, 0.618, 0.274, 0.787, 0.605,
+     0.276, 0.785, 0.592, 0.278, 0.783, 0.578, 0.279, 0.781, 0.564, 0.280,
+     0.779, 0.549, 0.282, 0.776, 0.535, 0.283, 0.773, 0.519, 0.284, 0.770,
+     0.504, 0.285, 0.767, 0.488, 0.286, 0.763, 0.472, 0.287, 0.759, 0.455,
+     0.288, 0.756, 0.438, 0.289, 0.751, 0.421, 0.291, 0.747, 0.403, 0.292,
+     0.742, 0.385, 0.293, 0.738, 0.367, 0.295, 0.733, 0.348, 0.296, 0.728,
+     0.329, 0.298, 0.723, 0.310, 0.300, 0.717, 0.290, 0.302, 0.712, 0.269,
+     0.304, 0.706, 0.247, 0.306, 0.700, 0.225, 0.308, 0.694, 0.201, 0.310,
+     0.688, 0.176, 0.312, 0.682, 0.149, 0.000, 0.678, 0.939, 0.000, 0.683,
+     0.931, 0.000, 0.689, 0.923, 0.000, 0.695, 0.916, 0.000, 0.701, 0.908,
+     0.000, 0.706, 0.901, 0.000, 0.711, 0.894, 0.000, 0.717, 0.887, 0.000,
+     0.722, 0.880, 0.000, 0.727, 0.873, 0.000, 0.732, 0.866, 0.000, 0.736,
+     0.859, 0.000, 0.741, 0.853, 0.000, 0.745, 0.846, 0.000, 0.750, 0.839,
+     0.000, 0.754, 0.833, 0.035, 0.758, 0.826, 0.091, 0.762, 0.819, 0.126,
+     0.765, 0.812, 0.153, 0.769, 0.805, 0.174, 0.772, 0.798, 0.193, 0.775,
+     0.791, 0.209, 0.778, 0.783, 0.223, 0.781, 0.776, 0.236, 0.784, 0.768,
+     0.247, 0.786, 0.760, 0.257, 0.788, 0.752, 0.266, 0.790, 0.743, 0.273,
+     0.791, 0.734, 0.280, 0.793, 0.725, 0.287, 0.794, 0.715, 0.292, 0.794,
+     0.706, 0.297, 0.795, 0.695, 0.301, 0.795, 0.685, 0.305, 0.795, 0.674,
+     0.308, 0.795, 0.662, 0.310, 0.794, 0.651, 0.312, 0.794, 0.638, 0.314,
+     0.792, 0.626, 0.316, 0.791, 0.613, 0.317, 0.789, 0.599, 0.318, 0.787,
+     0.586, 0.319, 0.785, 0.571, 0.320, 0.783, 0.557, 0.320, 0.780, 0.542,
+     0.321, 0.777, 0.527, 0.321, 0.774, 0.511, 0.322, 0.770, 0.495, 0.322,
+     0.767, 0.478, 0.323, 0.763, 0.462, 0.323, 0.759, 0.445, 0.324, 0.755,
+     0.427, 0.325, 0.750, 0.410, 0.325, 0.745, 0.391, 0.326, 0.741, 0.373,
+     0.327, 0.736, 0.354, 0.328, 0.730, 0.335, 0.329, 0.725, 0.315, 0.330,
+     0.720, 0.295, 0.331, 0.714, 0.274, 0.333, 0.708, 0.253, 0.334, 0.702,
+     0.230, 0.336, 0.696, 0.207, 0.337, 0.690, 0.182, 0.339, 0.684, 0.154,
+     0.000, 0.679, 0.942, 0.000, 0.685, 0.934, 0.000, 0.691, 0.927, 0.000,
+     0.696, 0.919, 0.000, 0.702, 0.912, 0.000, 0.708, 0.905, 0.000, 0.713,
+     0.898, 0.000, 0.718, 0.891, 0.000, 0.724, 0.884, 0.000, 0.729, 0.877,
+     0.000, 0.734, 0.871, 0.000, 0.739, 0.864, 0.000, 0.743, 0.857, 0.035,
+     0.748, 0.851, 0.096, 0.752, 0.844, 0.133, 0.757, 0.838, 0.161, 0.761,
+     0.831, 0.185, 0.765, 0.825, 0.205, 0.769, 0.818, 0.223, 0.772, 0.811,
+     0.238, 0.776, 0.804, 0.252, 0.779, 0.797, 0.265, 0.782, 0.790, 0.276,
+     0.785, 0.783, 0.286, 0.788, 0.775, 0.296, 0.790, 0.767, 0.304, 0.792,
+     0.759, 0.311, 0.794, 0.751, 0.318, 0.796, 0.742, 0.324, 0.797, 0.733,
+     0.329, 0.798, 0.723, 0.334, 0.799, 0.714, 0.338, 0.799, 0.703, 0.341,
+     0.800, 0.693, 0.344, 0.800, 0.682, 0.347, 0.799, 0.670, 0.349, 0.799,
+     0.659, 0.351, 0.798, 0.646, 0.352, 0.797, 0.634, 0.353, 0.795, 0.621,
+     0.354, 0.794, 0.607, 0.354, 0.792, 0.593, 0.355, 0.789, 0.579, 0.355,
+     0.787, 0.564, 0.355, 0.784, 0.549, 0.355, 0.781, 0.534, 0.355, 0.778,
+     0.518, 0.355, 0.774, 0.502, 0.355, 0.770, 0.485, 0.355, 0.766, 0.468,
+     0.355, 0.762, 0.451, 0.355, 0.758, 0.434, 0.355, 0.753, 0.416, 0.356,
+     0.748, 0.397, 0.356, 0.743, 0.379, 0.356, 0.738, 0.360, 0.357, 0.733,
+     0.340, 0.357, 0.728, 0.321, 0.358, 0.722, 0.300, 0.359, 0.716, 0.279,
+     0.360, 0.710, 0.258, 0.361, 0.704, 0.235, 0.361, 0.698, 0.212, 0.362,
+     0.692, 0.187, 0.363, 0.686, 0.160, 0.000, 0.680, 0.945, 0.000, 0.686,
+     0.937, 0.000, 0.692, 0.930, 0.000, 0.698, 0.922, 0.000, 0.703, 0.915,
+     0.000, 0.709, 0.908, 0.000, 0.715, 0.901, 0.000, 0.720, 0.894, 0.000,
+     0.726, 0.888, 0.000, 0.731, 0.881, 0.007, 0.736, 0.875, 0.084, 0.741,
+     0.869, 0.127, 0.746, 0.862, 0.159, 0.751, 0.856, 0.185, 0.755, 0.850,
+     0.208, 0.760, 0.843, 0.227, 0.764, 0.837, 0.245, 0.768, 0.830, 0.260,
+     0.772, 0.824, 0.275, 0.776, 0.817, 0.288, 0.779, 0.811, 0.300, 0.783,
+     0.804, 0.310, 0.786, 0.797, 0.320, 0.789, 0.789, 0.329, 0.792, 0.782,
+     0.337, 0.794, 0.774, 0.345, 0.796, 0.766, 0.351, 0.798, 0.758, 0.357,
+     0.800, 0.749, 0.363, 0.801, 0.740, 0.367, 0.803, 0.731, 0.371, 0.803,
+     0.721, 0.375, 0.804, 0.711, 0.378, 0.804, 0.701, 0.380, 0.804, 0.690,
+     0.382, 0.804, 0.679, 0.384, 0.803, 0.667, 0.385, 0.802, 0.654, 0.386,
+     0.801, 0.642, 0.386, 0.800, 0.629, 0.387, 0.798, 0.615, 0.387, 0.796,
+     0.601, 0.387, 0.793, 0.587, 0.387, 0.791, 0.572, 0.387, 0.788, 0.557,
+     0.386, 0.785, 0.541, 0.386, 0.781, 0.525, 0.385, 0.778, 0.509, 0.385,
+     0.774, 0.492, 0.385, 0.770, 0.475, 0.384, 0.765, 0.457, 0.384, 0.761,
+     0.440, 0.384, 0.756, 0.422, 0.384, 0.751, 0.403, 0.384, 0.746, 0.384,
+     0.384, 0.741, 0.365, 0.384, 0.735, 0.346, 0.384, 0.730, 0.326, 0.384,
+     0.724, 0.305, 0.384, 0.718, 0.284, 0.385, 0.712, 0.263, 0.385, 0.706,
+     0.240, 0.386, 0.700, 0.217, 0.386, 0.694, 0.192, 0.387, 0.687, 0.165,
+     0.000, 0.680, 0.948, 0.000, 0.687, 0.940, 0.000, 0.693, 0.933, 0.000,
+     0.699, 0.925, 0.000, 0.705, 0.918, 0.000, 0.711, 0.912, 0.000, 0.716,
+     0.905, 0.000, 0.722, 0.898, 0.050, 0.728, 0.892, 0.109, 0.733, 0.886,
+     0.147, 0.738, 0.879, 0.177, 0.743, 0.873, 0.202, 0.748, 0.867, 0.224,
+     0.753, 0.861, 0.243, 0.758, 0.855, 0.261, 0.763, 0.849, 0.277, 0.767,
+     0.842, 0.292, 0.771, 0.836, 0.305, 0.775, 0.830, 0.318, 0.779, 0.823,
+     0.329, 0.783, 0.817, 0.340, 0.787, 0.810, 0.350, 0.790, 0.803, 0.359,
+     0.793, 0.796, 0.367, 0.796, 0.789, 0.374, 0.798, 0.782, 0.381, 0.801,
+     0.774, 0.387, 0.803, 0.766, 0.393, 0.804, 0.757, 0.397, 0.806, 0.748,
+     0.402, 0.807, 0.739, 0.405, 0.808, 0.729, 0.408, 0.809, 0.719, 0.411,
+     0.809, 0.709, 0.413, 0.809, 0.698, 0.415, 0.808, 0.687, 0.416, 0.808,
+     0.675, 0.417, 0.807, 0.663, 0.417, 0.806, 0.650, 0.417, 0.804, 0.637,
+     0.418, 0.802, 0.623, 0.417, 0.800, 0.609, 0.417, 0.798, 0.594, 0.416,
+     0.795, 0.579, 0.416, 0.792, 0.564, 0.415, 0.789, 0.548, 0.414, 0.785,
+     0.532, 0.414, 0.781, 0.515, 0.413, 0.777, 0.499, 0.412, 0.773, 0.481,
+     0.412, 0.769, 0.464, 0.411, 0.764, 0.446, 0.410, 0.759, 0.428, 0.410,
+     0.754, 0.409, 0.409, 0.749, 0.390, 0.409, 0.743, 0.371, 0.409, 0.738,
+     0.351, 0.409, 0.732, 0.331, 0.408, 0.726, 0.310, 0.408, 0.720, 0.289,
+     0.408, 0.714, 0.268, 0.408, 0.708, 0.245, 0.409, 0.702, 0.222, 0.409,
+     0.695, 0.197, 0.409, 0.689, 0.170, 0.000, 0.681, 0.950, 0.000, 0.688,
+     0.943, 0.000, 0.694, 0.936, 0.000, 0.700, 0.929, 0.000, 0.706, 0.922,
+     0.000, 0.712, 0.915, 0.074, 0.718, 0.908, 0.124, 0.724, 0.902, 0.159,
+     0.730, 0.896, 0.188, 0.735, 0.890, 0.213, 0.740, 0.884, 0.235, 0.746,
+     0.878, 0.255, 0.751, 0.872, 0.273, 0.756, 0.866, 0.289, 0.761, 0.860,
+     0.305, 0.766, 0.854, 0.319, 0.770, 0.848, 0.332, 0.775, 0.842, 0.344,
+     0.779, 0.836, 0.356, 0.783, 0.830, 0.366, 0.787, 0.823, 0.376, 0.790,
+     0.817, 0.385, 0.794, 0.810, 0.394, 0.797, 0.803, 0.401, 0.800, 0.796,
+     0.408, 0.802, 0.789, 0.414, 0.805, 0.781, 0.420, 0.807, 0.773, 0.425,
+     0.809, 0.765, 0.430, 0.810, 0.756, 0.433, 0.812, 0.747, 0.437, 0.813,
+     0.738, 0.440, 0.813, 0.728, 0.442, 0.814, 0.717, 0.444, 0.813, 0.706,
+     0.445, 0.813, 0.695, 0.446, 0.812, 0.683, 0.446, 0.811, 0.671, 0.447,
+     0.810, 0.658, 0.447, 0.809, 0.645, 0.446, 0.807, 0.631, 0.446, 0.804,
+     0.617, 0.445, 0.802, 0.602, 0.444, 0.799, 0.587, 0.443, 0.796, 0.571,
+     0.442, 0.792, 0.555, 0.441, 0.789, 0.539, 0.440, 0.785, 0.522, 0.439,
+     0.781, 0.505, 0.438, 0.776, 0.488, 0.437, 0.772, 0.470, 0.436, 0.767,
+     0.452, 0.435, 0.762, 0.433, 0.435, 0.757, 0.415, 0.434, 0.751, 0.396,
+     0.433, 0.746, 0.376, 0.432, 0.740, 0.356, 0.432, 0.734, 0.336, 0.431,
+     0.728, 0.315, 0.431, 0.722, 0.294, 0.431, 0.716, 0.272, 0.430, 0.710,
+     0.250, 0.430, 0.703, 0.226, 0.430, 0.697, 0.201, 0.430, 0.690, 0.175,
+     0.000, 0.682, 0.953, 0.000, 0.689, 0.946, 0.000, 0.695, 0.938, 0.002,
+     0.701, 0.932, 0.086, 0.708, 0.925, 0.133, 0.714, 0.918, 0.167, 0.720,
+     0.912, 0.196, 0.726, 0.906, 0.221, 0.731, 0.900, 0.243, 0.737, 0.894,
+     0.263, 0.743, 0.888, 0.281, 0.748, 0.882, 0.298, 0.753, 0.876, 0.314,
+     0.759, 0.870, 0.329, 0.764, 0.865, 0.342, 0.768, 0.859, 0.355, 0.773,
+     0.853, 0.368, 0.778, 0.847, 0.379, 0.782, 0.842, 0.390, 0.786, 0.836,
+     0.400, 0.790, 0.830, 0.409, 0.794, 0.823, 0.417, 0.798, 0.817, 0.425,
+     0.801, 0.810, 0.433, 0.804, 0.803, 0.439, 0.807, 0.796, 0.445, 0.809,
+     0.789, 0.451, 0.811, 0.781, 0.456, 0.813, 0.773, 0.460, 0.815, 0.764,
+     0.463, 0.816, 0.755, 0.466, 0.817, 0.746, 0.469, 0.818, 0.736, 0.471,
+     0.818, 0.725, 0.472, 0.818, 0.715, 0.473, 0.818, 0.703, 0.474, 0.817,
+     0.691, 0.474, 0.816, 0.679, 0.474, 0.815, 0.666, 0.474, 0.813, 0.653,
+     0.473, 0.811, 0.639, 0.473, 0.809, 0.624, 0.472, 0.806, 0.610, 0.471,
+     0.803, 0.594, 0.469, 0.800, 0.579, 0.468, 0.796, 0.562, 0.467, 0.792,
+     0.546, 0.466, 0.788, 0.529, 0.464, 0.784, 0.512, 0.463, 0.780, 0.494,
+     0.462, 0.775, 0.476, 0.460, 0.770, 0.458, 0.459, 0.765, 0.439, 0.458,
+     0.759, 0.420, 0.457, 0.754, 0.401, 0.456, 0.748, 0.381, 0.455, 0.742,
+     0.361, 0.454, 0.736, 0.341, 0.453, 0.730, 0.320, 0.453, 0.724, 0.299,
+     0.452, 0.718, 0.277, 0.452, 0.711, 0.254, 0.451, 0.705, 0.231, 0.451,
+     0.698, 0.206, 0.450, 0.691, 0.179, 0.000, 0.683, 0.955, 0.013, 0.689,
+     0.948, 0.092, 0.696, 0.941, 0.137, 0.702, 0.935, 0.171, 0.709, 0.928,
+     0.200, 0.715, 0.922, 0.225, 0.721, 0.916, 0.247, 0.727, 0.909, 0.267,
+     0.733, 0.904, 0.286, 0.739, 0.898, 0.303, 0.745, 0.892, 0.320, 0.750,
+     0.886, 0.335, 0.756, 0.881, 0.350, 0.761, 0.875, 0.363, 0.766, 0.870,
+     0.376, 0.771, 0.864, 0.388, 0.776, 0.859, 0.400, 0.781, 0.853, 0.411,
+     0.785, 0.847, 0.421, 0.790, 0.842, 0.430, 0.794, 0.836, 0.439, 0.798,
+     0.830, 0.448, 0.802, 0.824, 0.455, 0.805, 0.817, 0.462, 0.808, 0.810,
+     0.469, 0.811, 0.804, 0.475, 0.814, 0.796, 0.480, 0.816, 0.789, 0.484,
+     0.818, 0.781, 0.488, 0.820, 0.772, 0.492, 0.821, 0.763, 0.495, 0.822,
+     0.754, 0.497, 0.823, 0.744, 0.499, 0.823, 0.734, 0.500, 0.823, 0.723,
+     0.501, 0.823, 0.712, 0.501, 0.822, 0.700, 0.501, 0.821, 0.687, 0.501,
+     0.819, 0.674, 0.500, 0.818, 0.661, 0.499, 0.815, 0.647, 0.498, 0.813,
+     0.632, 0.497, 0.810, 0.617, 0.496, 0.807, 0.602, 0.494, 0.804, 0.586,
+     0.493, 0.800, 0.569, 0.491, 0.796, 0.553, 0.490, 0.792, 0.536, 0.488,
+     0.787, 0.518, 0.486, 0.783, 0.500, 0.485, 0.778, 0.482, 0.483, 0.773,
+     0.463, 0.482, 0.767, 0.445, 0.480, 0.762, 0.425, 0.479, 0.756, 0.406,
+     0.478, 0.750, 0.386, 0.477, 0.744, 0.366, 0.476, 0.738, 0.345, 0.475,
+     0.732, 0.325, 0.474, 0.726, 0.303, 0.473, 0.719, 0.281, 0.472, 0.713,
+     0.258, 0.471, 0.706, 0.235, 0.470, 0.699, 0.210, 0.469, 0.692, 0.184,
+     0.095, 0.683, 0.958, 0.139, 0.690, 0.951, 0.173, 0.697, 0.944, 0.201,
+     0.703, 0.938, 0.226, 0.710, 0.931, 0.249, 0.716, 0.925, 0.269, 0.723,
+     0.919, 0.288, 0.729, 0.913, 0.306, 0.735, 0.907, 0.323, 0.741, 0.902,
+     0.339, 0.747, 0.896, 0.354, 0.752, 0.891, 0.368, 0.758, 0.885, 0.382,
+     0.764, 0.880, 0.394, 0.769, 0.875, 0.407, 0.774, 0.869, 0.418, 0.779,
+     0.864, 0.429, 0.784, 0.859, 0.440, 0.789, 0.853, 0.450, 0.793, 0.848,
+     0.459, 0.798, 0.842, 0.468, 0.802, 0.836, 0.476, 0.806, 0.830, 0.483,
+     0.809, 0.824, 0.490, 0.812, 0.818, 0.496, 0.815, 0.811, 0.502, 0.818,
+     0.804, 0.507, 0.821, 0.796, 0.512, 0.823, 0.789, 0.515, 0.825, 0.780,
+     0.519, 0.826, 0.772, 0.521, 0.827, 0.762, 0.524, 0.828, 0.753, 0.525,
+     0.828, 0.742, 0.526, 0.828, 0.732, 0.527, 0.828, 0.720, 0.527, 0.827,
+     0.708, 0.527, 0.826, 0.696, 0.526, 0.824, 0.683, 0.525, 0.822, 0.669,
+     0.524, 0.820, 0.655, 0.523, 0.817, 0.640, 0.522, 0.814, 0.625, 0.520,
+     0.811, 0.609, 0.518, 0.808, 0.593, 0.516, 0.804, 0.576, 0.515, 0.800,
+     0.559, 0.513, 0.795, 0.542, 0.511, 0.791, 0.524, 0.509, 0.786, 0.506,
+     0.507, 0.781, 0.488, 0.505, 0.775, 0.469, 0.504, 0.770, 0.450, 0.502,
+     0.764, 0.431, 0.500, 0.759, 0.411, 0.499, 0.753, 0.391, 0.497, 0.746,
+     0.371, 0.496, 0.740, 0.350, 0.495, 0.734, 0.329, 0.494, 0.727, 0.307,
+     0.492, 0.721, 0.285, 0.491, 0.714, 0.262, 0.490, 0.707, 0.239, 0.489,
+     0.700, 0.214, 0.488, 0.693, 0.188, 0.172, 0.684, 0.961, 0.201, 0.691,
+     0.954, 0.226, 0.698, 0.947, 0.248, 0.704, 0.941, 0.269, 0.711, 0.934,
+     0.289, 0.717, 0.928, 0.307, 0.724, 0.922, 0.324, 0.730, 0.917, 0.340,
+     0.736, 0.911, 0.356, 0.743, 0.906, 0.370, 0.749, 0.900, 0.384, 0.755,
+     0.895, 0.398, 0.760, 0.890, 0.411, 0.766, 0.885, 0.423, 0.772, 0.880,
+     0.435, 0.777, 0.874, 0.446, 0.782, 0.869, 0.457, 0.787, 0.864, 0.467,
+     0.792, 0.859, 0.477, 0.797, 0.854, 0.486, 0.801, 0.848, 0.494, 0.806,
+     0.843, 0.502, 0.810, 0.837, 0.510, 0.813, 0.831, 0.517, 0.817, 0.825,
+     0.523, 0.820, 0.818, 0.528, 0.823, 0.811, 0.533, 0.825, 0.804, 0.538,
+     0.828, 0.797, 0.542, 0.829, 0.788, 0.545, 0.831, 0.780, 0.547, 0.832,
+     0.771, 0.549, 0.833, 0.761, 0.551, 0.833, 0.751, 0.552, 0.833, 0.740,
+     0.552, 0.833, 0.729, 0.552, 0.832, 0.717, 0.551, 0.830, 0.704, 0.551,
+     0.829, 0.691, 0.550, 0.827, 0.677, 0.548, 0.824, 0.663, 0.547, 0.822,
+     0.648, 0.545, 0.819, 0.632, 0.543, 0.815, 0.617, 0.541, 0.812, 0.600,
+     0.539, 0.808, 0.583, 0.537, 0.803, 0.566, 0.535, 0.799, 0.549, 0.533,
+     0.794, 0.531, 0.531, 0.789, 0.512, 0.529, 0.784, 0.494, 0.527, 0.778,
+     0.475, 0.525, 0.773, 0.455, 0.523, 0.767, 0.436, 0.521, 0.761, 0.416,
+     0.519, 0.755, 0.396, 0.517, 0.748, 0.375, 0.516, 0.742, 0.354, 0.514,
+     0.735, 0.333, 0.513, 0.729, 0.311, 0.511, 0.722, 0.289, 0.510, 0.715,
+     0.266, 0.509, 0.708, 0.242, 0.507, 0.701, 0.218, 0.506, 0.694, 0.191,
+     0.224, 0.684, 0.963, 0.247, 0.691, 0.956, 0.268, 0.698, 0.950, 0.287,
+     0.705, 0.943, 0.305, 0.712, 0.937, 0.323, 0.719, 0.931, 0.339, 0.725,
+     0.926, 0.355, 0.732, 0.920, 0.370, 0.738, 0.915, 0.385, 0.744, 0.909,
+     0.399, 0.751, 0.904, 0.412, 0.757, 0.899, 0.425, 0.763, 0.894, 0.438,
+     0.768, 0.889, 0.450, 0.774, 0.884, 0.461, 0.780, 0.879, 0.472, 0.785,
+     0.875, 0.483, 0.790, 0.870, 0.493, 0.795, 0.865, 0.502, 0.800, 0.860,
+     0.511, 0.805, 0.855, 0.520, 0.809, 0.849, 0.528, 0.814, 0.844, 0.535,
+     0.818, 0.838, 0.542, 0.821, 0.832, 0.548, 0.824, 0.826, 0.554, 0.827,
+     0.819, 0.559, 0.830, 0.812, 0.563, 0.832, 0.805, 0.567, 0.834, 0.797,
+     0.570, 0.836, 0.788, 0.572, 0.837, 0.779, 0.574, 0.838, 0.770, 0.575,
+     0.838, 0.760, 0.576, 0.838, 0.749, 0.576, 0.838, 0.737, 0.576, 0.837,
+     0.725, 0.575, 0.835, 0.713, 0.574, 0.834, 0.699, 0.573, 0.831, 0.685,
+     0.571, 0.829, 0.671, 0.570, 0.826, 0.656, 0.568, 0.823, 0.640, 0.566,
+     0.819, 0.624, 0.563, 0.815, 0.607, 0.561, 0.811, 0.590, 0.559, 0.807,
+     0.573, 0.556, 0.802, 0.555, 0.554, 0.797, 0.537, 0.552, 0.792, 0.518,
+     0.549, 0.786, 0.499, 0.547, 0.781, 0.480, 0.545, 0.775, 0.460, 0.543,
+     0.769, 0.441, 0.541, 0.763, 0.420, 0.539, 0.756, 0.400, 0.537, 0.750,
+     0.379, 0.535, 0.743, 0.358, 0.533, 0.737, 0.337, 0.531, 0.730, 0.315,
+     0.530, 0.723, 0.293, 0.528, 0.716, 0.270, 0.527, 0.709, 0.246, 0.525,
+     0.702, 0.221, 0.524, 0.694, 0.195, 0.265, 0.685, 0.965, 0.284, 0.692,
+     0.959, 0.303, 0.699, 0.952, 0.320, 0.706, 0.946, 0.337, 0.713, 0.940,
+     0.353, 0.720, 0.935, 0.369, 0.726, 0.929, 0.384, 0.733, 0.924, 0.398,
+     0.739, 0.918, 0.412, 0.746, 0.913, 0.425, 0.752, 0.908, 0.438, 0.759,
+     0.903, 0.451, 0.765, 0.899, 0.463, 0.771, 0.894, 0.475, 0.777, 0.889,
+     0.486, 0.782, 0.884, 0.497, 0.788, 0.880, 0.507, 0.793, 0.875, 0.517,
+     0.799, 0.870, 0.527, 0.804, 0.866, 0.536, 0.809, 0.861, 0.544, 0.813,
+     0.856, 0.552, 0.818, 0.850, 0.560, 0.822, 0.845, 0.566, 0.826, 0.839,
+     0.573, 0.829, 0.833, 0.578, 0.832, 0.827, 0.583, 0.835, 0.820, 0.587,
+     0.837, 0.813, 0.591, 0.839, 0.805, 0.594, 0.841, 0.797, 0.596, 0.842,
+     0.788, 0.598, 0.843, 0.778, 0.599, 0.843, 0.768, 0.600, 0.843, 0.758,
+     0.600, 0.843, 0.746, 0.599, 0.842, 0.734, 0.599, 0.840, 0.721, 0.597,
+     0.838, 0.708, 0.596, 0.836, 0.694, 0.594, 0.834, 0.679, 0.592, 0.831,
+     0.663, 0.590, 0.827, 0.648, 0.587, 0.823, 0.631, 0.585, 0.819, 0.614,
+     0.582, 0.815, 0.597, 0.580, 0.810, 0.579, 0.577, 0.805, 0.561, 0.575,
+     0.800, 0.542, 0.572, 0.795, 0.524, 0.569, 0.789, 0.504, 0.567, 0.783,
+     0.485, 0.565, 0.777, 0.465, 0.562, 0.771, 0.445, 0.560, 0.765, 0.425,
+     0.558, 0.758, 0.404, 0.556, 0.752, 0.383, 0.554, 0.745, 0.362, 0.552,
+     0.738, 0.341, 0.550, 0.731, 0.319, 0.548, 0.724, 0.296, 0.546, 0.717,
+     0.273, 0.544, 0.709, 0.249, 0.542, 0.702, 0.224, 0.541, 0.695, 0.198,
+     0.299, 0.685, 0.968, 0.317, 0.692, 0.961, 0.334, 0.699, 0.955, 0.350,
+     0.706, 0.949, 0.366, 0.713, 0.943, 0.381, 0.720, 0.938, 0.395, 0.727,
+     0.932, 0.410, 0.734, 0.927, 0.423, 0.741, 0.922, 0.437, 0.747, 0.917,
+     0.450, 0.754, 0.912, 0.463, 0.760, 0.907, 0.475, 0.767, 0.903, 0.487,
+     0.773, 0.898, 0.498, 0.779, 0.894, 0.509, 0.785, 0.889, 0.520, 0.791,
+     0.885, 0.531, 0.796, 0.880, 0.540, 0.802, 0.876, 0.550, 0.807, 0.871,
+     0.559, 0.812, 0.867, 0.568, 0.817, 0.862, 0.576, 0.822, 0.857, 0.583,
+     0.826, 0.852, 0.590, 0.830, 0.847, 0.596, 0.834, 0.841, 0.602, 0.837,
+     0.835, 0.607, 0.840, 0.828, 0.611, 0.843, 0.821, 0.615, 0.845, 0.814,
+     0.618, 0.846, 0.805, 0.620, 0.848, 0.797, 0.622, 0.848, 0.787, 0.623,
+     0.849, 0.777, 0.623, 0.849, 0.766, 0.623, 0.848, 0.755, 0.622, 0.847,
+     0.743, 0.621, 0.845, 0.730, 0.620, 0.843, 0.716, 0.618, 0.841, 0.702,
+     0.616, 0.838, 0.687, 0.613, 0.835, 0.671, 0.611, 0.831, 0.655, 0.608,
+     0.827, 0.638, 0.606, 0.823, 0.621, 0.603, 0.818, 0.604, 0.600, 0.814,
+     0.585, 0.597, 0.808, 0.567, 0.594, 0.803, 0.548, 0.592, 0.797, 0.529,
+     0.589, 0.792, 0.510, 0.586, 0.785, 0.490, 0.584, 0.779, 0.470, 0.581,
+     0.773, 0.450, 0.579, 0.766, 0.429, 0.576, 0.760, 0.408, 0.574, 0.753,
+     0.387, 0.572, 0.746, 0.366, 0.569, 0.739, 0.344, 0.567, 0.732, 0.322,
+     0.565, 0.725, 0.299, 0.563, 0.717, 0.276, 0.561, 0.710, 0.252, 0.559,
+     0.703, 0.227, 0.557, 0.695, 0.201, 0.329, 0.685, 0.970, 0.346, 0.692,
+     0.964, 0.362, 0.699, 0.958, 0.377, 0.707, 0.952, 0.392, 0.714, 0.946,
+     0.406, 0.721, 0.941, 0.420, 0.728, 0.935, 0.434, 0.735, 0.930, 0.447,
+     0.742, 0.925, 0.460, 0.749, 0.920, 0.473, 0.756, 0.916, 0.485, 0.762,
+     0.911, 0.497, 0.769, 0.907, 0.509, 0.775, 0.903, 0.521, 0.781, 0.898,
+     0.532, 0.788, 0.894, 0.542, 0.794, 0.890, 0.553, 0.799, 0.886, 0.563,
+     0.805, 0.882, 0.572, 0.811, 0.877, 0.581, 0.816, 0.873, 0.590, 0.821,
+     0.868, 0.598, 0.826, 0.864, 0.606, 0.830, 0.859, 0.613, 0.834, 0.854,
+     0.619, 0.838, 0.848, 0.625, 0.842, 0.842, 0.630, 0.845, 0.836, 0.634,
+     0.848, 0.829, 0.638, 0.850, 0.822, 0.641, 0.852, 0.814, 0.643, 0.853,
+     0.805, 0.645, 0.854, 0.796, 0.645, 0.854, 0.786, 0.646, 0.854, 0.775,
+     0.645, 0.853, 0.764, 0.645, 0.852, 0.751, 0.643, 0.851, 0.738, 0.642,
+     0.848, 0.725, 0.639, 0.846, 0.710, 0.637, 0.843, 0.695, 0.635, 0.839,
+     0.679, 0.632, 0.836, 0.662, 0.629, 0.831, 0.645, 0.626, 0.827, 0.628,
+     0.623, 0.822, 0.610, 0.620, 0.817, 0.592, 0.617, 0.811, 0.573, 0.614,
+     0.806, 0.554, 0.611, 0.800, 0.534, 0.608, 0.794, 0.515, 0.605, 0.788,
+     0.495, 0.602, 0.781, 0.474, 0.599, 0.775, 0.454, 0.597, 0.768, 0.433,
+     0.594, 0.761, 0.412, 0.592, 0.754, 0.391, 0.589, 0.747, 0.369, 0.587,
+     0.740, 0.347, 0.584, 0.733, 0.325, 0.582, 0.725, 0.302, 0.580, 0.718,
+     0.279, 0.577, 0.710, 0.255, 0.575, 0.703, 0.230, 0.573, 0.695, 0.204,
+     0.357, 0.685, 0.972, 0.372, 0.692, 0.966, 0.387, 0.700, 0.960, 0.401,
+     0.707, 0.954, 0.416, 0.714, 0.949, 0.429, 0.722, 0.943, 0.443, 0.729,
+     0.938, 0.456, 0.736, 0.933, 0.469, 0.743, 0.929, 0.482, 0.750, 0.924,
+     0.494, 0.757, 0.919, 0.507, 0.764, 0.915, 0.519, 0.771, 0.911, 0.530,
+     0.777, 0.907, 0.542, 0.784, 0.903, 0.553, 0.790, 0.899, 0.563, 0.796,
+     0.895, 0.574, 0.802, 0.891, 0.584, 0.808, 0.887, 0.593, 0.814, 0.883,
+     0.603, 0.820, 0.879, 0.611, 0.825, 0.875, 0.620, 0.830, 0.870, 0.627,
+     0.835, 0.866, 0.635, 0.839, 0.861, 0.641, 0.843, 0.856, 0.647, 0.847,
+     0.850, 0.652, 0.850, 0.844, 0.657, 0.853, 0.838, 0.660, 0.855, 0.831,
+     0.663, 0.857, 0.823, 0.666, 0.859, 0.814, 0.667, 0.859, 0.805, 0.668,
+     0.860, 0.795, 0.668, 0.860, 0.784, 0.667, 0.859, 0.773, 0.666, 0.858,
+     0.760, 0.665, 0.856, 0.747, 0.663, 0.853, 0.733, 0.661, 0.851, 0.718,
+     0.658, 0.847, 0.703, 0.655, 0.844, 0.687, 0.652, 0.840, 0.670, 0.649,
+     0.835, 0.652, 0.646, 0.830, 0.635, 0.642, 0.825, 0.616, 0.639, 0.820,
+     0.598, 0.636, 0.814, 0.579, 0.633, 0.808, 0.559, 0.629, 0.802, 0.539,
+     0.626, 0.796, 0.519, 0.623, 0.790, 0.499, 0.620, 0.783, 0.479, 0.617,
+     0.776, 0.458, 0.614, 0.769, 0.437, 0.611, 0.762, 0.416, 0.609, 0.755,
+     0.394, 0.606, 0.748, 0.372, 0.603, 0.740, 0.350, 0.601, 0.733, 0.328,
+     0.598, 0.726, 0.305, 0.596, 0.718, 0.282, 0.593, 0.710, 0.257, 0.591,
+     0.703, 0.232, 0.589, 0.695, 0.206, 0.381, 0.684, 0.974, 0.396, 0.692,
+     0.968, 0.410, 0.700, 0.962, 0.424, 0.707, 0.957, 0.438, 0.715, 0.951,
+     0.451, 0.722, 0.946, 0.464, 0.729, 0.941, 0.477, 0.737, 0.936, 0.490,
+     0.744, 0.932, 0.503, 0.751, 0.927, 0.515, 0.758, 0.923, 0.527, 0.765,
+     0.919, 0.539, 0.772, 0.915, 0.550, 0.779, 0.911, 0.562, 0.786, 0.907,
+     0.573, 0.792, 0.903, 0.584, 0.799, 0.900, 0.594, 0.805, 0.896, 0.604,
+     0.811, 0.892, 0.614, 0.817, 0.889, 0.623, 0.823, 0.885, 0.632, 0.829,
+     0.881, 0.641, 0.834, 0.877, 0.649, 0.839, 0.873, 0.656, 0.844, 0.868,
+     0.663, 0.848, 0.863, 0.669, 0.852, 0.858, 0.674, 0.855, 0.852, 0.679,
+     0.858, 0.846, 0.682, 0.861, 0.839, 0.685, 0.863, 0.832, 0.688, 0.864,
+     0.823, 0.689, 0.865, 0.814, 0.690, 0.865, 0.804, 0.690, 0.865, 0.794,
+     0.689, 0.864, 0.782, 0.688, 0.863, 0.769, 0.686, 0.861, 0.756, 0.684,
+     0.858, 0.742, 0.681, 0.855, 0.726, 0.678, 0.852, 0.711, 0.675, 0.848,
+     0.694, 0.672, 0.844, 0.677, 0.668, 0.839, 0.659, 0.665, 0.834, 0.641,
+     0.662, 0.829, 0.622, 0.658, 0.823, 0.603, 0.655, 0.817, 0.584, 0.651,
+     0.811, 0.564, 0.648, 0.805, 0.544, 0.644, 0.798, 0.524, 0.641, 0.791,
+     0.503, 0.638, 0.785, 0.483, 0.635, 0.778, 0.462, 0.631, 0.770, 0.440,
+     0.628, 0.763, 0.419, 0.625, 0.756, 0.397, 0.623, 0.748, 0.375, 0.620,
+     0.741, 0.353, 0.617, 0.733, 0.330, 0.614, 0.726, 0.307, 0.612, 0.718,
+     0.284, 0.609, 0.710, 0.260, 0.606, 0.702, 0.235, 0.604, 0.694, 0.208,
+     0.404, 0.684, 0.977, 0.418, 0.692, 0.971, 0.432, 0.699, 0.965, 0.445,
+     0.707, 0.959, 0.458, 0.715, 0.954, 0.472, 0.722, 0.949, 0.484, 0.730,
+     0.944, 0.497, 0.737, 0.939, 0.510, 0.745, 0.935, 0.522, 0.752, 0.931,
+     0.534, 0.759, 0.926, 0.546, 0.767, 0.922, 0.558, 0.774, 0.919, 0.569,
+     0.781, 0.915, 0.581, 0.788, 0.911, 0.592, 0.794, 0.908, 0.603, 0.801,
+     0.904, 0.613, 0.808, 0.901, 0.624, 0.814, 0.897, 0.633, 0.820, 0.894,
+     0.643, 0.826, 0.891, 0.652, 0.832, 0.887, 0.661, 0.838, 0.883, 0.669,
+     0.843, 0.879, 0.677, 0.848, 0.875, 0.684, 0.853, 0.871, 0.690, 0.857,
+     0.866, 0.695, 0.860, 0.860, 0.700, 0.864, 0.855, 0.704, 0.866, 0.848,
+     0.707, 0.869, 0.841, 0.709, 0.870, 0.833, 0.711, 0.871, 0.824, 0.711,
+     0.871, 0.814, 0.711, 0.871, 0.803, 0.710, 0.870, 0.791, 0.709, 0.868,
+     0.778, 0.707, 0.866, 0.765, 0.704, 0.864, 0.750, 0.701, 0.860, 0.735,
+     0.698, 0.857, 0.718, 0.695, 0.852, 0.702, 0.691, 0.848, 0.684, 0.688,
+     0.843, 0.666, 0.684, 0.837, 0.647, 0.680, 0.832, 0.628, 0.676, 0.826,
+     0.609, 0.673, 0.820, 0.589, 0.669, 0.813, 0.569, 0.665, 0.807, 0.549,
+     0.662, 0.800, 0.528, 0.658, 0.793, 0.507, 0.655, 0.786, 0.486, 0.651,
+     0.779, 0.465, 0.648, 0.771, 0.444, 0.645, 0.764, 0.422, 0.642, 0.756,
+     0.400, 0.639, 0.749, 0.378, 0.636, 0.741, 0.356, 0.633, 0.733, 0.333,
+     0.630, 0.726, 0.310, 0.627, 0.718, 0.286, 0.624, 0.710, 0.262, 0.621,
+     0.702, 0.237, 0.619, 0.694, 0.210, 0.425, 0.683, 0.979, 0.439, 0.691,
+     0.973, 0.452, 0.699, 0.967, 0.465, 0.707, 0.962, 0.478, 0.715, 0.956,
+     0.491, 0.722, 0.951, 0.503, 0.730, 0.947, 0.516, 0.738, 0.942, 0.528,
+     0.745, 0.938, 0.540, 0.753, 0.934, 0.552, 0.760, 0.930, 0.564, 0.768,
+     0.926, 0.576, 0.775, 0.922, 0.588, 0.782, 0.919, 0.599, 0.789, 0.915,
+     0.610, 0.797, 0.912, 0.621, 0.803, 0.909, 0.632, 0.810, 0.906, 0.642,
+     0.817, 0.902, 0.652, 0.823, 0.899, 0.662, 0.830, 0.896, 0.671, 0.836,
+     0.893, 0.680, 0.842, 0.890, 0.689, 0.847, 0.886, 0.697, 0.853, 0.882,
+     0.704, 0.857, 0.878, 0.710, 0.862, 0.874, 0.716, 0.866, 0.869, 0.721,
+     0.869, 0.863, 0.725, 0.872, 0.857, 0.729, 0.874, 0.850, 0.731, 0.876,
+     0.842, 0.732, 0.877, 0.833, 0.733, 0.877, 0.823, 0.732, 0.877, 0.812,
+     0.731, 0.876, 0.800, 0.729, 0.874, 0.787, 0.727, 0.872, 0.773, 0.724,
+     0.869, 0.759, 0.721, 0.865, 0.743, 0.718, 0.861, 0.726, 0.714, 0.857,
+     0.709, 0.710, 0.852, 0.691, 0.706, 0.846, 0.672, 0.702, 0.841, 0.653,
+     0.698, 0.835, 0.634, 0.694, 0.828, 0.614, 0.690, 0.822, 0.594, 0.686,
+     0.815, 0.574, 0.683, 0.808, 0.553, 0.679, 0.801, 0.532, 0.675, 0.794,
+     0.511, 0.672, 0.787, 0.490, 0.668, 0.779, 0.468, 0.665, 0.772, 0.446,
+     0.661, 0.764, 0.425, 0.658, 0.757, 0.403, 0.654, 0.749, 0.380, 0.651,
+     0.741, 0.358, 0.648, 0.733, 0.335, 0.645, 0.725, 0.312, 0.642, 0.717,
+     0.288, 0.639, 0.709, 0.264, 0.636, 0.701, 0.238, 0.633, 0.693, 0.212,
+     0.445, 0.682, 0.981, 0.458, 0.691, 0.975, 0.471, 0.699, 0.969, 0.484,
+     0.707, 0.964, 0.496, 0.715, 0.959, 0.509, 0.722, 0.954, 0.521, 0.730,
+     0.949, 0.534, 0.738, 0.945, 0.546, 0.746, 0.941, 0.558, 0.753, 0.937,
+     0.570, 0.761, 0.933, 0.582, 0.769, 0.929, 0.593, 0.776, 0.926, 0.605,
+     0.784, 0.922, 0.616, 0.791, 0.919, 0.628, 0.798, 0.916, 0.639, 0.806,
+     0.913, 0.649, 0.813, 0.910, 0.660, 0.820, 0.907, 0.670, 0.826, 0.904,
+     0.680, 0.833, 0.902, 0.690, 0.839, 0.899, 0.699, 0.846, 0.896, 0.708,
+     0.851, 0.893, 0.716, 0.857, 0.889, 0.724, 0.862, 0.885, 0.731, 0.867,
+     0.881, 0.737, 0.871, 0.877, 0.742, 0.875, 0.872, 0.746, 0.878, 0.866,
+     0.750, 0.880, 0.859, 0.752, 0.882, 0.851, 0.753, 0.883, 0.843, 0.754,
+     0.883, 0.833, 0.753, 0.883, 0.822, 0.752, 0.882, 0.810, 0.750, 0.880,
+     0.797, 0.747, 0.877, 0.782, 0.744, 0.874, 0.767, 0.740, 0.870, 0.751,
+     0.737, 0.866, 0.734, 0.733, 0.861, 0.716, 0.729, 0.855, 0.697, 0.724,
+     0.850, 0.678, 0.720, 0.844, 0.659, 0.716, 0.837, 0.639, 0.712, 0.831,
+     0.619, 0.708, 0.824, 0.598, 0.704, 0.817, 0.578, 0.699, 0.810, 0.557,
+     0.696, 0.803, 0.535, 0.692, 0.795, 0.514, 0.688, 0.788, 0.493, 0.684,
+     0.780, 0.471, 0.680, 0.772, 0.449, 0.677, 0.765, 0.427, 0.673, 0.757,
+     0.405, 0.670, 0.749, 0.382, 0.666, 0.741, 0.360, 0.663, 0.733, 0.337,
+     0.660, 0.725, 0.313, 0.657, 0.716, 0.289, 0.653, 0.708, 0.265, 0.650,
+     0.700, 0.240, 0.647, 0.692, 0.213, 0.464, 0.681, 0.982, 0.476, 0.690,
+     0.977, 0.489, 0.698, 0.971, 0.501, 0.706, 0.966, 0.514, 0.714, 0.961,
+     0.526, 0.722, 0.956, 0.538, 0.730, 0.952, 0.550, 0.738, 0.947, 0.562,
+     0.746, 0.943, 0.574, 0.754, 0.939, 0.586, 0.762, 0.936, 0.598, 0.769,
+     0.932, 0.610, 0.777, 0.929, 0.621, 0.785, 0.926, 0.633, 0.792, 0.923,
+     0.644, 0.800, 0.920, 0.655, 0.807, 0.917, 0.666, 0.815, 0.915, 0.677,
+     0.822, 0.912, 0.688, 0.829, 0.909, 0.698, 0.836, 0.907, 0.708, 0.843,
+     0.904, 0.717, 0.849, 0.902, 0.727, 0.855, 0.899, 0.735, 0.861, 0.896,
+     0.743, 0.867, 0.893, 0.750, 0.872, 0.889, 0.757, 0.877, 0.885, 0.762,
+     0.881, 0.880, 0.767, 0.884, 0.875, 0.770, 0.887, 0.868, 0.773, 0.888,
+     0.861, 0.774, 0.889, 0.852, 0.774, 0.890, 0.842, 0.774, 0.889, 0.831,
+     0.772, 0.888, 0.819, 0.770, 0.885, 0.806, 0.767, 0.883, 0.791, 0.763,
+     0.879, 0.775, 0.759, 0.875, 0.759, 0.755, 0.870, 0.741, 0.751, 0.865,
+     0.723, 0.747, 0.859, 0.704, 0.742, 0.853, 0.684, 0.738, 0.847, 0.664,
+     0.733, 0.840, 0.644, 0.729, 0.833, 0.623, 0.724, 0.826, 0.603, 0.720,
+     0.819, 0.581, 0.716, 0.811, 0.560, 0.712, 0.804, 0.539, 0.708, 0.796,
+     0.517, 0.704, 0.788, 0.495, 0.700, 0.780, 0.473, 0.696, 0.772, 0.451,
+     0.692, 0.764, 0.429, 0.688, 0.756, 0.407, 0.685, 0.748, 0.384, 0.681,
+     0.740, 0.361, 0.678, 0.732, 0.338, 0.674, 0.724, 0.315, 0.671, 0.715,
+     0.291, 0.667, 0.707, 0.266, 0.664, 0.699, 0.241, 0.661, 0.691, 0.214,
+     0.481, 0.680, 0.984, 0.494, 0.689, 0.978, 0.506, 0.697, 0.973, 0.518,
+     0.705, 0.968, 0.530, 0.713, 0.963, 0.542, 0.722, 0.958, 0.554, 0.730,
+     0.954, 0.566, 0.738, 0.950, 0.578, 0.746, 0.946, 0.590, 0.754, 0.942,
+     0.602, 0.762, 0.939, 0.614, 0.770, 0.935, 0.626, 0.778, 0.932, 0.637,
+     0.786, 0.929, 0.649, 0.794, 0.926, 0.660, 0.801, 0.924, 0.671, 0.809,
+     0.921, 0.683, 0.817, 0.919, 0.694, 0.824, 0.916, 0.704, 0.832, 0.914,
+     0.715, 0.839, 0.912, 0.725, 0.846, 0.910, 0.735, 0.853, 0.908, 0.744,
+     0.859, 0.905, 0.753, 0.866, 0.903, 0.762, 0.872, 0.900, 0.770, 0.877,
+     0.897, 0.776, 0.882, 0.893, 0.782, 0.886, 0.889, 0.787, 0.890, 0.884,
+     0.791, 0.893, 0.878, 0.794, 0.895, 0.871, 0.795, 0.896, 0.862, 0.795,
+     0.896, 0.852, 0.794, 0.895, 0.841, 0.792, 0.894, 0.829, 0.789, 0.891,
+     0.815, 0.786, 0.888, 0.800, 0.782, 0.884, 0.783, 0.778, 0.879, 0.766,
+     0.774, 0.874, 0.748, 0.769, 0.868, 0.729, 0.764, 0.862, 0.710, 0.760,
+     0.856, 0.690, 0.755, 0.849, 0.669, 0.750, 0.842, 0.649, 0.745, 0.835,
+     0.628, 0.741, 0.827, 0.606, 0.736, 0.820, 0.585, 0.732, 0.812, 0.563,
+     0.728, 0.804, 0.542, 0.723, 0.796, 0.520, 0.719, 0.788, 0.498, 0.715,
+     0.780, 0.475, 0.711, 0.772, 0.453, 0.707, 0.764, 0.431, 0.703, 0.756,
+     0.408, 0.699, 0.748, 0.386, 0.696, 0.739, 0.363, 0.692, 0.731, 0.339,
+     0.688, 0.723, 0.316, 0.685, 0.714, 0.292, 0.681, 0.706, 0.267, 0.678,
+     0.697, 0.242, 0.674, 0.689, 0.215, 0.498, 0.679, 0.986, 0.510, 0.687,
+     0.980, 0.522, 0.696, 0.975, 0.534, 0.704, 0.970, 0.546, 0.712, 0.965,
+     0.558, 0.721, 0.961, 0.570, 0.729, 0.956, 0.581, 0.737, 0.952, 0.593,
+     0.746, 0.948, 0.605, 0.754, 0.945, 0.617, 0.762, 0.941, 0.629, 0.770,
+     0.938, 0.640, 0.778, 0.935, 0.652, 0.786, 0.932, 0.664, 0.794, 0.930,
+     0.675, 0.802, 0.927, 0.687, 0.810, 0.925, 0.698, 0.818, 0.923, 0.709,
+     0.826, 0.921, 0.720, 0.834, 0.919, 0.731, 0.841, 0.917, 0.742, 0.849,
+     0.915, 0.752, 0.856, 0.913, 0.762, 0.863, 0.911, 0.771, 0.870, 0.909,
+     0.780, 0.876, 0.907, 0.788, 0.882, 0.904, 0.796, 0.887, 0.901, 0.802,
+     0.892, 0.897, 0.807, 0.896, 0.893, 0.811, 0.899, 0.887, 0.814, 0.902,
+     0.880, 0.815, 0.903, 0.872, 0.815, 0.903, 0.862, 0.814, 0.902, 0.851,
+     0.812, 0.900, 0.838, 0.809, 0.897, 0.824, 0.805, 0.893, 0.808, 0.801,
+     0.889, 0.791, 0.796, 0.884, 0.774, 0.791, 0.878, 0.755, 0.786, 0.872,
+     0.735, 0.781, 0.865, 0.715, 0.776, 0.858, 0.695, 0.771, 0.851, 0.674,
+     0.767, 0.844, 0.653, 0.762, 0.836, 0.631, 0.757, 0.829, 0.610, 0.752,
+     0.821, 0.588, 0.748, 0.813, 0.566, 0.743, 0.805, 0.544, 0.739, 0.796,
+     0.522, 0.734, 0.788, 0.500, 0.730, 0.780, 0.477, 0.726, 0.772, 0.455,
+     0.722, 0.763, 0.432, 0.718, 0.755, 0.410, 0.714, 0.746, 0.387, 0.710,
+     0.738, 0.364, 0.706, 0.730, 0.340, 0.702, 0.721, 0.317, 0.698, 0.713,
+     0.293, 0.694, 0.704, 0.268, 0.691, 0.696, 0.243, 0.687, 0.687, 0.216,
+     0.513, 0.677, 0.987, 0.525, 0.686, 0.982, 0.537, 0.694, 0.977, 0.549,
+     0.703, 0.972, 0.561, 0.711, 0.967, 0.572, 0.720, 0.962, 0.584, 0.728,
+     0.958, 0.596, 0.737, 0.954, 0.608, 0.745, 0.951, 0.619, 0.753, 0.947,
+     0.631, 0.762, 0.944, 0.643, 0.770, 0.941, 0.655, 0.778, 0.938, 0.666,
+     0.787, 0.935, 0.678, 0.795, 0.933, 0.689, 0.803, 0.930, 0.701, 0.811,
+     0.928, 0.713, 0.820, 0.926, 0.724, 0.828, 0.925, 0.735, 0.836, 0.923,
+     0.746, 0.844, 0.921, 0.757, 0.852, 0.920, 0.768, 0.859, 0.918, 0.778,
+     0.867, 0.917, 0.788, 0.874, 0.915, 0.797, 0.881, 0.913, 0.806, 0.887,
+     0.911, 0.814, 0.893, 0.909, 0.821, 0.898, 0.906, 0.827, 0.902, 0.902,
+     0.831, 0.906, 0.897, 0.834, 0.908, 0.890, 0.836, 0.910, 0.882, 0.836,
+     0.910, 0.873, 0.834, 0.909, 0.861, 0.832, 0.906, 0.848, 0.828, 0.903,
+     0.833, 0.824, 0.899, 0.817, 0.819, 0.894, 0.799, 0.814, 0.888, 0.781,
+     0.809, 0.882, 0.761, 0.804, 0.875, 0.741, 0.798, 0.868, 0.720, 0.793,
+     0.861, 0.699, 0.788, 0.853, 0.678, 0.783, 0.845, 0.656, 0.777, 0.837,
+     0.635, 0.772, 0.829, 0.613, 0.768, 0.821, 0.590, 0.763, 0.813, 0.568,
+     0.758, 0.804, 0.546, 0.753, 0.796, 0.524, 0.749, 0.788, 0.501, 0.744,
+     0.779, 0.479, 0.740, 0.771, 0.456, 0.736, 0.762, 0.433, 0.731, 0.754,
+     0.411, 0.727, 0.745, 0.388, 0.723, 0.736, 0.365, 0.719, 0.728, 0.341,
+     0.715, 0.719, 0.317, 0.711, 0.711, 0.293, 0.707, 0.702, 0.268, 0.704,
+     0.694, 0.243, 0.700, 0.685, 0.216, 0.528, 0.675, 0.989, 0.540, 0.684,
+     0.983, 0.551, 0.693, 0.978, 0.563, 0.701, 0.973, 0.575, 0.710, 0.969,
+     0.586, 0.718, 0.964, 0.598, 0.727, 0.960, 0.610, 0.736, 0.956, 0.621,
+     0.744, 0.953, 0.633, 0.753, 0.949, 0.645, 0.761, 0.946, 0.656, 0.770,
+     0.943, 0.668, 0.778, 0.940, 0.680, 0.787, 0.938, 0.691, 0.795, 0.936,
+     0.703, 0.804, 0.933, 0.715, 0.812, 0.932, 0.726, 0.821, 0.930, 0.738,
+     0.829, 0.928, 0.749, 0.837, 0.927, 0.761, 0.846, 0.926, 0.772, 0.854,
+     0.924, 0.783, 0.862, 0.923, 0.794, 0.870, 0.922, 0.804, 0.877, 0.921,
+     0.814, 0.885, 0.920, 0.824, 0.892, 0.918, 0.832, 0.898, 0.917, 0.840,
+     0.904, 0.914, 0.846, 0.909, 0.911, 0.851, 0.913, 0.906, 0.855, 0.915,
+     0.901, 0.856, 0.917, 0.893, 0.856, 0.917, 0.883, 0.854, 0.915, 0.871,
+     0.851, 0.913, 0.858, 0.847, 0.909, 0.842, 0.842, 0.904, 0.825, 0.837,
+     0.898, 0.806, 0.831, 0.892, 0.787, 0.826, 0.885, 0.767, 0.820, 0.878,
+     0.746, 0.814, 0.870, 0.725, 0.809, 0.862, 0.703, 0.803, 0.854, 0.681,
+     0.798, 0.846, 0.659, 0.793, 0.838, 0.637, 0.788, 0.829, 0.615, 0.782,
+     0.821, 0.592, 0.777, 0.812, 0.570, 0.773, 0.804, 0.548, 0.768, 0.795,
+     0.525, 0.763, 0.787, 0.502, 0.758, 0.778, 0.480, 0.754, 0.769, 0.457,
+     0.749, 0.761, 0.434, 0.745, 0.752, 0.411, 0.741, 0.743, 0.388, 0.737,
+     0.735, 0.365, 0.732, 0.726, 0.342, 0.728, 0.717, 0.318, 0.724, 0.709,
+     0.293, 0.720, 0.700, 0.269, 0.716, 0.691, 0.243, 0.712, 0.683, 0.216,
+     0.542, 0.673, 0.990, 0.554, 0.682, 0.985, 0.565, 0.691, 0.980, 0.577,
+     0.700, 0.975, 0.588, 0.708, 0.970, 0.600, 0.717, 0.966, 0.611, 0.726,
+     0.962, 0.623, 0.734, 0.958, 0.634, 0.743, 0.955, 0.646, 0.752, 0.951,
+     0.657, 0.760, 0.948, 0.669, 0.769, 0.945, 0.681, 0.778, 0.943, 0.692,
+     0.786, 0.940, 0.704, 0.795, 0.938, 0.716, 0.804, 0.936, 0.728, 0.812,
+     0.934, 0.739, 0.821, 0.933, 0.751, 0.830, 0.932, 0.763, 0.838, 0.930,
+     0.774, 0.847, 0.929, 0.786, 0.856, 0.929, 0.797, 0.864, 0.928, 0.809,
+     0.873, 0.927, 0.819, 0.881, 0.927, 0.830, 0.889, 0.926, 0.840, 0.896,
+     0.925, 0.850, 0.903, 0.924, 0.858, 0.910, 0.922, 0.865, 0.915, 0.920,
+     0.871, 0.920, 0.916, 0.875, 0.923, 0.911, 0.876, 0.924, 0.903, 0.876,
+     0.924, 0.894, 0.873, 0.922, 0.882, 0.870, 0.919, 0.867, 0.865, 0.914,
+     0.851, 0.860, 0.909, 0.832, 0.854, 0.902, 0.813, 0.848, 0.895, 0.793,
+     0.842, 0.888, 0.772, 0.836, 0.880, 0.750, 0.830, 0.872, 0.729, 0.824,
+     0.864, 0.707, 0.819, 0.855, 0.684, 0.813, 0.847, 0.662, 0.808, 0.838,
+     0.639, 0.802, 0.829, 0.617, 0.797, 0.820, 0.594, 0.792, 0.812, 0.571,
+     0.787, 0.803, 0.549, 0.782, 0.794, 0.526, 0.777, 0.785, 0.503, 0.772,
+     0.776, 0.480, 0.767, 0.768, 0.458, 0.763, 0.759, 0.435, 0.758, 0.750,
+     0.412, 0.754, 0.741, 0.388, 0.749, 0.732, 0.365, 0.745, 0.724, 0.342,
+     0.741, 0.715, 0.318, 0.737, 0.706, 0.293, 0.732, 0.697, 0.269, 0.728,
+     0.689, 0.243, 0.724, 0.680, 0.216, 0.556, 0.671, 0.992, 0.567, 0.680,
+     0.986, 0.578, 0.689, 0.981, 0.590, 0.697, 0.976, 0.601, 0.706, 0.972,
+     0.612, 0.715, 0.968, 0.624, 0.724, 0.964, 0.635, 0.733, 0.960, 0.646,
+     0.741, 0.956, 0.658, 0.750, 0.953, 0.670, 0.759, 0.950, 0.681, 0.768,
+     0.947, 0.693, 0.777, 0.945, 0.704, 0.786, 0.943, 0.716, 0.794, 0.941,
+     0.728, 0.803, 0.939, 0.740, 0.812, 0.937, 0.752, 0.821, 0.936, 0.763,
+     0.830, 0.935, 0.775, 0.839, 0.934, 0.787, 0.848, 0.933, 0.799, 0.857,
+     0.932, 0.811, 0.866, 0.932, 0.822, 0.875, 0.932, 0.834, 0.883, 0.932,
+     0.845, 0.892, 0.931, 0.856, 0.900, 0.931, 0.866, 0.908, 0.931, 0.876,
+     0.915, 0.930, 0.884, 0.922, 0.929, 0.890, 0.927, 0.926, 0.895, 0.930,
+     0.921, 0.896, 0.932, 0.914, 0.896, 0.932, 0.905, 0.893, 0.929, 0.892,
+     0.888, 0.925, 0.876, 0.883, 0.920, 0.859, 0.877, 0.913, 0.840, 0.871,
+     0.906, 0.819, 0.864, 0.898, 0.798, 0.858, 0.890, 0.776, 0.852, 0.882,
+     0.754, 0.845, 0.873, 0.732, 0.839, 0.864, 0.709, 0.833, 0.855, 0.686,
+     0.828, 0.846, 0.664, 0.822, 0.837, 0.641, 0.816, 0.828, 0.618, 0.811,
+     0.819, 0.595, 0.806, 0.810, 0.572, 0.800, 0.801, 0.549, 0.795, 0.792,
+     0.526, 0.790, 0.783, 0.504, 0.785, 0.774, 0.481, 0.781, 0.765, 0.458,
+     0.776, 0.756, 0.435, 0.771, 0.748, 0.412, 0.766, 0.739, 0.388, 0.762,
+     0.730, 0.365, 0.757, 0.721, 0.341, 0.753, 0.712, 0.318, 0.749, 0.703,
+     0.293, 0.744, 0.695, 0.268, 0.740, 0.686, 0.243, 0.736, 0.677, 0.216,
+     0.569, 0.668, 0.993, 0.580, 0.677, 0.987, 0.591, 0.686, 0.982, 0.602,
+     0.695, 0.978, 0.613, 0.704, 0.973, 0.624, 0.713, 0.969, 0.635, 0.722,
+     0.965, 0.647, 0.731, 0.961, 0.658, 0.740, 0.958, 0.670, 0.748, 0.955,
+     0.681, 0.757, 0.952, 0.693, 0.766, 0.949, 0.704, 0.775, 0.947, 0.716,
+     0.784, 0.945, 0.728, 0.793, 0.943, 0.739, 0.802, 0.941, 0.751, 0.812,
+     0.939, 0.763, 0.821, 0.938, 0.775, 0.830, 0.937, 0.787, 0.839, 0.936,
+     0.799, 0.848, 0.936, 0.811, 0.858, 0.936, 0.823, 0.867, 0.935, 0.835,
+     0.876, 0.936, 0.847, 0.886, 0.936, 0.859, 0.895, 0.936, 0.870, 0.904,
+     0.937, 0.882, 0.912, 0.937, 0.892, 0.920, 0.937, 0.901, 0.928, 0.937,
+     0.909, 0.934, 0.936, 0.914, 0.938, 0.932, 0.917, 0.940, 0.926, 0.915,
+     0.940, 0.916, 0.912, 0.936, 0.902, 0.906, 0.931, 0.885, 0.900, 0.925,
+     0.866, 0.893, 0.917, 0.846, 0.887, 0.909, 0.824, 0.880, 0.900, 0.802,
+     0.873, 0.891, 0.780, 0.867, 0.882, 0.757, 0.860, 0.873, 0.734, 0.854,
+     0.864, 0.711, 0.848, 0.855, 0.688, 0.842, 0.845, 0.665, 0.836, 0.836,
+     0.642, 0.830, 0.827, 0.619, 0.824, 0.818, 0.596, 0.819, 0.808, 0.573,
+     0.814, 0.799, 0.549, 0.808, 0.790, 0.527, 0.803, 0.781, 0.504, 0.798,
+     0.772, 0.481, 0.793, 0.763, 0.458, 0.788, 0.754, 0.434, 0.783, 0.745,
+     0.411, 0.779, 0.736, 0.388, 0.774, 0.727, 0.365, 0.769, 0.718, 0.341,
+     0.765, 0.709, 0.317, 0.760, 0.700, 0.293, 0.756, 0.691, 0.268, 0.751,
+     0.683, 0.242, 0.747, 0.674, 0.215, 0.581, 0.665, 0.994, 0.592, 0.674,
+     0.989, 0.603, 0.683, 0.984, 0.614, 0.692, 0.979, 0.625, 0.701, 0.974,
+     0.636, 0.710, 0.970, 0.647, 0.719, 0.966, 0.658, 0.728, 0.963, 0.669,
+     0.737, 0.959, 0.681, 0.746, 0.956, 0.692, 0.755, 0.953, 0.703, 0.765,
+     0.951, 0.715, 0.774, 0.948, 0.727, 0.783, 0.946, 0.738, 0.792, 0.944,
+     0.750, 0.801, 0.943, 0.762, 0.810, 0.941, 0.774, 0.820, 0.940, 0.786,
+     0.829, 0.939, 0.798, 0.839, 0.939, 0.810, 0.848, 0.938, 0.822, 0.858,
+     0.938, 0.834, 0.867, 0.939, 0.847, 0.877, 0.939, 0.859, 0.887, 0.940,
+     0.871, 0.897, 0.940, 0.883, 0.906, 0.942, 0.896, 0.916, 0.943, 0.907,
+     0.925, 0.944, 0.918, 0.933, 0.945, 0.927, 0.941, 0.945, 0.934, 0.946,
+     0.943, 0.937, 0.949, 0.937, 0.935, 0.948, 0.927, 0.930, 0.943, 0.912,
+     0.924, 0.937, 0.893, 0.916, 0.929, 0.872, 0.909, 0.920, 0.850, 0.902,
+     0.911, 0.828, 0.895, 0.901, 0.805, 0.888, 0.892, 0.782, 0.881, 0.882,
+     0.759, 0.874, 0.872, 0.735, 0.868, 0.863, 0.712, 0.861, 0.853, 0.689,
+     0.855, 0.844, 0.665, 0.849, 0.834, 0.642, 0.843, 0.825, 0.619, 0.838,
+     0.815, 0.596, 0.832, 0.806, 0.572, 0.826, 0.797, 0.549, 0.821, 0.787,
+     0.526, 0.816, 0.778, 0.503, 0.811, 0.769, 0.480, 0.805, 0.760, 0.457,
+     0.800, 0.751, 0.434, 0.795, 0.742, 0.411, 0.791, 0.733, 0.387, 0.786,
+     0.724, 0.364, 0.781, 0.715, 0.340, 0.776, 0.706, 0.316, 0.772, 0.697,
+     0.292, 0.767, 0.688, 0.267, 0.762, 0.679, 0.241, 0.758, 0.670, 0.215,
+     0.593, 0.662, 0.995, 0.603, 0.671, 0.990, 0.614, 0.680, 0.985, 0.625,
+     0.689, 0.980, 0.636, 0.699, 0.975, 0.647, 0.708, 0.971, 0.658, 0.717,
+     0.967, 0.669, 0.726, 0.964, 0.680, 0.735, 0.960, 0.691, 0.744, 0.957,
+     0.702, 0.753, 0.955, 0.714, 0.762, 0.952, 0.725, 0.771, 0.950, 0.737,
+     0.781, 0.948, 0.748, 0.790, 0.946, 0.760, 0.799, 0.944, 0.772, 0.809,
+     0.943, 0.784, 0.818, 0.942, 0.796, 0.828, 0.941, 0.808, 0.837, 0.941,
+     0.820, 0.847, 0.940, 0.832, 0.857, 0.941, 0.844, 0.867, 0.941, 0.857,
+     0.877, 0.942, 0.869, 0.887, 0.943, 0.882, 0.897, 0.944, 0.895, 0.908,
+     0.945, 0.908, 0.918, 0.947, 0.920, 0.928, 0.949, 0.933, 0.938, 0.951,
+     0.944, 0.947, 0.953, 0.953, 0.955, 0.954, 0.957, 0.958, 0.950, 0.954,
+     0.956, 0.938, 0.948, 0.949, 0.920, 0.940, 0.941, 0.899, 0.932, 0.931,
+     0.877, 0.924, 0.921, 0.854, 0.916, 0.911, 0.830, 0.909, 0.901, 0.807,
+     0.901, 0.891, 0.783, 0.894, 0.881, 0.759, 0.887, 0.871, 0.736, 0.881,
+     0.861, 0.712, 0.874, 0.851, 0.688, 0.868, 0.841, 0.665, 0.862, 0.832,
+     0.642, 0.856, 0.822, 0.618, 0.850, 0.812, 0.595, 0.844, 0.803, 0.572,
+     0.839, 0.793, 0.549, 0.833, 0.784, 0.525, 0.828, 0.775, 0.502, 0.822,
+     0.766, 0.479, 0.817, 0.756, 0.456, 0.812, 0.747, 0.433, 0.807, 0.738,
+     0.410, 0.802, 0.729, 0.387, 0.797, 0.720, 0.363, 0.792, 0.711, 0.339,
+     0.787, 0.702, 0.315, 0.782, 0.693, 0.291, 0.778, 0.684, 0.266, 0.773,
+     0.675, 0.240, 0.768, 0.666, 0.214, 0.604, 0.659, 0.996, 0.614, 0.668,
+     0.990, 0.625, 0.677, 0.985, 0.636, 0.686, 0.981, 0.646, 0.695, 0.976,
+     0.657, 0.704, 0.972, 0.668, 0.714, 0.968, 0.679, 0.723, 0.965, 0.690,
+     0.732, 0.961, 0.701, 0.741, 0.958, 0.712, 0.750, 0.956, 0.723, 0.759,
+     0.953, 0.735, 0.769, 0.951, 0.746, 0.778, 0.949, 0.758, 0.787, 0.947,
+     0.769, 0.797, 0.945, 0.781, 0.806, 0.944, 0.793, 0.816, 0.943, 0.805,
+     0.826, 0.943, 0.817, 0.836, 0.942, 0.829, 0.845, 0.942, 0.841, 0.855,
+     0.942, 0.853, 0.866, 0.943, 0.866, 0.876, 0.943, 0.879, 0.886, 0.945,
+     0.892, 0.897, 0.946, 0.905, 0.907, 0.948, 0.918, 0.918, 0.950, 0.931,
+     0.930, 0.953, 0.945, 0.941, 0.956, 0.958, 0.952, 0.960, 0.971, 0.963,
+     0.963, 0.978, 0.968, 0.963, 0.972, 0.963, 0.948, 0.963, 0.954, 0.926,
+     0.954, 0.943, 0.903, 0.945, 0.931, 0.879, 0.937, 0.921, 0.855, 0.929,
+     0.910, 0.831, 0.921, 0.899, 0.807, 0.914, 0.889, 0.783, 0.907, 0.878,
+     0.759, 0.900, 0.868, 0.735, 0.893, 0.858, 0.711, 0.887, 0.848, 0.688,
+     0.880, 0.838, 0.664, 0.874, 0.828, 0.641, 0.868, 0.818, 0.617, 0.862,
+     0.809, 0.594, 0.856, 0.799, 0.571, 0.850, 0.790, 0.547, 0.845, 0.780,
+     0.524, 0.839, 0.771, 0.501, 0.834, 0.762, 0.478, 0.828, 0.752, 0.455,
+     0.823, 0.743, 0.432, 0.818, 0.734, 0.409, 0.813, 0.725, 0.385, 0.808,
+     0.716, 0.362, 0.803, 0.707, 0.338, 0.798, 0.698, 0.314, 0.793, 0.689,
+     0.290, 0.788, 0.680, 0.265, 0.783, 0.671, 0.239, 0.778, 0.662, 0.213,
+     0.615, 0.655, 0.996, 0.625, 0.664, 0.991, 0.635, 0.673, 0.986, 0.646,
+     0.683, 0.982, 0.656, 0.692, 0.977, 0.667, 0.701, 0.973, 0.678, 0.710,
+     0.969, 0.688, 0.719, 0.966, 0.699, 0.729, 0.962, 0.710, 0.738, 0.959,
+     0.721, 0.747, 0.956, 0.732, 0.756, 0.954, 0.744, 0.766, 0.952, 0.755,
+     0.775, 0.950, 0.766, 0.784, 0.948, 0.778, 0.794, 0.946, 0.789, 0.804,
+     0.945, 0.801, 0.813, 0.944, 0.813, 0.823, 0.943, 0.825, 0.833, 0.943,
+     0.837, 0.843, 0.943, 0.849, 0.853, 0.943, 0.861, 0.863, 0.944, 0.874,
+     0.873, 0.944, 0.886, 0.884, 0.946, 0.899, 0.895, 0.947, 0.912, 0.906,
+     0.949, 0.926, 0.917, 0.952, 0.939, 0.928, 0.955, 0.953, 0.940, 0.958,
+     0.967, 0.953, 0.963, 0.982, 0.966, 0.969, 0.994, 0.976, 0.972, 0.986,
+     0.966, 0.952, 0.976, 0.953, 0.928, 0.966, 0.941, 0.903, 0.957, 0.929,
+     0.878, 0.949, 0.918, 0.854, 0.941, 0.906, 0.830, 0.933, 0.896, 0.806,
+     0.926, 0.885, 0.782, 0.918, 0.874, 0.758, 0.911, 0.864, 0.734, 0.905,
+     0.854, 0.710, 0.898, 0.844, 0.686, 0.892, 0.834, 0.663, 0.885, 0.824,
+     0.639, 0.879, 0.814, 0.616, 0.873, 0.804, 0.592, 0.867, 0.795, 0.569,
+     0.861, 0.785, 0.546, 0.856, 0.776, 0.523, 0.850, 0.766, 0.500, 0.845,
+     0.757, 0.477, 0.839, 0.748, 0.454, 0.834, 0.739, 0.430, 0.829, 0.729,
+     0.407, 0.823, 0.720, 0.384, 0.818, 0.711, 0.361, 0.813, 0.702, 0.337,
+     0.808, 0.693, 0.313, 0.803, 0.684, 0.289, 0.798, 0.675, 0.264, 0.793,
+     0.666, 0.238, 0.788, 0.657, 0.211, 0.625, 0.651, 0.997, 0.635, 0.660,
+     0.992, 0.645, 0.669, 0.987, 0.656, 0.679, 0.982, 0.666, 0.688, 0.978,
+     0.676, 0.697, 0.974, 0.687, 0.706, 0.970, 0.698, 0.716, 0.966, 0.708,
+     0.725, 0.963, 0.719, 0.734, 0.960, 0.730, 0.743, 0.957, 0.741, 0.753,
+     0.954, 0.752, 0.762, 0.952, 0.763, 0.771, 0.950, 0.774, 0.781, 0.948,
+     0.786, 0.790, 0.947, 0.797, 0.800, 0.945, 0.809, 0.810, 0.945, 0.820,
+     0.819, 0.944, 0.832, 0.829, 0.943, 0.844, 0.839, 0.943, 0.856, 0.849,
+     0.943, 0.868, 0.860, 0.944, 0.880, 0.870, 0.945, 0.893, 0.880, 0.946,
+     0.905, 0.891, 0.947, 0.918, 0.902, 0.949, 0.931, 0.913, 0.951, 0.944,
+     0.924, 0.954, 0.957, 0.936, 0.957, 0.971, 0.947, 0.961, 0.983, 0.958,
+     0.964, 0.991, 0.963, 0.962, 0.990, 0.957, 0.946, 0.983, 0.946, 0.924,
+     0.975, 0.935, 0.900, 0.967, 0.923, 0.876, 0.959, 0.912, 0.851, 0.951,
+     0.901, 0.827, 0.943, 0.890, 0.803, 0.936, 0.880, 0.779, 0.929, 0.869,
+     0.755, 0.922, 0.859, 0.732, 0.915, 0.849, 0.708, 0.909, 0.839, 0.684,
+     0.902, 0.829, 0.661, 0.896, 0.819, 0.637, 0.890, 0.809, 0.614, 0.884,
+     0.800, 0.591, 0.878, 0.790, 0.567, 0.872, 0.780, 0.544, 0.866, 0.771,
+     0.521, 0.861, 0.762, 0.498, 0.855, 0.752, 0.475, 0.850, 0.743, 0.452,
+     0.844, 0.734, 0.429, 0.839, 0.725, 0.406, 0.834, 0.715, 0.382, 0.828,
+     0.706, 0.359, 0.823, 0.697, 0.335, 0.818, 0.688, 0.311, 0.813, 0.679,
+     0.287, 0.808, 0.670, 0.262, 0.803, 0.662, 0.236, 0.798, 0.653, 0.210,
+     0.635, 0.646, 0.998, 0.645, 0.656, 0.992, 0.655, 0.665, 0.987, 0.665,
+     0.674, 0.983, 0.675, 0.684, 0.978, 0.685, 0.693, 0.974, 0.696, 0.702,
+     0.970, 0.706, 0.711, 0.966, 0.717, 0.721, 0.963, 0.727, 0.730, 0.960,
+     0.738, 0.739, 0.957, 0.749, 0.748, 0.955, 0.760, 0.758, 0.952, 0.771,
+     0.767, 0.950, 0.782, 0.777, 0.948, 0.793, 0.786, 0.947, 0.804, 0.796,
+     0.946, 0.816, 0.805, 0.945, 0.827, 0.815, 0.944, 0.839, 0.825, 0.943,
+     0.850, 0.835, 0.943, 0.862, 0.845, 0.943, 0.874, 0.855, 0.943, 0.886,
+     0.865, 0.944, 0.898, 0.875, 0.945, 0.910, 0.886, 0.946, 0.923, 0.896,
+     0.948, 0.935, 0.907, 0.949, 0.947, 0.917, 0.951, 0.959, 0.927, 0.953,
+     0.970, 0.937, 0.955, 0.980, 0.944, 0.955, 0.987, 0.946, 0.949, 0.989,
+     0.942, 0.936, 0.985, 0.935, 0.916, 0.980, 0.925, 0.894, 0.973, 0.915,
+     0.871, 0.966, 0.904, 0.847, 0.959, 0.894, 0.824, 0.952, 0.883, 0.800,
+     0.945, 0.873, 0.776, 0.938, 0.863, 0.752, 0.932, 0.853, 0.729, 0.925,
+     0.843, 0.705, 0.919, 0.833, 0.682, 0.912, 0.823, 0.658, 0.906, 0.813,
+     0.635, 0.900, 0.803, 0.611, 0.894, 0.794, 0.588, 0.888, 0.784, 0.565,
+     0.882, 0.775, 0.542, 0.876, 0.765, 0.519, 0.871, 0.756, 0.496, 0.865,
+     0.747, 0.473, 0.859, 0.738, 0.450, 0.854, 0.728, 0.427, 0.848, 0.719,
+     0.404, 0.843, 0.710, 0.380, 0.838, 0.701, 0.357, 0.833, 0.692, 0.333,
+     0.827, 0.683, 0.310, 0.822, 0.674, 0.285, 0.817, 0.665, 0.260, 0.812,
+     0.656, 0.235, 0.807, 0.648, 0.208, 0.644, 0.642, 0.998, 0.654, 0.651,
+     0.993, 0.664, 0.660, 0.988, 0.674, 0.670, 0.983, 0.684, 0.679, 0.978,
+     0.694, 0.688, 0.974, 0.704, 0.697, 0.970, 0.715, 0.707, 0.967, 0.725,
+     0.716, 0.963, 0.735, 0.725, 0.960, 0.746, 0.735, 0.957, 0.757, 0.744,
+     0.955, 0.767, 0.753, 0.952, 0.778, 0.763, 0.950, 0.789, 0.772, 0.948,
+     0.800, 0.781, 0.947, 0.811, 0.791, 0.945, 0.822, 0.801, 0.944, 0.833,
+     0.810, 0.943, 0.845, 0.820, 0.943, 0.856, 0.830, 0.942, 0.868, 0.839,
+     0.942, 0.879, 0.849, 0.942, 0.891, 0.859, 0.943, 0.902, 0.869, 0.943,
+     0.914, 0.879, 0.944, 0.926, 0.889, 0.945, 0.937, 0.899, 0.946, 0.949,
+     0.908, 0.947, 0.959, 0.917, 0.948, 0.969, 0.924, 0.947, 0.978, 0.929,
+     0.944, 0.984, 0.930, 0.937, 0.986, 0.927, 0.924, 0.986, 0.921, 0.907,
+     0.982, 0.913, 0.887, 0.978, 0.904, 0.865, 0.972, 0.895, 0.842, 0.966,
+     0.885, 0.819, 0.959, 0.875, 0.795, 0.953, 0.865, 0.772, 0.946, 0.855,
+     0.749, 0.940, 0.846, 0.725, 0.934, 0.836, 0.702, 0.927, 0.826, 0.678,
+     0.921, 0.816, 0.655, 0.915, 0.807, 0.632, 0.909, 0.797, 0.609, 0.903,
+     0.788, 0.586, 0.897, 0.778, 0.562, 0.891, 0.769, 0.539, 0.886, 0.759,
+     0.516, 0.880, 0.750, 0.493, 0.874, 0.741, 0.471, 0.869, 0.732, 0.448,
+     0.863, 0.723, 0.425, 0.858, 0.713, 0.402, 0.852, 0.704, 0.378, 0.847,
+     0.695, 0.355, 0.842, 0.686, 0.331, 0.836, 0.677, 0.308, 0.831, 0.669,
+     0.283, 0.826, 0.660, 0.258, 0.821, 0.651, 0.233, 0.815, 0.642, 0.206,
+     0.653, 0.636, 0.998, 0.663, 0.646, 0.993, 0.673, 0.655, 0.988, 0.682,
+     0.665, 0.983, 0.692, 0.674, 0.979, 0.702, 0.683, 0.974, 0.712, 0.692,
+     0.970, 0.722, 0.702, 0.967, 0.733, 0.711, 0.963, 0.743, 0.720, 0.960,
+     0.753, 0.730, 0.957, 0.764, 0.739, 0.954, 0.774, 0.748, 0.952, 0.785,
+     0.757, 0.950, 0.796, 0.767, 0.948, 0.806, 0.776, 0.946, 0.817, 0.786,
+     0.945, 0.828, 0.795, 0.943, 0.839, 0.804, 0.942, 0.850, 0.814, 0.941,
+     0.861, 0.824, 0.941, 0.872, 0.833, 0.940, 0.884, 0.843, 0.940, 0.895,
+     0.852, 0.940, 0.906, 0.862, 0.940, 0.917, 0.871, 0.941, 0.928, 0.880,
+     0.941, 0.939, 0.889, 0.941, 0.949, 0.897, 0.941, 0.959, 0.904, 0.940,
+     0.968, 0.910, 0.938, 0.975, 0.914, 0.933, 0.981, 0.914, 0.925, 0.984,
+     0.912, 0.913, 0.985, 0.907, 0.897, 0.983, 0.900, 0.878, 0.980, 0.893,
+     0.857, 0.976, 0.884, 0.836, 0.971, 0.875, 0.813, 0.965, 0.866, 0.790,
+     0.959, 0.856, 0.767, 0.954, 0.847, 0.744, 0.947, 0.837, 0.721, 0.941,
+     0.828, 0.698, 0.935, 0.818, 0.675, 0.929, 0.809, 0.652, 0.923, 0.800,
+     0.629, 0.917, 0.790, 0.605, 0.912, 0.781, 0.582, 0.906, 0.771, 0.560,
+     0.900, 0.762, 0.537, 0.894, 0.753, 0.514, 0.889, 0.744, 0.491, 0.883,
+     0.735, 0.468, 0.877, 0.725, 0.445, 0.872, 0.716, 0.422, 0.866, 0.707,
+     0.399, 0.861, 0.698, 0.376, 0.856, 0.689, 0.353, 0.850, 0.680, 0.329,
+     0.845, 0.672, 0.305, 0.840, 0.663, 0.281, 0.834, 0.654, 0.256, 0.829,
+     0.645, 0.231, 0.824, 0.636, 0.204, 0.662, 0.631, 0.998, 0.672, 0.641,
+     0.993, 0.681, 0.650, 0.988, 0.691, 0.659, 0.983, 0.700, 0.669, 0.979,
+     0.710, 0.678, 0.974, 0.720, 0.687, 0.970, 0.730, 0.696, 0.966, 0.740,
+     0.706, 0.963, 0.750, 0.715, 0.960, 0.760, 0.724, 0.957, 0.771, 0.733,
+     0.954, 0.781, 0.742, 0.951, 0.791, 0.752, 0.949, 0.802, 0.761, 0.947,
+     0.812, 0.770, 0.945, 0.823, 0.779, 0.943, 0.834, 0.789, 0.942, 0.844,
+     0.798, 0.941, 0.855, 0.807, 0.940, 0.866, 0.817, 0.939, 0.877, 0.826,
+     0.938, 0.887, 0.835, 0.938, 0.898, 0.844, 0.937, 0.909, 0.853, 0.937,
+     0.919, 0.862, 0.937, 0.930, 0.870, 0.936, 0.940, 0.878, 0.936, 0.950,
+     0.885, 0.934, 0.958, 0.891, 0.932, 0.967, 0.896, 0.928, 0.974, 0.898,
+     0.922, 0.979, 0.899, 0.914, 0.982, 0.897, 0.902, 0.984, 0.893, 0.886,
+     0.984, 0.887, 0.869, 0.982, 0.880, 0.849, 0.979, 0.872, 0.828, 0.975,
+     0.864, 0.807, 0.970, 0.856, 0.785, 0.965, 0.847, 0.762, 0.959, 0.838,
+     0.739, 0.954, 0.829, 0.717, 0.948, 0.819, 0.694, 0.943, 0.810, 0.671,
+     0.937, 0.801, 0.648, 0.931, 0.792, 0.625, 0.925, 0.782, 0.602, 0.919,
+     0.773, 0.579, 0.914, 0.764, 0.556, 0.908, 0.755, 0.533, 0.902, 0.746,
+     0.511, 0.897, 0.737, 0.488, 0.891, 0.728, 0.465, 0.886, 0.719, 0.442,
+     0.880, 0.710, 0.420, 0.875, 0.701, 0.397, 0.869, 0.692, 0.374, 0.864,
+     0.683, 0.350, 0.858, 0.674, 0.327, 0.853, 0.665, 0.303, 0.848, 0.657,
+     0.279, 0.842, 0.648, 0.254, 0.837, 0.639, 0.229, 0.832, 0.630, 0.202,
+     0.671, 0.625, 0.998, 0.680, 0.635, 0.993, 0.689, 0.644, 0.988, 0.698,
+     0.654, 0.983, 0.708, 0.663, 0.978, 0.718, 0.672, 0.974, 0.727, 0.681,
+     0.970, 0.737, 0.691, 0.966, 0.747, 0.700, 0.962, 0.757, 0.709, 0.959,
+     0.767, 0.718, 0.956, 0.777, 0.727, 0.953, 0.787, 0.736, 0.950, 0.797,
+     0.745, 0.948, 0.807, 0.755, 0.946, 0.818, 0.764, 0.944, 0.828, 0.773,
+     0.942, 0.839, 0.782, 0.940, 0.849, 0.791, 0.939, 0.859, 0.800, 0.938,
+     0.870, 0.809, 0.937, 0.880, 0.818, 0.936, 0.891, 0.827, 0.935, 0.901,
+     0.835, 0.934, 0.911, 0.844, 0.933, 0.921, 0.852, 0.932, 0.931, 0.859,
+     0.931, 0.941, 0.866, 0.929, 0.950, 0.873, 0.927, 0.958, 0.878, 0.923,
+     0.966, 0.881, 0.919, 0.972, 0.883, 0.912, 0.977, 0.883, 0.903, 0.981,
+     0.882, 0.891, 0.983, 0.878, 0.876, 0.984, 0.873, 0.859, 0.983, 0.867,
+     0.841, 0.980, 0.860, 0.821, 0.977, 0.853, 0.800, 0.974, 0.845, 0.778,
+     0.969, 0.836, 0.756, 0.964, 0.828, 0.734, 0.959, 0.819, 0.712, 0.954,
+     0.810, 0.689, 0.949, 0.801, 0.666, 0.943, 0.792, 0.644, 0.938, 0.783,
+     0.621, 0.932, 0.774, 0.598, 0.927, 0.765, 0.575, 0.921, 0.756, 0.553,
+     0.916, 0.747, 0.530, 0.910, 0.738, 0.507, 0.904, 0.729, 0.485, 0.899,
+     0.721, 0.462, 0.893, 0.712, 0.439, 0.888, 0.703, 0.417, 0.882, 0.694,
+     0.394, 0.877, 0.685, 0.371, 0.871, 0.676, 0.348, 0.866, 0.668, 0.324,
+     0.861, 0.659, 0.301, 0.855, 0.650, 0.277, 0.850, 0.641, 0.252, 0.845,
+     0.633, 0.226, 0.839, 0.624, 0.200, 0.679, 0.619, 0.998, 0.688, 0.629,
+     0.993, 0.697, 0.638, 0.988, 0.706, 0.648, 0.983, 0.715, 0.657, 0.978,
+     0.725, 0.666, 0.974, 0.734, 0.675, 0.969, 0.744, 0.684, 0.965, 0.754,
+     0.693, 0.962, 0.763, 0.703, 0.958, 0.773, 0.712, 0.955, 0.783, 0.721,
+     0.952, 0.793, 0.730, 0.949, 0.803, 0.739, 0.947, 0.813, 0.748, 0.944,
+     0.823, 0.757, 0.942, 0.833, 0.766, 0.940, 0.843, 0.774, 0.938, 0.853,
+     0.783, 0.937, 0.863, 0.792, 0.935, 0.874, 0.801, 0.934, 0.884, 0.809,
+     0.932, 0.894, 0.818, 0.931, 0.904, 0.826, 0.930, 0.913, 0.833, 0.928,
+     0.923, 0.841, 0.927, 0.932, 0.848, 0.925, 0.941, 0.854, 0.922, 0.950,
+     0.859, 0.919, 0.957, 0.864, 0.915, 0.965, 0.867, 0.909, 0.971, 0.868,
+     0.901, 0.976, 0.868, 0.892, 0.980, 0.867, 0.880, 0.982, 0.863, 0.866,
+     0.983, 0.859, 0.849, 0.983, 0.854, 0.832, 0.982, 0.847, 0.812, 0.979,
+     0.840, 0.792, 0.976, 0.833, 0.771, 0.973, 0.825, 0.750, 0.969, 0.817,
+     0.728, 0.964, 0.809, 0.706, 0.959, 0.800, 0.684, 0.954, 0.792, 0.661,
+     0.949, 0.783, 0.639, 0.944, 0.774, 0.617, 0.939, 0.766, 0.594, 0.933,
+     0.757, 0.572, 0.928, 0.748, 0.549, 0.922, 0.739, 0.527, 0.917, 0.731,
+     0.504, 0.911, 0.722, 0.481, 0.906, 0.713, 0.459, 0.901, 0.704, 0.436,
+     0.895, 0.695, 0.414, 0.890, 0.687, 0.391, 0.884, 0.678, 0.368, 0.879,
+     0.669, 0.345, 0.873, 0.661, 0.322, 0.868, 0.652, 0.298, 0.863, 0.643,
+     0.274, 0.857, 0.635, 0.249, 0.852, 0.626, 0.224, 0.846, 0.617, 0.197,
+     0.686, 0.613, 0.998, 0.695, 0.622, 0.993, 0.704, 0.632, 0.987, 0.713,
+     0.641, 0.982, 0.722, 0.650, 0.977, 0.732, 0.660, 0.973, 0.741, 0.669,
+     0.969, 0.750, 0.678, 0.965, 0.760, 0.687, 0.961, 0.769, 0.696, 0.957,
+     0.779, 0.705, 0.954, 0.789, 0.714, 0.951, 0.798, 0.723, 0.948, 0.808,
+     0.731, 0.945, 0.818, 0.740, 0.943, 0.828, 0.749, 0.940, 0.838, 0.758,
+     0.938, 0.847, 0.766, 0.936, 0.857, 0.775, 0.934, 0.867, 0.783, 0.932,
+     0.877, 0.792, 0.930, 0.887, 0.800, 0.929, 0.896, 0.808, 0.927, 0.906,
+     0.815, 0.925, 0.915, 0.823, 0.923, 0.924, 0.829, 0.921, 0.933, 0.836,
+     0.918, 0.942, 0.841, 0.915, 0.950, 0.846, 0.911, 0.957, 0.850, 0.906,
+     0.964, 0.852, 0.899, 0.970, 0.853, 0.891, 0.975, 0.853, 0.881, 0.979,
+     0.852, 0.869, 0.981, 0.849, 0.855, 0.983, 0.845, 0.840, 0.983, 0.840,
+     0.822, 0.982, 0.834, 0.804, 0.981, 0.828, 0.784, 0.978, 0.821, 0.764,
+     0.975, 0.814, 0.743, 0.972, 0.806, 0.722, 0.968, 0.798, 0.700, 0.964,
+     0.790, 0.678, 0.959, 0.782, 0.656, 0.954, 0.773, 0.634, 0.949, 0.765,
+     0.612, 0.944, 0.757, 0.590, 0.939, 0.748, 0.567, 0.934, 0.739, 0.545,
+     0.929, 0.731, 0.523, 0.923, 0.722, 0.500, 0.918, 0.714, 0.478, 0.913,
+     0.705, 0.456, 0.907, 0.696, 0.433, 0.902, 0.688, 0.411, 0.896, 0.679,
+     0.388, 0.891, 0.670, 0.365, 0.886, 0.662, 0.342, 0.880, 0.653, 0.319,
+     0.875, 0.645, 0.295, 0.869, 0.636, 0.271, 0.864, 0.628, 0.247, 0.859,
+     0.619, 0.221, 0.853, 0.611, 0.195, 0.694, 0.606, 0.998, 0.703, 0.616,
+     0.992, 0.711, 0.625, 0.987, 0.720, 0.634, 0.982, 0.729, 0.644, 0.977,
+     0.738, 0.653, 0.972, 0.747, 0.662, 0.968, 0.757, 0.671, 0.964, 0.766,
+     0.680, 0.960, 0.775, 0.689, 0.956, 0.785, 0.698, 0.953, 0.794, 0.706,
+     0.949, 0.804, 0.715, 0.946, 0.813, 0.724, 0.943, 0.823, 0.732, 0.941,
+     0.832, 0.741, 0.938, 0.842, 0.749, 0.936, 0.851, 0.758, 0.933, 0.861,
+     0.766, 0.931, 0.870, 0.774, 0.929, 0.880, 0.782, 0.927, 0.889, 0.790,
+     0.924, 0.899, 0.797, 0.922, 0.908, 0.805, 0.920, 0.917, 0.811, 0.917,
+     0.925, 0.818, 0.914, 0.934, 0.823, 0.911, 0.942, 0.828, 0.907, 0.950,
+     0.832, 0.902, 0.957, 0.836, 0.896, 0.963, 0.838, 0.889, 0.969, 0.839,
+     0.881, 0.974, 0.838, 0.871, 0.978, 0.837, 0.859, 0.980, 0.834, 0.845,
+     0.982, 0.831, 0.830, 0.983, 0.826, 0.813, 0.983, 0.821, 0.795, 0.982,
+     0.815, 0.776, 0.980, 0.809, 0.757, 0.978, 0.802, 0.736, 0.975, 0.794,
+     0.715, 0.971, 0.787, 0.694, 0.967, 0.779, 0.673, 0.963, 0.771, 0.651,
+     0.959, 0.763, 0.629, 0.954, 0.755, 0.607, 0.949, 0.747, 0.585, 0.944,
+     0.739, 0.563, 0.939, 0.730, 0.541, 0.934, 0.722, 0.519, 0.929, 0.714,
+     0.496, 0.924, 0.705, 0.474, 0.919, 0.697, 0.452, 0.913, 0.688, 0.430,
+     0.908, 0.680, 0.407, 0.903, 0.671, 0.385, 0.897, 0.663, 0.362, 0.892,
+     0.654, 0.339, 0.887, 0.646, 0.316, 0.881, 0.637, 0.293, 0.876, 0.629,
+     0.269, 0.870, 0.620, 0.244, 0.865, 0.612, 0.219, 0.860, 0.604, 0.192,
+     0.701, 0.599, 0.997, 0.710, 0.609, 0.992, 0.718, 0.618, 0.986, 0.727,
+     0.627, 0.981, 0.736, 0.636, 0.976, 0.745, 0.645, 0.971, 0.754, 0.655,
+     0.967, 0.763, 0.663, 0.963, 0.772, 0.672, 0.959, 0.781, 0.681, 0.955,
+     0.790, 0.690, 0.951, 0.799, 0.699, 0.948, 0.808, 0.707, 0.944, 0.818,
+     0.716, 0.941, 0.827, 0.724, 0.938, 0.836, 0.732, 0.935, 0.846, 0.741,
+     0.933, 0.855, 0.749, 0.930, 0.864, 0.757, 0.928, 0.874, 0.765, 0.925,
+     0.883, 0.772, 0.923, 0.892, 0.780, 0.920, 0.901, 0.787, 0.917, 0.910,
+     0.793, 0.914, 0.918, 0.800, 0.911, 0.927, 0.805, 0.908, 0.935, 0.811,
+     0.904, 0.942, 0.815, 0.899, 0.950, 0.819, 0.894, 0.956, 0.821, 0.887,
+     0.963, 0.823, 0.880, 0.968, 0.824, 0.871, 0.973, 0.824, 0.860, 0.977,
+     0.822, 0.849, 0.980, 0.820, 0.835, 0.982, 0.817, 0.820, 0.983, 0.812,
+     0.804, 0.983, 0.808, 0.786, 0.983, 0.802, 0.768, 0.981, 0.796, 0.749,
+     0.979, 0.789, 0.729, 0.977, 0.783, 0.709, 0.974, 0.776, 0.688, 0.970,
+     0.768, 0.667, 0.967, 0.761, 0.645, 0.963, 0.753, 0.624, 0.958, 0.745,
+     0.602, 0.954, 0.737, 0.580, 0.949, 0.729, 0.558, 0.944, 0.721, 0.536,
+     0.939, 0.713, 0.514, 0.934, 0.704, 0.492, 0.929, 0.696, 0.470, 0.924,
+     0.688, 0.448, 0.919, 0.680, 0.426, 0.914, 0.671, 0.404, 0.908, 0.663,
+     0.381, 0.903, 0.655, 0.359, 0.898, 0.646, 0.336, 0.893, 0.638, 0.313,
+     0.887, 0.629, 0.290, 0.882, 0.621, 0.266, 0.876, 0.613, 0.241, 0.871,
+     0.604, 0.216, 0.866, 0.596, 0.189, 0.708, 0.592, 0.997, 0.716, 0.601,
+     0.991, 0.725, 0.611, 0.985, 0.733, 0.620, 0.980, 0.742, 0.629, 0.975,
+     0.751, 0.638, 0.970, 0.759, 0.647, 0.966, 0.768, 0.656, 0.961, 0.777,
+     0.665, 0.957, 0.786, 0.673, 0.953, 0.795, 0.682, 0.949, 0.804, 0.690,
+     0.946, 0.813, 0.699, 0.942, 0.822, 0.707, 0.939, 0.831, 0.715, 0.936,
+     0.840, 0.723, 0.933, 0.849, 0.731, 0.930, 0.859, 0.739, 0.927, 0.868,
+     0.747, 0.924, 0.876, 0.754, 0.921, 0.885, 0.762, 0.918, 0.894, 0.769,
+     0.915, 0.903, 0.775, 0.912, 0.911, 0.782, 0.909, 0.920, 0.787, 0.905,
+     0.928, 0.793, 0.901, 0.935, 0.798, 0.896, 0.943, 0.802, 0.891, 0.950,
+     0.805, 0.885, 0.956, 0.807, 0.878, 0.962, 0.809, 0.870, 0.967, 0.809,
+     0.861, 0.972, 0.809, 0.850, 0.976, 0.808, 0.838, 0.979, 0.805, 0.825,
+     0.981, 0.802, 0.810, 0.983, 0.799, 0.795, 0.983, 0.794, 0.778, 0.983,
+     0.789, 0.760, 0.982, 0.783, 0.741, 0.981, 0.777, 0.721, 0.979, 0.771,
+     0.701, 0.976, 0.764, 0.681, 0.973, 0.757, 0.660, 0.970, 0.750, 0.639,
+     0.966, 0.742, 0.618, 0.962, 0.735, 0.597, 0.958, 0.727, 0.575, 0.953,
+     0.719, 0.553, 0.949, 0.711, 0.532, 0.944, 0.703, 0.510, 0.939, 0.695,
+     0.488, 0.934, 0.687, 0.466, 0.929, 0.679, 0.444, 0.924, 0.671, 0.422,
+     0.919, 0.663, 0.400, 0.914, 0.654, 0.378, 0.909, 0.646, 0.355, 0.903,
+     0.638, 0.333, 0.898, 0.630, 0.310, 0.893, 0.621, 0.287, 0.887, 0.613,
+     0.263, 0.882, 0.605, 0.238, 0.877, 0.597, 0.213, 0.871, 0.589, 0.186,
+     0.715, 0.584, 0.996, 0.723, 0.593, 0.990, 0.731, 0.603, 0.984, 0.739,
+     0.612, 0.979, 0.748, 0.621, 0.974, 0.756, 0.630, 0.969, 0.765, 0.639,
+     0.964, 0.774, 0.648, 0.960, 0.782, 0.656, 0.955, 0.791, 0.665, 0.951,
+     0.800, 0.673, 0.947, 0.809, 0.682, 0.943, 0.818, 0.690, 0.940, 0.826,
+     0.698, 0.936, 0.835, 0.706, 0.933, 0.844, 0.714, 0.930, 0.853, 0.722,
+     0.926, 0.862, 0.729, 0.923, 0.871, 0.737, 0.920, 0.879, 0.744, 0.917,
+     0.888, 0.751, 0.913, 0.896, 0.758, 0.910, 0.905, 0.764, 0.906, 0.913,
+     0.770, 0.903, 0.921, 0.775, 0.898, 0.929, 0.780, 0.894, 0.936, 0.784,
+     0.889, 0.943, 0.788, 0.883, 0.950, 0.791, 0.877, 0.956, 0.793, 0.869,
+     0.962, 0.794, 0.861, 0.967, 0.795, 0.851, 0.971, 0.794, 0.841, 0.975,
+     0.793, 0.829, 0.978, 0.791, 0.815, 0.981, 0.788, 0.801, 0.982, 0.785,
+     0.785, 0.983, 0.780, 0.769, 0.983, 0.776, 0.751, 0.983, 0.770, 0.733,
+     0.982, 0.764, 0.714, 0.980, 0.758, 0.694, 0.978, 0.752, 0.674, 0.975,
+     0.745, 0.654, 0.972, 0.738, 0.633, 0.969, 0.731, 0.612, 0.965, 0.724,
+     0.591, 0.961, 0.716, 0.570, 0.957, 0.709, 0.548, 0.953, 0.701, 0.527,
+     0.948, 0.693, 0.505, 0.943, 0.685, 0.484, 0.939, 0.678, 0.462, 0.934,
+     0.670, 0.440, 0.929, 0.662, 0.418, 0.924, 0.654, 0.396, 0.919, 0.646,
+     0.374, 0.914, 0.637, 0.352, 0.908, 0.629, 0.329, 0.903, 0.621, 0.307,
+     0.898, 0.613, 0.283, 0.893, 0.605, 0.260, 0.887, 0.597, 0.235, 0.882,
+     0.589, 0.210, 0.876, 0.581, 0.183, 0.721, 0.576, 0.995, 0.729, 0.585,
+     0.989, 0.737, 0.595, 0.983, 0.745, 0.604, 0.978, 0.754, 0.613, 0.973,
+     0.762, 0.622, 0.968, 0.770, 0.631, 0.963, 0.779, 0.639, 0.958, 0.787,
+     0.648, 0.954, 0.796, 0.656, 0.949, 0.805, 0.665, 0.945, 0.813, 0.673,
+     0.941, 0.822, 0.681, 0.937, 0.830, 0.689, 0.933, 0.839, 0.697, 0.930,
+     0.848, 0.704, 0.926, 0.856, 0.712, 0.923, 0.865, 0.719, 0.919, 0.873,
+     0.726, 0.916, 0.882, 0.733, 0.912, 0.890, 0.740, 0.908, 0.898, 0.746,
+     0.905, 0.906, 0.752, 0.901, 0.914, 0.757, 0.896, 0.922, 0.762, 0.892,
+     0.929, 0.767, 0.887, 0.937, 0.771, 0.881, 0.943, 0.774, 0.875, 0.950,
+     0.777, 0.868, 0.956, 0.779, 0.860, 0.961, 0.780, 0.851, 0.966, 0.780,
+     0.842, 0.971, 0.780, 0.831, 0.975, 0.779, 0.819, 0.978, 0.777, 0.806,
+     0.980, 0.774, 0.791, 0.982, 0.771, 0.776, 0.983, 0.767, 0.760, 0.984,
+     0.762, 0.742, 0.983, 0.757, 0.725, 0.983, 0.752, 0.706, 0.981, 0.746,
+     0.687, 0.979, 0.740, 0.667, 0.977, 0.733, 0.647, 0.974, 0.727, 0.627,
+     0.971, 0.720, 0.606, 0.968, 0.713, 0.585, 0.964, 0.706, 0.564, 0.960,
+     0.698, 0.543, 0.956, 0.691, 0.522, 0.952, 0.683, 0.501, 0.947, 0.676,
+     0.479, 0.943, 0.668, 0.458, 0.938, 0.660, 0.436, 0.933, 0.652, 0.414,
+     0.928, 0.644, 0.392, 0.923, 0.636, 0.370, 0.918, 0.629, 0.348, 0.913,
+     0.621, 0.326, 0.908, 0.613, 0.303, 0.903, 0.605, 0.280, 0.897, 0.597,
+     0.257, 0.892, 0.589, 0.232, 0.887, 0.581, 0.207, 0.881, 0.573, 0.180,
+     0.727, 0.568, 0.994, 0.735, 0.577, 0.988, 0.743, 0.586, 0.982, 0.751,
+     0.595, 0.977, 0.759, 0.604, 0.971, 0.767, 0.613, 0.966, 0.776, 0.622,
+     0.961, 0.784, 0.630, 0.956, 0.792, 0.639, 0.951, 0.801, 0.647, 0.947,
+     0.809, 0.655, 0.943, 0.817, 0.663, 0.938, 0.826, 0.671, 0.934, 0.834,
+     0.679, 0.930, 0.843, 0.687, 0.927, 0.851, 0.694, 0.923, 0.859, 0.702,
+     0.919, 0.868, 0.709, 0.915, 0.876, 0.715, 0.911, 0.884, 0.722, 0.907,
+     0.892, 0.728, 0.903, 0.900, 0.734, 0.899, 0.908, 0.740, 0.895, 0.916,
+     0.745, 0.890, 0.923, 0.750, 0.885, 0.930, 0.754, 0.879, 0.937, 0.758,
+     0.873, 0.944, 0.761, 0.867, 0.950, 0.763, 0.859, 0.956, 0.765, 0.851,
+     0.961, 0.766, 0.842, 0.966, 0.766, 0.832, 0.970, 0.766, 0.821, 0.974,
+     0.764, 0.809, 0.977, 0.762, 0.796, 0.980, 0.760, 0.782, 0.982, 0.757,
+     0.767, 0.983, 0.753, 0.751, 0.984, 0.749, 0.734, 0.984, 0.744, 0.716,
+     0.983, 0.739, 0.698, 0.982, 0.733, 0.679, 0.980, 0.727, 0.660, 0.978,
+     0.721, 0.640, 0.976, 0.715, 0.620, 0.973, 0.708, 0.600, 0.970, 0.701,
+     0.579, 0.967, 0.694, 0.559, 0.963, 0.687, 0.538, 0.959, 0.680, 0.517,
+     0.955, 0.673, 0.496, 0.951, 0.665, 0.474, 0.946, 0.658, 0.453, 0.942,
+     0.650, 0.432, 0.937, 0.643, 0.410, 0.932, 0.635, 0.388, 0.927, 0.627,
+     0.367, 0.922, 0.619, 0.345, 0.917, 0.612, 0.322, 0.912, 0.604, 0.300,
+     0.907, 0.596, 0.277, 0.902, 0.588, 0.253, 0.897, 0.580, 0.229, 0.891,
+     0.572, 0.204, 0.886, 0.564, 0.177, 0.733, 0.559, 0.993, 0.741, 0.568,
+     0.987, 0.749, 0.577, 0.981, 0.757, 0.587, 0.975, 0.765, 0.595, 0.970,
+     0.773, 0.604, 0.964, 0.781, 0.613, 0.959, 0.789, 0.621, 0.954, 0.797,
+     0.630, 0.949, 0.805, 0.638, 0.945, 0.813, 0.646, 0.940, 0.821, 0.654,
+     0.936, 0.830, 0.662, 0.931, 0.838, 0.669, 0.927, 0.846, 0.677, 0.923,
+     0.854, 0.684, 0.919, 0.862, 0.691, 0.915, 0.870, 0.698, 0.911, 0.879,
+     0.704, 0.907, 0.886, 0.711, 0.902, 0.894, 0.717, 0.898, 0.902, 0.722,
+     0.893, 0.910, 0.727, 0.889, 0.917, 0.732, 0.883, 0.924, 0.737, 0.878,
+     0.931, 0.741, 0.872, 0.938, 0.744, 0.866, 0.944, 0.747, 0.859, 0.950,
+     0.749, 0.851, 0.956, 0.751, 0.842, 0.961, 0.751, 0.833, 0.966, 0.752,
+     0.823, 0.970, 0.751, 0.812, 0.974, 0.750, 0.800, 0.977, 0.748, 0.787,
+     0.979, 0.746, 0.773, 0.981, 0.743, 0.758, 0.983, 0.739, 0.742, 0.984,
+     0.735, 0.725, 0.984, 0.731, 0.708, 0.983, 0.726, 0.690, 0.983, 0.721,
+     0.672, 0.981, 0.715, 0.653, 0.980, 0.709, 0.633, 0.977, 0.703, 0.614,
+     0.975, 0.697, 0.594, 0.972, 0.690, 0.573, 0.969, 0.683, 0.553, 0.965,
+     0.676, 0.532, 0.962, 0.669, 0.512, 0.958, 0.662, 0.491, 0.954, 0.655,
+     0.470, 0.949, 0.648, 0.448, 0.945, 0.640, 0.427, 0.941, 0.633, 0.406,
+     0.936, 0.625, 0.384, 0.931, 0.618, 0.363, 0.926, 0.610, 0.341, 0.921,
+     0.602, 0.319, 0.916, 0.595, 0.296, 0.911, 0.587, 0.273, 0.906, 0.579,
+     0.250, 0.901, 0.571, 0.226, 0.896, 0.563, 0.201, 0.890, 0.556, 0.174,
+     0.739, 0.550, 0.992, 0.747, 0.559, 0.986, 0.754, 0.568, 0.980, 0.762,
+     0.577, 0.974, 0.770, 0.586, 0.968, 0.778, 0.595, 0.962, 0.785, 0.603,
+     0.957, 0.793, 0.612, 0.952, 0.801, 0.620, 0.947, 0.809, 0.628, 0.942,
+     0.817, 0.636, 0.937, 0.825, 0.644, 0.933, 0.833, 0.651, 0.928, 0.841,
+     0.659, 0.924, 0.849, 0.666, 0.919, 0.857, 0.673, 0.915, 0.865, 0.680,
+     0.911, 0.873, 0.686, 0.906, 0.881, 0.693, 0.902, 0.889, 0.699, 0.897,
+     0.896, 0.705, 0.892, 0.904, 0.710, 0.887, 0.911, 0.715, 0.882, 0.918,
+     0.720, 0.877, 0.925, 0.724, 0.871, 0.932, 0.727, 0.865, 0.938, 0.730,
+     0.858, 0.944, 0.733, 0.850, 0.950, 0.735, 0.842, 0.956, 0.736, 0.834,
+     0.961, 0.737, 0.824, 0.965, 0.737, 0.814, 0.970, 0.737, 0.802, 0.973,
+     0.736, 0.790, 0.976, 0.734, 0.777, 0.979, 0.732, 0.763, 0.981, 0.729,
+     0.749, 0.982, 0.726, 0.733, 0.983, 0.722, 0.717, 0.984, 0.717, 0.700,
+     0.984, 0.713, 0.682, 0.983, 0.708, 0.664, 0.982, 0.702, 0.645, 0.980,
+     0.697, 0.626, 0.979, 0.691, 0.607, 0.976, 0.685, 0.587, 0.974, 0.678,
+     0.567, 0.971, 0.672, 0.547, 0.967, 0.665, 0.527, 0.964, 0.658, 0.506,
+     0.960, 0.651, 0.485, 0.956, 0.644, 0.465, 0.952, 0.637, 0.444, 0.948,
+     0.630, 0.423, 0.944, 0.623, 0.401, 0.939, 0.615, 0.380, 0.934, 0.608,
+     0.358, 0.930, 0.600, 0.337, 0.925, 0.593, 0.315, 0.920, 0.585, 0.292,
+     0.915, 0.578, 0.270, 0.910, 0.570, 0.246, 0.905, 0.562, 0.222, 0.899,
+     0.555, 0.197, 0.894, 0.547, 0.171, 0.745, 0.540, 0.991, 0.752, 0.550,
+     0.984, 0.760, 0.559, 0.978, 0.767, 0.568, 0.972, 0.775, 0.577, 0.966,
+     0.782, 0.585, 0.960, 0.790, 0.594, 0.955, 0.798, 0.602, 0.950, 0.806,
+     0.610, 0.944, 0.813, 0.618, 0.939, 0.821, 0.626, 0.934, 0.829, 0.634,
+     0.930, 0.837, 0.641, 0.925, 0.845, 0.648, 0.920, 0.852, 0.655, 0.915,
+     0.860, 0.662, 0.911, 0.868, 0.669, 0.906, 0.876, 0.675, 0.901, 0.883,
+     0.681, 0.897, 0.891, 0.687, 0.892, 0.898, 0.692, 0.887, 0.905, 0.697,
+     0.881, 0.912, 0.702, 0.876, 0.919, 0.707, 0.870, 0.926, 0.710, 0.864,
+     0.932, 0.714, 0.857, 0.939, 0.717, 0.850, 0.945, 0.719, 0.842, 0.950,
+     0.721, 0.834, 0.956, 0.722, 0.825, 0.961, 0.723, 0.815, 0.965, 0.723,
+     0.804, 0.969, 0.723, 0.793, 0.973, 0.722, 0.781, 0.976, 0.720, 0.768,
+     0.978, 0.718, 0.754, 0.981, 0.715, 0.739, 0.982, 0.712, 0.724, 0.983,
+     0.708, 0.708, 0.984, 0.704, 0.691, 0.984, 0.700, 0.674, 0.983, 0.695,
+     0.656, 0.982, 0.690, 0.638, 0.981, 0.684, 0.619, 0.979, 0.679, 0.600,
+     0.977, 0.673, 0.581, 0.975, 0.666, 0.561, 0.972, 0.660, 0.541, 0.969,
+     0.654, 0.521, 0.966, 0.647, 0.501, 0.962, 0.640, 0.480, 0.959, 0.634,
+     0.459, 0.955, 0.627, 0.439, 0.951, 0.620, 0.418, 0.946, 0.612, 0.397,
+     0.942, 0.605, 0.376, 0.937, 0.598, 0.354, 0.933, 0.591, 0.333, 0.928,
+     0.583, 0.311, 0.923, 0.576, 0.289, 0.918, 0.568, 0.266, 0.913, 0.561,
+     0.243, 0.908, 0.553, 0.219, 0.903, 0.546, 0.194, 0.898, 0.538, 0.167,
+     0.750, 0.531, 0.989, 0.757, 0.540, 0.983, 0.765, 0.549, 0.976, 0.772,
+     0.558, 0.970, 0.779, 0.567, 0.964, 0.787, 0.575, 0.958, 0.794, 0.584,
+     0.953, 0.802, 0.592, 0.947, 0.810, 0.600, 0.942, 0.817, 0.608, 0.936,
+     0.825, 0.615, 0.931, 0.833, 0.623, 0.926, 0.840, 0.630, 0.921, 0.848,
+     0.637, 0.916, 0.855, 0.644, 0.911, 0.863, 0.651, 0.907, 0.870, 0.657,
+     0.902, 0.878, 0.663, 0.897, 0.885, 0.669, 0.891, 0.893, 0.675, 0.886,
+     0.900, 0.680, 0.881, 0.907, 0.685, 0.875, 0.914, 0.689, 0.869, 0.920,
+     0.693, 0.863, 0.927, 0.697, 0.857, 0.933, 0.700, 0.850, 0.939, 0.703,
+     0.842, 0.945, 0.705, 0.834, 0.950, 0.707, 0.825, 0.956, 0.708, 0.816,
+     0.960, 0.709, 0.806, 0.965, 0.709, 0.795, 0.969, 0.708, 0.784, 0.972,
+     0.707, 0.772, 0.975, 0.706, 0.759, 0.978, 0.704, 0.745, 0.980, 0.701,
+     0.731, 0.982, 0.698, 0.715, 0.983, 0.694, 0.699, 0.984, 0.691, 0.683,
+     0.984, 0.686, 0.666, 0.983, 0.682, 0.648, 0.983, 0.677, 0.630, 0.982,
+     0.672, 0.612, 0.980, 0.666, 0.593, 0.978, 0.660, 0.574, 0.976, 0.655,
+     0.554, 0.973, 0.648, 0.535, 0.971, 0.642, 0.515, 0.967, 0.636, 0.495,
+     0.964, 0.629, 0.475, 0.961, 0.623, 0.454, 0.957, 0.616, 0.434, 0.953,
+     0.609, 0.413, 0.949, 0.602, 0.392, 0.944, 0.595, 0.371, 0.940, 0.588,
+     0.350, 0.936, 0.580, 0.328, 0.931, 0.573, 0.307, 0.926, 0.566, 0.285,
+     0.921, 0.559, 0.262, 0.916, 0.551, 0.239, 0.911, 0.544, 0.215, 0.906,
+     0.536, 0.190, 0.901, 0.529, 0.164, 0.755, 0.521, 0.988, 0.762, 0.530,
+     0.981, 0.770, 0.539, 0.975, 0.777, 0.548, 0.968, 0.784, 0.557, 0.962,
+     0.791, 0.565, 0.956, 0.799, 0.573, 0.950, 0.806, 0.582, 0.944, 0.814,
+     0.589, 0.939, 0.821, 0.597, 0.933, 0.828, 0.605, 0.928, 0.836, 0.612,
+     0.923, 0.843, 0.619, 0.918, 0.851, 0.626, 0.912, 0.858, 0.633, 0.907,
+     0.866, 0.639, 0.902, 0.873, 0.645, 0.897, 0.880, 0.651, 0.892, 0.887,
+     0.657, 0.886, 0.894, 0.662, 0.881, 0.901, 0.667, 0.875, 0.908, 0.672,
+     0.869, 0.915, 0.676, 0.863, 0.921, 0.680, 0.856, 0.928, 0.684, 0.849,
+     0.934, 0.687, 0.842, 0.940, 0.689, 0.834, 0.945, 0.691, 0.826, 0.951,
+     0.693, 0.817, 0.956, 0.694, 0.807, 0.960, 0.695, 0.797, 0.964, 0.695,
+     0.787, 0.968, 0.694, 0.775, 0.972, 0.693, 0.763, 0.975, 0.692, 0.750,
+     0.977, 0.690, 0.736, 0.980, 0.687, 0.722, 0.981, 0.684, 0.707, 0.982,
+     0.681, 0.691, 0.983, 0.677, 0.675, 0.984, 0.673, 0.658, 0.983, 0.669,
+     0.641, 0.983, 0.664, 0.623, 0.982, 0.659, 0.605, 0.980, 0.654, 0.586,
+     0.979, 0.648, 0.567, 0.977, 0.642, 0.548, 0.974, 0.637, 0.529, 0.972,
+     0.630, 0.509, 0.969, 0.624, 0.489, 0.966, 0.618, 0.469, 0.962, 0.611,
+     0.449, 0.959, 0.605, 0.429, 0.955, 0.598, 0.408, 0.951, 0.591, 0.387,
+     0.947, 0.584, 0.367, 0.942, 0.577, 0.346, 0.938, 0.570, 0.324, 0.933,
+     0.563, 0.303, 0.929, 0.556, 0.281, 0.924, 0.549, 0.258, 0.919, 0.541,
+     0.235, 0.914, 0.534, 0.212, 0.909, 0.527, 0.187, 0.904, 0.519, 0.160,
+     0.760, 0.510, 0.986, 0.767, 0.520, 0.979, 0.774, 0.529, 0.973, 0.781,
+     0.538, 0.966, 0.788, 0.546, 0.960, 0.796, 0.555, 0.954, 0.803, 0.563,
+     0.948, 0.810, 0.571, 0.942, 0.817, 0.579, 0.936, 0.825, 0.586, 0.930,
+     0.832, 0.594, 0.925, 0.839, 0.601, 0.919, 0.846, 0.608, 0.914, 0.854,
+     0.615, 0.908, 0.861, 0.621, 0.903, 0.868, 0.627, 0.897, 0.875, 0.633,
+     0.892, 0.882, 0.639, 0.886, 0.889, 0.645, 0.881, 0.896, 0.650, 0.875,
+     0.903, 0.655, 0.869, 0.909, 0.659, 0.863, 0.916, 0.663, 0.856, 0.922,
+     0.667, 0.849, 0.928, 0.670, 0.842, 0.934, 0.673, 0.834, 0.940, 0.675,
+     0.826, 0.945, 0.677, 0.818, 0.951, 0.679, 0.809, 0.955, 0.680, 0.799,
+     0.960, 0.680, 0.789, 0.964, 0.680, 0.778, 0.968, 0.680, 0.766, 0.971,
+     0.679, 0.754, 0.974, 0.677, 0.741, 0.977, 0.676, 0.727, 0.979, 0.673,
+     0.713, 0.981, 0.670, 0.698, 0.982, 0.667, 0.682, 0.983, 0.664, 0.666,
+     0.983, 0.660, 0.650, 0.983, 0.655, 0.633, 0.983, 0.651, 0.615, 0.982,
+     0.646, 0.597, 0.981, 0.641, 0.579, 0.979, 0.636, 0.560, 0.977, 0.630,
+     0.541, 0.975, 0.625, 0.522, 0.973, 0.619, 0.503, 0.970, 0.613, 0.483,
+     0.967, 0.606, 0.463, 0.964, 0.600, 0.443, 0.960, 0.594, 0.423, 0.956,
+     0.587, 0.403, 0.953, 0.580, 0.383, 0.949, 0.574, 0.362, 0.944, 0.567,
+     0.341, 0.940, 0.560, 0.320, 0.936, 0.553, 0.298, 0.931, 0.546, 0.277,
+     0.926, 0.539, 0.254, 0.922, 0.532, 0.232, 0.917, 0.524, 0.208, 0.912,
+     0.517, 0.183, 0.906, 0.510, 0.156, 0.765, 0.499, 0.985, 0.772, 0.509,
+     0.978, 0.779, 0.518, 0.971, 0.786, 0.527, 0.964, 0.793, 0.535, 0.957,
+     0.800, 0.544, 0.951, 0.807, 0.552, 0.945, 0.814, 0.560, 0.939, 0.821,
+     0.568, 0.933, 0.828, 0.575, 0.927, 0.835, 0.582, 0.921, 0.842, 0.589,
+     0.915, 0.849, 0.596, 0.910, 0.856, 0.603, 0.904, 0.863, 0.609, 0.898,
+     0.870, 0.615, 0.893, 0.877, 0.621, 0.887, 0.884, 0.627, 0.881, 0.891,
+     0.632, 0.875, 0.898, 0.637, 0.869, 0.904, 0.642, 0.863, 0.911, 0.646,
+     0.856, 0.917, 0.650, 0.849, 0.923, 0.653, 0.842, 0.929, 0.657, 0.835,
+     0.935, 0.659, 0.827, 0.940, 0.662, 0.818, 0.946, 0.663, 0.810, 0.951,
+     0.665, 0.800, 0.955, 0.666, 0.790, 0.960, 0.666, 0.780, 0.964, 0.666,
+     0.769, 0.967, 0.666, 0.757, 0.971, 0.665, 0.745, 0.974, 0.663, 0.732,
+     0.976, 0.662, 0.718, 0.978, 0.659, 0.704, 0.980, 0.657, 0.689, 0.981,
+     0.654, 0.674, 0.982, 0.650, 0.658, 0.983, 0.646, 0.642, 0.983, 0.642,
+     0.625, 0.983, 0.638, 0.608, 0.982, 0.633, 0.590, 0.981, 0.628, 0.572,
+     0.979, 0.623, 0.553, 0.978, 0.618, 0.535, 0.976, 0.612, 0.516, 0.973,
+     0.607, 0.497, 0.971, 0.601, 0.477, 0.968, 0.595, 0.458, 0.965, 0.589,
+     0.438, 0.961, 0.582, 0.418, 0.958, 0.576, 0.398, 0.954, 0.569, 0.378,
+     0.950, 0.563, 0.357, 0.946, 0.556, 0.336, 0.942, 0.549, 0.315, 0.938,
+     0.542, 0.294, 0.933, 0.536, 0.273, 0.928, 0.529, 0.250, 0.924, 0.522,
+     0.228, 0.919, 0.514, 0.204, 0.914, 0.507, 0.179, 0.909, 0.500, 0.153,
+     0.770, 0.488, 0.983, 0.777, 0.498, 0.976, 0.783, 0.507, 0.969, 0.790,
+     0.516, 0.962, 0.797, 0.524, 0.955, 0.804, 0.533, 0.948, 0.811, 0.541,
+     0.942, 0.817, 0.549, 0.936, 0.824, 0.556, 0.930, 0.831, 0.564, 0.924,
+     0.838, 0.571, 0.918, 0.845, 0.578, 0.912, 0.852, 0.584, 0.906, 0.859,
+     0.591, 0.900, 0.866, 0.597, 0.894, 0.873, 0.603, 0.888, 0.879, 0.609,
+     0.882, 0.886, 0.614, 0.876, 0.893, 0.619, 0.869, 0.899, 0.624, 0.863,
+     0.906, 0.629, 0.856, 0.912, 0.633, 0.850, 0.918, 0.637, 0.843, 0.924,
+     0.640, 0.835, 0.930, 0.643, 0.827, 0.935, 0.646, 0.819, 0.941, 0.648,
+     0.811, 0.946, 0.649, 0.802, 0.951, 0.651, 0.792, 0.955, 0.652, 0.782,
+     0.959, 0.652, 0.771, 0.963, 0.652, 0.760, 0.967, 0.652, 0.749, 0.970,
+     0.651, 0.736, 0.973, 0.649, 0.723, 0.976, 0.647, 0.710, 0.978, 0.645,
+     0.696, 0.980, 0.643, 0.681, 0.981, 0.640, 0.666, 0.982, 0.637, 0.650,
+     0.982, 0.633, 0.634, 0.983, 0.629, 0.617, 0.982, 0.625, 0.600, 0.982,
+     0.620, 0.582, 0.981, 0.616, 0.565, 0.979, 0.611, 0.546, 0.978, 0.605,
+     0.528, 0.976, 0.600, 0.509, 0.974, 0.595, 0.490, 0.971, 0.589, 0.471,
+     0.969, 0.583, 0.452, 0.966, 0.577, 0.432, 0.962, 0.571, 0.413, 0.959,
+     0.565, 0.393, 0.955, 0.558, 0.373, 0.952, 0.552, 0.352, 0.948, 0.545,
+     0.332, 0.943, 0.539, 0.311, 0.939, 0.532, 0.290, 0.935, 0.525, 0.268,
+     0.930, 0.518, 0.246, 0.926, 0.511, 0.224, 0.921, 0.504, 0.200, 0.916,
+     0.497, 0.175, 0.911, 0.490, 0.149, 0.775, 0.477, 0.981, 0.781, 0.486,
+     0.974, 0.788, 0.495, 0.966, 0.794, 0.504, 0.959, 0.801, 0.513, 0.952,
+     0.808, 0.521, 0.946, 0.814, 0.529, 0.939, 0.821, 0.537, 0.933, 0.828,
+     0.545, 0.926, 0.835, 0.552, 0.920, 0.841, 0.559, 0.914, 0.848, 0.566,
+     0.908, 0.855, 0.572, 0.901, 0.862, 0.579, 0.895, 0.868, 0.585, 0.889,
+     0.875, 0.591, 0.883, 0.881, 0.596, 0.877, 0.888, 0.601, 0.870, 0.894,
+     0.606, 0.864, 0.901, 0.611, 0.857, 0.907, 0.615, 0.850, 0.913, 0.619,
+     0.843, 0.919, 0.623, 0.836, 0.925, 0.626, 0.828, 0.930, 0.629, 0.820,
+     0.936, 0.632, 0.812, 0.941, 0.634, 0.803, 0.946, 0.635, 0.794, 0.951,
+     0.637, 0.784, 0.955, 0.637, 0.774, 0.959, 0.638, 0.763, 0.963, 0.638,
+     0.752, 0.967, 0.637, 0.740, 0.970, 0.636, 0.728, 0.973, 0.635, 0.715,
+     0.975, 0.633, 0.701, 0.977, 0.631, 0.687, 0.979, 0.629, 0.672, 0.980,
+     0.626, 0.657, 0.981, 0.623, 0.642, 0.982, 0.619, 0.626, 0.982, 0.616,
+     0.609, 0.982, 0.612, 0.592, 0.981, 0.607, 0.575, 0.981, 0.603, 0.557,
+     0.979, 0.598, 0.540, 0.978, 0.593, 0.521, 0.976, 0.588, 0.503, 0.974,
+     0.582, 0.484, 0.972, 0.577, 0.465, 0.969, 0.571, 0.446, 0.966, 0.565,
+     0.427, 0.963, 0.559, 0.407, 0.960, 0.553, 0.387, 0.956, 0.547, 0.368,
+     0.953, 0.541, 0.347, 0.949, 0.534, 0.327, 0.945, 0.528, 0.306, 0.941,
+     0.521, 0.285, 0.936, 0.514, 0.264, 0.932, 0.508, 0.242, 0.927, 0.501,
+     0.220, 0.922, 0.494, 0.196, 0.918, 0.487, 0.172, 0.913, 0.480, 0.145,
+     0.779, 0.465, 0.979, 0.785, 0.474, 0.971, 0.792, 0.484, 0.964, 0.798,
+     0.492, 0.957, 0.805, 0.501, 0.950, 0.811, 0.509, 0.943, 0.818, 0.517,
+     0.936, 0.824, 0.525, 0.929, 0.831, 0.533, 0.923, 0.838, 0.540, 0.916,
+     0.844, 0.547, 0.910, 0.851, 0.554, 0.904, 0.857, 0.560, 0.897, 0.864,
+     0.566, 0.891, 0.870, 0.572, 0.884, 0.877, 0.578, 0.878, 0.883, 0.583,
+     0.871, 0.890, 0.589, 0.865, 0.896, 0.593, 0.858, 0.902, 0.598, 0.851,
+     0.908, 0.602, 0.844, 0.914, 0.606, 0.837, 0.920, 0.609, 0.829, 0.925,
+     0.613, 0.821, 0.931, 0.615, 0.813, 0.936, 0.618, 0.804, 0.941, 0.620,
+     0.795, 0.946, 0.621, 0.786, 0.950, 0.622, 0.776, 0.955, 0.623, 0.765,
+     0.959, 0.624, 0.755, 0.963, 0.624, 0.743, 0.966, 0.623, 0.731, 0.969,
+     0.622, 0.719, 0.972, 0.621, 0.706, 0.974, 0.619, 0.693, 0.976, 0.617,
+     0.679, 0.978, 0.615, 0.664, 0.979, 0.612, 0.649, 0.980, 0.609, 0.634,
+     0.981, 0.606, 0.618, 0.981, 0.602, 0.601, 0.981, 0.598, 0.585, 0.981,
+     0.594, 0.568, 0.980, 0.590, 0.550, 0.979, 0.585, 0.533, 0.978, 0.580,
+     0.515, 0.976, 0.575, 0.496, 0.974, 0.570, 0.478, 0.972, 0.565, 0.459,
+     0.969, 0.559, 0.440, 0.967, 0.553, 0.421, 0.964, 0.547, 0.402, 0.960,
+     0.542, 0.382, 0.957, 0.535, 0.362, 0.953, 0.529, 0.342, 0.950, 0.523,
+     0.322, 0.946, 0.517, 0.302, 0.942, 0.510, 0.281, 0.937, 0.504, 0.260,
+     0.933, 0.497, 0.238, 0.929, 0.490, 0.216, 0.924, 0.484, 0.192, 0.919,
+     0.477, 0.168, 0.914, 0.470, 0.141, 0.783, 0.453, 0.977, 0.789, 0.462,
+     0.969, 0.796, 0.471, 0.962, 0.802, 0.480, 0.954, 0.808, 0.489, 0.947,
+     0.815, 0.497, 0.940, 0.821, 0.505, 0.933, 0.828, 0.513, 0.926, 0.834,
+     0.520, 0.919, 0.840, 0.527, 0.913, 0.847, 0.534, 0.906, 0.853, 0.541,
+     0.899, 0.860, 0.548, 0.893, 0.866, 0.554, 0.886, 0.873, 0.560, 0.880,
+     0.879, 0.565, 0.873, 0.885, 0.570, 0.866, 0.891, 0.575, 0.859, 0.897,
+     0.580, 0.852, 0.903, 0.585, 0.845, 0.909, 0.589, 0.838, 0.915, 0.592,
+     0.830, 0.921, 0.596, 0.822, 0.926, 0.599, 0.814, 0.931, 0.601, 0.805,
+     0.936, 0.604, 0.797, 0.941, 0.606, 0.787, 0.946, 0.607, 0.778, 0.950,
+     0.608, 0.768, 0.955, 0.609, 0.757, 0.958, 0.609, 0.746, 0.962, 0.609,
+     0.735, 0.965, 0.609, 0.723, 0.968, 0.608, 0.710, 0.971, 0.607, 0.698,
+     0.974, 0.605, 0.684, 0.976, 0.603, 0.670, 0.977, 0.601, 0.656, 0.979,
+     0.598, 0.641, 0.980, 0.596, 0.626, 0.980, 0.592, 0.610, 0.981, 0.589,
+     0.594, 0.981, 0.585, 0.577, 0.980, 0.581, 0.560, 0.980, 0.577, 0.543,
+     0.979, 0.572, 0.526, 0.977, 0.568, 0.508, 0.976, 0.563, 0.490, 0.974,
+     0.558, 0.471, 0.972, 0.552, 0.453, 0.969, 0.547, 0.434, 0.967, 0.541,
+     0.415, 0.964, 0.536, 0.396, 0.961, 0.530, 0.377, 0.958, 0.524, 0.357,
+     0.954, 0.518, 0.337, 0.950, 0.512, 0.317, 0.947, 0.505, 0.297, 0.943,
+     0.499, 0.276, 0.938, 0.493, 0.255, 0.934, 0.486, 0.234, 0.930, 0.480,
+     0.211, 0.925, 0.473, 0.188, 0.920, 0.466, 0.164, 0.916, 0.459, 0.137,
+     0.787, 0.440, 0.975, 0.793, 0.450, 0.967, 0.799, 0.459, 0.959, 0.806,
+     0.468, 0.952, 0.812, 0.476, 0.944, 0.818, 0.485, 0.937, 0.824, 0.493,
+     0.930, 0.831, 0.500, 0.923, 0.837, 0.508, 0.916, 0.843, 0.515, 0.909,
+     0.850, 0.522, 0.902, 0.856, 0.528, 0.895, 0.862, 0.535, 0.888, 0.868,
+     0.541, 0.881, 0.874, 0.547, 0.875, 0.881, 0.552, 0.868, 0.887, 0.557,
+     0.861, 0.893, 0.562, 0.853, 0.899, 0.567, 0.846, 0.904, 0.571, 0.839,
+     0.910, 0.575, 0.831, 0.916, 0.579, 0.823, 0.921, 0.582, 0.815, 0.926,
+     0.585, 0.807, 0.932, 0.587, 0.798, 0.937, 0.590, 0.789, 0.941, 0.591,
+     0.780, 0.946, 0.593, 0.770, 0.950, 0.594, 0.760, 0.954, 0.595, 0.749,
+     0.958, 0.595, 0.738, 0.962, 0.595, 0.727, 0.965, 0.595, 0.715, 0.968,
+     0.594, 0.702, 0.970, 0.593, 0.689, 0.973, 0.591, 0.676, 0.975, 0.589,
+     0.662, 0.976, 0.587, 0.648, 0.978, 0.585, 0.633, 0.979, 0.582, 0.618,
+     0.980, 0.579, 0.602, 0.980, 0.575, 0.586, 0.980, 0.572, 0.570, 0.980,
+     0.568, 0.553, 0.979, 0.564, 0.536, 0.978, 0.559, 0.518, 0.977, 0.555,
+     0.501, 0.975, 0.550, 0.483, 0.974, 0.545, 0.465, 0.972, 0.540, 0.447,
+     0.969, 0.535, 0.428, 0.967, 0.529, 0.409, 0.964, 0.524, 0.390, 0.961,
+     0.518, 0.371, 0.958, 0.512, 0.352, 0.954, 0.506, 0.332, 0.951, 0.500,
+     0.312, 0.947, 0.494, 0.292, 0.943, 0.488, 0.272, 0.939, 0.481, 0.251,
+     0.935, 0.475, 0.229, 0.931, 0.469, 0.207, 0.926, 0.462, 0.184, 0.921,
+     0.455, 0.159, 0.917, 0.449, 0.133, 0.791, 0.427, 0.973, 0.797, 0.437,
+     0.964, 0.803, 0.446, 0.957, 0.809, 0.455, 0.949, 0.815, 0.464, 0.941,
+     0.821, 0.472, 0.934, 0.827, 0.480, 0.926, 0.834, 0.488, 0.919, 0.840,
+     0.495, 0.912, 0.846, 0.502, 0.905, 0.852, 0.509, 0.898, 0.858, 0.515,
+     0.891, 0.864, 0.522, 0.884, 0.870, 0.528, 0.877, 0.876, 0.533, 0.870,
+     0.882, 0.539, 0.862, 0.888, 0.544, 0.855, 0.894, 0.549, 0.848, 0.900,
+     0.553, 0.840, 0.906, 0.557, 0.833, 0.911, 0.561, 0.825, 0.916, 0.565,
+     0.817, 0.922, 0.568, 0.808, 0.927, 0.571, 0.800, 0.932, 0.573, 0.791,
+     0.937, 0.575, 0.782, 0.941, 0.577, 0.772, 0.946, 0.579, 0.762, 0.950,
+     0.580, 0.752, 0.954, 0.580, 0.741, 0.958, 0.581, 0.730, 0.961, 0.581,
+     0.718, 0.964, 0.580, 0.706, 0.967, 0.580, 0.694, 0.970, 0.578, 0.681,
+     0.972, 0.577, 0.667, 0.974, 0.575, 0.654, 0.976, 0.573, 0.639, 0.977,
+     0.571, 0.625, 0.978, 0.568, 0.610, 0.979, 0.565, 0.594, 0.979, 0.562,
+     0.578, 0.979, 0.558, 0.562, 0.979, 0.554, 0.545, 0.978, 0.550, 0.529,
+     0.977, 0.546, 0.511, 0.976, 0.542, 0.494, 0.975, 0.537, 0.476, 0.973,
+     0.532, 0.458, 0.971, 0.527, 0.440, 0.969, 0.522, 0.422, 0.967, 0.517,
+     0.403, 0.964, 0.511, 0.385, 0.961, 0.506, 0.366, 0.958, 0.500, 0.347,
+     0.955, 0.494, 0.327, 0.951, 0.488, 0.307, 0.947, 0.482, 0.287, 0.944,
+     0.476, 0.267, 0.940, 0.470, 0.246, 0.935, 0.464, 0.225, 0.931, 0.458,
+     0.203, 0.927, 0.451, 0.180, 0.922, 0.445, 0.155, 0.917, 0.438, 0.129,
+     0.795, 0.413, 0.970, 0.801, 0.423, 0.962, 0.807, 0.433, 0.954, 0.813,
+     0.442, 0.946, 0.818, 0.450, 0.938, 0.824, 0.459, 0.930, 0.830, 0.467,
+     0.923, 0.836, 0.474, 0.915, 0.842, 0.482, 0.908, 0.848, 0.489, 0.901,
+     0.854, 0.496, 0.894, 0.860, 0.502, 0.886, 0.866, 0.508, 0.879, 0.872,
+     0.514, 0.872, 0.878, 0.520, 0.864, 0.884, 0.525, 0.857, 0.890, 0.530,
+     0.850, 0.895, 0.535, 0.842, 0.901, 0.539, 0.834, 0.906, 0.543, 0.826,
+     0.912, 0.547, 0.818, 0.917, 0.551, 0.810, 0.922, 0.554, 0.801, 0.927,
+     0.557, 0.793, 0.932, 0.559, 0.783, 0.937, 0.561, 0.774, 0.941, 0.563,
+     0.764, 0.946, 0.564, 0.754, 0.950, 0.565, 0.744, 0.953, 0.566, 0.733,
+     0.957, 0.566, 0.722, 0.960, 0.566, 0.710, 0.963, 0.566, 0.698, 0.966,
+     0.565, 0.685, 0.969, 0.564, 0.673, 0.971, 0.563, 0.659, 0.973, 0.561,
+     0.645, 0.975, 0.559, 0.631, 0.976, 0.557, 0.617, 0.977, 0.554, 0.602,
+     0.978, 0.551, 0.586, 0.978, 0.548, 0.571, 0.978, 0.545, 0.554, 0.978,
+     0.541, 0.538, 0.977, 0.537, 0.521, 0.977, 0.533, 0.504, 0.976, 0.529,
+     0.487, 0.974, 0.524, 0.470, 0.973, 0.519, 0.452, 0.971, 0.515, 0.434,
+     0.969, 0.510, 0.416, 0.966, 0.504, 0.398, 0.964, 0.499, 0.379, 0.961,
+     0.494, 0.360, 0.958, 0.488, 0.341, 0.955, 0.482, 0.322, 0.951, 0.477,
+     0.302, 0.948, 0.471, 0.283, 0.944, 0.465, 0.262, 0.940, 0.459, 0.242,
+     0.936, 0.452, 0.220, 0.932, 0.446, 0.198, 0.927, 0.440, 0.175, 0.923,
+     0.434, 0.151, 0.918, 0.427, 0.124, 0.799, 0.399, 0.968, 0.804, 0.409,
+     0.959, 0.810, 0.419, 0.951, 0.816, 0.428, 0.943, 0.822, 0.437, 0.935,
+     0.827, 0.445, 0.927, 0.833, 0.453, 0.919, 0.839, 0.461, 0.912, 0.845,
+     0.468, 0.904, 0.851, 0.475, 0.897, 0.857, 0.482, 0.889, 0.862, 0.489,
+     0.882, 0.868, 0.495, 0.874, 0.874, 0.501, 0.867, 0.880, 0.506, 0.859,
+     0.885, 0.511, 0.852, 0.891, 0.516, 0.844, 0.897, 0.521, 0.836, 0.902,
+     0.525, 0.828, 0.907, 0.529, 0.820, 0.913, 0.533, 0.812, 0.918, 0.537,
+     0.803, 0.923, 0.540, 0.794, 0.928, 0.542, 0.785, 0.932, 0.545, 0.776,
+     0.937, 0.547, 0.767, 0.941, 0.549, 0.757, 0.945, 0.550, 0.747, 0.949,
+     0.551, 0.736, 0.953, 0.552, 0.725, 0.956, 0.552, 0.714, 0.960, 0.552,
+     0.702, 0.963, 0.552, 0.690, 0.965, 0.551, 0.677, 0.968, 0.550, 0.664,
+     0.970, 0.549, 0.651, 0.972, 0.547, 0.637, 0.974, 0.545, 0.623, 0.975,
+     0.543, 0.609, 0.976, 0.540, 0.594, 0.977, 0.537, 0.578, 0.977, 0.534,
+     0.563, 0.977, 0.531, 0.547, 0.977, 0.527, 0.531, 0.976, 0.524, 0.514,
+     0.976, 0.520, 0.497, 0.975, 0.516, 0.480, 0.973, 0.511, 0.463, 0.972,
+     0.507, 0.446, 0.970, 0.502, 0.428, 0.968, 0.497, 0.410, 0.966, 0.492,
+     0.392, 0.963, 0.487, 0.373, 0.960, 0.481, 0.355, 0.957, 0.476, 0.336,
+     0.954, 0.470, 0.317, 0.951, 0.465, 0.297, 0.947, 0.459, 0.278, 0.944,
+     0.453, 0.258, 0.940, 0.447, 0.237, 0.936, 0.441, 0.216, 0.932, 0.435,
+     0.194, 0.927, 0.429, 0.171, 0.923, 0.422, 0.147, 0.918, 0.416, 0.120,
+     0.802, 0.385, 0.965, 0.808, 0.395, 0.957, 0.813, 0.405, 0.948, 0.819,
+     0.414, 0.940, 0.825, 0.423, 0.932, 0.830, 0.431, 0.924, 0.836, 0.439,
+     0.916, 0.842, 0.447, 0.908, 0.847, 0.454, 0.900, 0.853, 0.462, 0.892,
+     0.859, 0.468, 0.885, 0.864, 0.475, 0.877, 0.870, 0.481, 0.869, 0.876,
+     0.487, 0.862, 0.881, 0.492, 0.854, 0.887, 0.498, 0.846, 0.892, 0.502,
+     0.838, 0.898, 0.507, 0.830, 0.903, 0.511, 0.822, 0.908, 0.515, 0.814,
+     0.913, 0.519, 0.805, 0.918, 0.522, 0.797, 0.923, 0.525, 0.788, 0.928,
+     0.528, 0.778, 0.932, 0.530, 0.769, 0.937, 0.532, 0.759, 0.941, 0.534,
+     0.749, 0.945, 0.535, 0.739, 0.949, 0.536, 0.728, 0.952, 0.537, 0.717,
+     0.956, 0.537, 0.706, 0.959, 0.537, 0.694, 0.962, 0.537, 0.682, 0.964,
+     0.536, 0.669, 0.967, 0.536, 0.656, 0.969, 0.534, 0.643, 0.971, 0.533,
+     0.629, 0.972, 0.531, 0.615, 0.974, 0.529, 0.601, 0.975, 0.526, 0.586,
+     0.975, 0.523, 0.571, 0.976, 0.521, 0.555, 0.976, 0.517, 0.540, 0.976,
+     0.514, 0.523, 0.975, 0.510, 0.507, 0.975, 0.506, 0.490, 0.974, 0.502,
+     0.474, 0.972, 0.498, 0.456, 0.971, 0.494, 0.439, 0.969, 0.489, 0.421,
+     0.967, 0.484, 0.404, 0.965, 0.479, 0.386, 0.963, 0.474, 0.367, 0.960,
+     0.469, 0.349, 0.957, 0.464, 0.330, 0.954, 0.458, 0.311, 0.951, 0.453,
+     0.292, 0.947, 0.447, 0.273, 0.944, 0.441, 0.253, 0.940, 0.435, 0.232,
+     0.936, 0.429, 0.211, 0.932, 0.423, 0.190, 0.927, 0.417, 0.167, 0.923,
+     0.411, 0.142, 0.919, 0.405, 0.116, 0.806, 0.370, 0.963, 0.811, 0.380,
+     0.954, 0.816, 0.390, 0.945, 0.822, 0.399, 0.937, 0.827, 0.408, 0.929,
+     0.833, 0.417, 0.920, 0.838, 0.425, 0.912, 0.844, 0.433, 0.904, 0.850,
+     0.440, 0.896, 0.855, 0.447, 0.888, 0.861, 0.454, 0.880, 0.866, 0.461,
+     0.872, 0.872, 0.467, 0.865, 0.877, 0.473, 0.857, 0.883, 0.478, 0.849,
+     0.888, 0.483, 0.841, 0.893, 0.488, 0.833, 0.899, 0.493, 0.824, 0.904,
+     0.497, 0.816, 0.909, 0.501, 0.807, 0.914, 0.505, 0.799, 0.919, 0.508,
+     0.790, 0.923, 0.511, 0.781, 0.928, 0.514, 0.771, 0.932, 0.516, 0.762,
+     0.937, 0.518, 0.752, 0.941, 0.520, 0.742, 0.945, 0.521, 0.731, 0.948,
+     0.522, 0.720, 0.952, 0.523, 0.709, 0.955, 0.523, 0.698, 0.958, 0.523,
+     0.686, 0.961, 0.523, 0.674, 0.964, 0.522, 0.661, 0.966, 0.521, 0.648,
+     0.968, 0.520, 0.635, 0.970, 0.518, 0.621, 0.971, 0.517, 0.607, 0.972,
+     0.514, 0.593, 0.973, 0.512, 0.578, 0.974, 0.509, 0.563, 0.975, 0.507,
+     0.548, 0.975, 0.503, 0.532, 0.975, 0.500, 0.516, 0.974, 0.497, 0.500,
+     0.974, 0.493, 0.483, 0.973, 0.489, 0.467, 0.971, 0.485, 0.450, 0.970,
+     0.480, 0.433, 0.968, 0.476, 0.415, 0.966, 0.471, 0.397, 0.964, 0.466,
+     0.380, 0.962, 0.461, 0.362, 0.959, 0.456, 0.343, 0.956, 0.451, 0.325,
+     0.953, 0.446, 0.306, 0.950, 0.440, 0.287, 0.947, 0.435, 0.268, 0.943,
+     0.429, 0.248, 0.939, 0.423, 0.228, 0.936, 0.417, 0.207, 0.931, 0.411,
+     0.185, 0.927, 0.405, 0.162, 0.923, 0.399, 0.138, 0.918, 0.393, 0.111,
+     0.809, 0.354, 0.960, 0.814, 0.364, 0.951, 0.819, 0.375, 0.942, 0.825,
+     0.384, 0.934, 0.830, 0.393, 0.925, 0.835, 0.402, 0.917, 0.841, 0.410,
+     0.908, 0.846, 0.418, 0.900, 0.852, 0.426, 0.892, 0.857, 0.433, 0.884,
+     0.863, 0.440, 0.876, 0.868, 0.446, 0.868, 0.873, 0.452, 0.860, 0.879,
+     0.458, 0.852, 0.884, 0.464, 0.843, 0.889, 0.469, 0.835, 0.894, 0.474,
+     0.827, 0.899, 0.478, 0.818, 0.904, 0.483, 0.810, 0.909, 0.486, 0.801,
+     0.914, 0.490, 0.792, 0.919, 0.493, 0.783, 0.923, 0.496, 0.774, 0.928,
+     0.499, 0.764, 0.932, 0.501, 0.755, 0.936, 0.503, 0.745, 0.940, 0.505,
+     0.734, 0.944, 0.506, 0.724, 0.948, 0.507, 0.713, 0.951, 0.508, 0.701,
+     0.954, 0.508, 0.690, 0.957, 0.508, 0.678, 0.960, 0.508, 0.666, 0.962,
+     0.507, 0.653, 0.965, 0.507, 0.640, 0.967, 0.505, 0.627, 0.968, 0.504,
+     0.613, 0.970, 0.502, 0.599, 0.971, 0.500, 0.585, 0.972, 0.498, 0.570,
+     0.973, 0.495, 0.555, 0.973, 0.493, 0.540, 0.973, 0.490, 0.525, 0.973,
+     0.486, 0.509, 0.973, 0.483, 0.493, 0.972, 0.479, 0.476, 0.971, 0.475,
+     0.460, 0.970, 0.471, 0.443, 0.969, 0.467, 0.426, 0.967, 0.463, 0.409,
+     0.965, 0.458, 0.391, 0.963, 0.453, 0.374, 0.961, 0.449, 0.356, 0.958,
+     0.444, 0.338, 0.956, 0.438, 0.319, 0.953, 0.433, 0.301, 0.949, 0.428,
+     0.282, 0.946, 0.422, 0.263, 0.943, 0.417, 0.243, 0.939, 0.411, 0.223,
+     0.935, 0.405, 0.202, 0.931, 0.399, 0.181, 0.927, 0.393, 0.158, 0.923,
+     0.387, 0.134, 0.918, 0.381, 0.107,
+     ]).reshape((65, 65, 3))
+
+BiOrangeBlue = np.array(
+    [0.000, 0.000, 0.000, 0.000, 0.062, 0.125, 0.000, 0.125, 0.250, 0.000,
+     0.188, 0.375, 0.000, 0.250, 0.500, 0.000, 0.312, 0.625, 0.000, 0.375,
+     0.750, 0.000, 0.438, 0.875, 0.000, 0.500, 1.000, 0.125, 0.062, 0.000,
+     0.125, 0.125, 0.125, 0.125, 0.188, 0.250, 0.125, 0.250, 0.375, 0.125,
+     0.312, 0.500, 0.125, 0.375, 0.625, 0.125, 0.438, 0.750, 0.125, 0.500,
+     0.875, 0.125, 0.562, 1.000, 0.250, 0.125, 0.000, 0.250, 0.188, 0.125,
+     0.250, 0.250, 0.250, 0.250, 0.312, 0.375, 0.250, 0.375, 0.500, 0.250,
+     0.438, 0.625, 0.250, 0.500, 0.750, 0.250, 0.562, 0.875, 0.250, 0.625,
+     1.000, 0.375, 0.188, 0.000, 0.375, 0.250, 0.125, 0.375, 0.312, 0.250,
+     0.375, 0.375, 0.375, 0.375, 0.438, 0.500, 0.375, 0.500, 0.625, 0.375,
+     0.562, 0.750, 0.375, 0.625, 0.875, 0.375, 0.688, 1.000, 0.500, 0.250,
+     0.000, 0.500, 0.312, 0.125, 0.500, 0.375, 0.250, 0.500, 0.438, 0.375,
+     0.500, 0.500, 0.500, 0.500, 0.562, 0.625, 0.500, 0.625, 0.750, 0.500,
+     0.688, 0.875, 0.500, 0.750, 1.000, 0.625, 0.312, 0.000, 0.625, 0.375,
+     0.125, 0.625, 0.438, 0.250, 0.625, 0.500, 0.375, 0.625, 0.562, 0.500,
+     0.625, 0.625, 0.625, 0.625, 0.688, 0.750, 0.625, 0.750, 0.875, 0.625,
+     0.812, 1.000, 0.750, 0.375, 0.000, 0.750, 0.438, 0.125, 0.750, 0.500,
+     0.250, 0.750, 0.562, 0.375, 0.750, 0.625, 0.500, 0.750, 0.688, 0.625,
+     0.750, 0.750, 0.750, 0.750, 0.812, 0.875, 0.750, 0.875, 1.000, 0.875,
+     0.438, 0.000, 0.875, 0.500, 0.125, 0.875, 0.562, 0.250, 0.875, 0.625,
+     0.375, 0.875, 0.688, 0.500, 0.875, 0.750, 0.625, 0.875, 0.812, 0.750,
+     0.875, 0.875, 0.875, 0.875, 0.938, 1.000, 1.000, 0.500, 0.000, 1.000,
+     0.562, 0.125, 1.000, 0.625, 0.250, 1.000, 0.688, 0.375, 1.000, 0.750,
+     0.500, 1.000, 0.812, 0.625, 1.000, 0.875, 0.750, 1.000, 0.938, 0.875,
+     1.000, 1.000, 1.000,
+     ]).reshape((9, 9, 3))
+
+cmaps = {
+    "BiPeak": SegmentedBivarColormap(
+        BiPeak, 256, "square", (.5, .5), name="BiPeak"),
+    "BiOrangeBlue": SegmentedBivarColormap(
+        BiOrangeBlue, 256, "square", (0, 0), name="BiOrangeBlue"),
+    "BiCone": SegmentedBivarColormap(BiPeak, 256, "circle", (.5, .5), name="BiCone"),
+}
diff --git a/lib/python3.12/site-packages/matplotlib/_cm_multivar.py b/lib/python3.12/site-packages/matplotlib/_cm_multivar.py
new file mode 100644
index 0000000000000000000000000000000000000000..610d7c40935b0999fe7de38515f316ce816023f7
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_cm_multivar.py
@@ -0,0 +1,166 @@
+# auto-generated by https://github.com/trygvrad/multivariate_colormaps
+# date: 2024-05-28
+
+from .colors import LinearSegmentedColormap, MultivarColormap
+import matplotlib as mpl
+_LUTSIZE = mpl.rcParams['image.lut']
+
+_2VarAddA0_data = [[0.000, 0.000, 0.000],
+                   [0.020, 0.026, 0.031],
+                   [0.049, 0.068, 0.085],
+                   [0.075, 0.107, 0.135],
+                   [0.097, 0.144, 0.183],
+                   [0.116, 0.178, 0.231],
+                   [0.133, 0.212, 0.279],
+                   [0.148, 0.244, 0.326],
+                   [0.161, 0.276, 0.374],
+                   [0.173, 0.308, 0.422],
+                   [0.182, 0.339, 0.471],
+                   [0.190, 0.370, 0.521],
+                   [0.197, 0.400, 0.572],
+                   [0.201, 0.431, 0.623],
+                   [0.204, 0.461, 0.675],
+                   [0.204, 0.491, 0.728],
+                   [0.202, 0.520, 0.783],
+                   [0.197, 0.549, 0.838],
+                   [0.187, 0.577, 0.895]]
+
+_2VarAddA1_data = [[0.000, 0.000, 0.000],
+                   [0.030, 0.023, 0.018],
+                   [0.079, 0.060, 0.043],
+                   [0.125, 0.093, 0.065],
+                   [0.170, 0.123, 0.083],
+                   [0.213, 0.151, 0.098],
+                   [0.255, 0.177, 0.110],
+                   [0.298, 0.202, 0.120],
+                   [0.341, 0.226, 0.128],
+                   [0.384, 0.249, 0.134],
+                   [0.427, 0.271, 0.138],
+                   [0.472, 0.292, 0.141],
+                   [0.517, 0.313, 0.142],
+                   [0.563, 0.333, 0.141],
+                   [0.610, 0.353, 0.139],
+                   [0.658, 0.372, 0.134],
+                   [0.708, 0.390, 0.127],
+                   [0.759, 0.407, 0.118],
+                   [0.813, 0.423, 0.105]]
+
+_2VarSubA0_data = [[1.000, 1.000, 1.000],
+                   [0.959, 0.973, 0.986],
+                   [0.916, 0.948, 0.974],
+                   [0.874, 0.923, 0.965],
+                   [0.832, 0.899, 0.956],
+                   [0.790, 0.875, 0.948],
+                   [0.748, 0.852, 0.940],
+                   [0.707, 0.829, 0.934],
+                   [0.665, 0.806, 0.927],
+                   [0.624, 0.784, 0.921],
+                   [0.583, 0.762, 0.916],
+                   [0.541, 0.740, 0.910],
+                   [0.500, 0.718, 0.905],
+                   [0.457, 0.697, 0.901],
+                   [0.414, 0.675, 0.896],
+                   [0.369, 0.652, 0.892],
+                   [0.320, 0.629, 0.888],
+                   [0.266, 0.604, 0.884],
+                   [0.199, 0.574, 0.881]]
+
+_2VarSubA1_data = [[1.000, 1.000, 1.000],
+                   [0.982, 0.967, 0.955],
+                   [0.966, 0.935, 0.908],
+                   [0.951, 0.902, 0.860],
+                   [0.937, 0.870, 0.813],
+                   [0.923, 0.838, 0.765],
+                   [0.910, 0.807, 0.718],
+                   [0.898, 0.776, 0.671],
+                   [0.886, 0.745, 0.624],
+                   [0.874, 0.714, 0.577],
+                   [0.862, 0.683, 0.530],
+                   [0.851, 0.653, 0.483],
+                   [0.841, 0.622, 0.435],
+                   [0.831, 0.592, 0.388],
+                   [0.822, 0.561, 0.340],
+                   [0.813, 0.530, 0.290],
+                   [0.806, 0.498, 0.239],
+                   [0.802, 0.464, 0.184],
+                   [0.801, 0.426, 0.119]]
+
+_3VarAddA0_data = [[0.000, 0.000, 0.000],
+                   [0.018, 0.023, 0.028],
+                   [0.040, 0.056, 0.071],
+                   [0.059, 0.087, 0.110],
+                   [0.074, 0.114, 0.147],
+                   [0.086, 0.139, 0.183],
+                   [0.095, 0.163, 0.219],
+                   [0.101, 0.187, 0.255],
+                   [0.105, 0.209, 0.290],
+                   [0.107, 0.230, 0.326],
+                   [0.105, 0.251, 0.362],
+                   [0.101, 0.271, 0.398],
+                   [0.091, 0.291, 0.434],
+                   [0.075, 0.309, 0.471],
+                   [0.046, 0.325, 0.507],
+                   [0.021, 0.341, 0.546],
+                   [0.021, 0.363, 0.584],
+                   [0.022, 0.385, 0.622],
+                   [0.023, 0.408, 0.661]]
+
+_3VarAddA1_data = [[0.000, 0.000, 0.000],
+                   [0.020, 0.024, 0.016],
+                   [0.047, 0.058, 0.034],
+                   [0.072, 0.088, 0.048],
+                   [0.093, 0.116, 0.059],
+                   [0.113, 0.142, 0.067],
+                   [0.131, 0.167, 0.071],
+                   [0.149, 0.190, 0.074],
+                   [0.166, 0.213, 0.074],
+                   [0.182, 0.235, 0.072],
+                   [0.198, 0.256, 0.068],
+                   [0.215, 0.276, 0.061],
+                   [0.232, 0.296, 0.051],
+                   [0.249, 0.314, 0.037],
+                   [0.270, 0.330, 0.018],
+                   [0.288, 0.347, 0.000],
+                   [0.302, 0.369, 0.000],
+                   [0.315, 0.391, 0.000],
+                   [0.328, 0.414, 0.000]]
+
+_3VarAddA2_data = [[0.000, 0.000, 0.000],
+                   [0.029, 0.020, 0.023],
+                   [0.072, 0.045, 0.055],
+                   [0.111, 0.067, 0.084],
+                   [0.148, 0.085, 0.109],
+                   [0.184, 0.101, 0.133],
+                   [0.219, 0.115, 0.155],
+                   [0.254, 0.127, 0.176],
+                   [0.289, 0.138, 0.195],
+                   [0.323, 0.147, 0.214],
+                   [0.358, 0.155, 0.232],
+                   [0.393, 0.161, 0.250],
+                   [0.429, 0.166, 0.267],
+                   [0.467, 0.169, 0.283],
+                   [0.507, 0.168, 0.298],
+                   [0.546, 0.168, 0.313],
+                   [0.580, 0.172, 0.328],
+                   [0.615, 0.175, 0.341],
+                   [0.649, 0.178, 0.355]]
+
+cmaps = {
+    name: LinearSegmentedColormap.from_list(name, data, _LUTSIZE) for name, data in [
+        ('2VarAddA0', _2VarAddA0_data),
+        ('2VarAddA1', _2VarAddA1_data),
+        ('2VarSubA0', _2VarSubA0_data),
+        ('2VarSubA1', _2VarSubA1_data),
+        ('3VarAddA0', _3VarAddA0_data),
+        ('3VarAddA1', _3VarAddA1_data),
+        ('3VarAddA2', _3VarAddA2_data),
+    ]}
+
+cmap_families = {
+    '2VarAddA': MultivarColormap([cmaps[f'2VarAddA{i}'] for i in range(2)],
+                                 'sRGB_add', name='2VarAddA'),
+    '2VarSubA': MultivarColormap([cmaps[f'2VarSubA{i}'] for i in range(2)],
+                                 'sRGB_sub', name='2VarSubA'),
+    '3VarAddA': MultivarColormap([cmaps[f'3VarAddA{i}'] for i in range(3)],
+                                 'sRGB_add', name='3VarAddA'),
+}
diff --git a/lib/python3.12/site-packages/matplotlib/_color_data.pyi b/lib/python3.12/site-packages/matplotlib/_color_data.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..feb3de9c3043d55910e2649804352ae96ccbd1ec
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_color_data.pyi
@@ -0,0 +1,6 @@
+from .typing import ColorType
+
+BASE_COLORS: dict[str, ColorType]
+TABLEAU_COLORS: dict[str, ColorType]
+XKCD_COLORS: dict[str, ColorType]
+CSS4_COLORS: dict[str, ColorType]
diff --git a/lib/python3.12/site-packages/matplotlib/_constrained_layout.py b/lib/python3.12/site-packages/matplotlib/_constrained_layout.py
new file mode 100644
index 0000000000000000000000000000000000000000..5623e12a3c41d0d0d35041fd1dd9fb23e9938e51
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_constrained_layout.py
@@ -0,0 +1,801 @@
+"""
+Adjust subplot layouts so that there are no overlapping Axes or Axes
+decorations.  All Axes decorations are dealt with (labels, ticks, titles,
+ticklabels) and some dependent artists are also dealt with (colorbar,
+suptitle).
+
+Layout is done via `~matplotlib.gridspec`, with one constraint per gridspec,
+so it is possible to have overlapping Axes if the gridspecs overlap (i.e.
+using `~matplotlib.gridspec.GridSpecFromSubplotSpec`).  Axes placed using
+``figure.subplots()`` or ``figure.add_subplots()`` will participate in the
+layout.  Axes manually placed via ``figure.add_axes()`` will not.
+
+See Tutorial: :ref:`constrainedlayout_guide`
+
+General idea:
+-------------
+
+First, a figure has a gridspec that divides the figure into nrows and ncols,
+with heights and widths set by ``height_ratios`` and ``width_ratios``,
+often just set to 1 for an equal grid.
+
+Subplotspecs that are derived from this gridspec can contain either a
+``SubPanel``, a ``GridSpecFromSubplotSpec``, or an ``Axes``.  The ``SubPanel``
+and ``GridSpecFromSubplotSpec`` are dealt with recursively and each contain an
+analogous layout.
+
+Each ``GridSpec`` has a ``_layoutgrid`` attached to it.  The ``_layoutgrid``
+has the same logical layout as the ``GridSpec``.   Each row of the grid spec
+has a top and bottom "margin" and each column has a left and right "margin".
+The "inner" height of each row is constrained to be the same (or as modified
+by ``height_ratio``), and the "inner" width of each column is
+constrained to be the same (as modified by ``width_ratio``), where "inner"
+is the width or height of each column/row minus the size of the margins.
+
+Then the size of the margins for each row and column are determined as the
+max width of the decorators on each Axes that has decorators in that margin.
+For instance, a normal Axes would have a left margin that includes the
+left ticklabels, and the ylabel if it exists.  The right margin may include a
+colorbar, the bottom margin the xaxis decorations, and the top margin the
+title.
+
+With these constraints, the solver then finds appropriate bounds for the
+columns and rows.  It's possible that the margins take up the whole figure,
+in which case the algorithm is not applied and a warning is raised.
+
+See the tutorial :ref:`constrainedlayout_guide`
+for more discussion of the algorithm with examples.
+"""
+
+import logging
+
+import numpy as np
+
+from matplotlib import _api, artist as martist
+import matplotlib.transforms as mtransforms
+import matplotlib._layoutgrid as mlayoutgrid
+
+
+_log = logging.getLogger(__name__)
+
+
+######################################################
+def do_constrained_layout(fig, h_pad, w_pad,
+                          hspace=None, wspace=None, rect=(0, 0, 1, 1),
+                          compress=False):
+    """
+    Do the constrained_layout.  Called at draw time in
+     ``figure.constrained_layout()``
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        `.Figure` instance to do the layout in.
+
+    h_pad, w_pad : float
+      Padding around the Axes elements in figure-normalized units.
+
+    hspace, wspace : float
+       Fraction of the figure to dedicate to space between the
+       Axes.  These are evenly spread between the gaps between the Axes.
+       A value of 0.2 for a three-column layout would have a space
+       of 0.1 of the figure width between each column.
+       If h/wspace < h/w_pad, then the pads are used instead.
+
+    rect : tuple of 4 floats
+        Rectangle in figure coordinates to perform constrained layout in
+        [left, bottom, width, height], each from 0-1.
+
+    compress : bool
+        Whether to shift Axes so that white space in between them is
+        removed. This is useful for simple grids of fixed-aspect Axes (e.g.
+        a grid of images).
+
+    Returns
+    -------
+    layoutgrid : private debugging structure
+    """
+
+    renderer = fig._get_renderer()
+    # make layoutgrid tree...
+    layoutgrids = make_layoutgrids(fig, None, rect=rect)
+    if not layoutgrids['hasgrids']:
+        _api.warn_external('There are no gridspecs with layoutgrids. '
+                           'Possibly did not call parent GridSpec with the'
+                           ' "figure" keyword')
+        return
+
+    for _ in range(2):
+        # do the algorithm twice.  This has to be done because decorations
+        # change size after the first re-position (i.e. x/yticklabels get
+        # larger/smaller).  This second reposition tends to be much milder,
+        # so doing twice makes things work OK.
+
+        # make margins for all the Axes and subfigures in the
+        # figure.  Add margins for colorbars...
+        make_layout_margins(layoutgrids, fig, renderer, h_pad=h_pad,
+                            w_pad=w_pad, hspace=hspace, wspace=wspace)
+        make_margin_suptitles(layoutgrids, fig, renderer, h_pad=h_pad,
+                              w_pad=w_pad)
+
+        # if a layout is such that a columns (or rows) margin has no
+        # constraints, we need to make all such instances in the grid
+        # match in margin size.
+        match_submerged_margins(layoutgrids, fig)
+
+        # update all the variables in the layout.
+        layoutgrids[fig].update_variables()
+
+        warn_collapsed = ('constrained_layout not applied because '
+                          'axes sizes collapsed to zero.  Try making '
+                          'figure larger or Axes decorations smaller.')
+        if check_no_collapsed_axes(layoutgrids, fig):
+            reposition_axes(layoutgrids, fig, renderer, h_pad=h_pad,
+                            w_pad=w_pad, hspace=hspace, wspace=wspace)
+            if compress:
+                layoutgrids = compress_fixed_aspect(layoutgrids, fig)
+                layoutgrids[fig].update_variables()
+                if check_no_collapsed_axes(layoutgrids, fig):
+                    reposition_axes(layoutgrids, fig, renderer, h_pad=h_pad,
+                                    w_pad=w_pad, hspace=hspace, wspace=wspace)
+                else:
+                    _api.warn_external(warn_collapsed)
+
+                if ((suptitle := fig._suptitle) is not None and
+                        suptitle.get_in_layout() and suptitle._autopos):
+                    x, _ = suptitle.get_position()
+                    suptitle.set_position(
+                        (x, layoutgrids[fig].get_inner_bbox().y1 + h_pad))
+                    suptitle.set_verticalalignment('bottom')
+        else:
+            _api.warn_external(warn_collapsed)
+        reset_margins(layoutgrids, fig)
+    return layoutgrids
+
+
+def make_layoutgrids(fig, layoutgrids, rect=(0, 0, 1, 1)):
+    """
+    Make the layoutgrid tree.
+
+    (Sub)Figures get a layoutgrid so we can have figure margins.
+
+    Gridspecs that are attached to Axes get a layoutgrid so Axes
+    can have margins.
+    """
+
+    if layoutgrids is None:
+        layoutgrids = dict()
+        layoutgrids['hasgrids'] = False
+    if not hasattr(fig, '_parent'):
+        # top figure;  pass rect as parent to allow user-specified
+        # margins
+        layoutgrids[fig] = mlayoutgrid.LayoutGrid(parent=rect, name='figlb')
+    else:
+        # subfigure
+        gs = fig._subplotspec.get_gridspec()
+        # it is possible the gridspec containing this subfigure hasn't
+        # been added to the tree yet:
+        layoutgrids = make_layoutgrids_gs(layoutgrids, gs)
+        # add the layoutgrid for the subfigure:
+        parentlb = layoutgrids[gs]
+        layoutgrids[fig] = mlayoutgrid.LayoutGrid(
+            parent=parentlb,
+            name='panellb',
+            parent_inner=True,
+            nrows=1, ncols=1,
+            parent_pos=(fig._subplotspec.rowspan,
+                        fig._subplotspec.colspan))
+    # recursively do all subfigures in this figure...
+    for sfig in fig.subfigs:
+        layoutgrids = make_layoutgrids(sfig, layoutgrids)
+
+    # for each Axes at the local level add its gridspec:
+    for ax in fig._localaxes:
+        gs = ax.get_gridspec()
+        if gs is not None:
+            layoutgrids = make_layoutgrids_gs(layoutgrids, gs)
+
+    return layoutgrids
+
+
+def make_layoutgrids_gs(layoutgrids, gs):
+    """
+    Make the layoutgrid for a gridspec (and anything nested in the gridspec)
+    """
+
+    if gs in layoutgrids or gs.figure is None:
+        return layoutgrids
+    # in order to do constrained_layout there has to be at least *one*
+    # gridspec in the tree:
+    layoutgrids['hasgrids'] = True
+    if not hasattr(gs, '_subplot_spec'):
+        # normal gridspec
+        parent = layoutgrids[gs.figure]
+        layoutgrids[gs] = mlayoutgrid.LayoutGrid(
+                parent=parent,
+                parent_inner=True,
+                name='gridspec',
+                ncols=gs._ncols, nrows=gs._nrows,
+                width_ratios=gs.get_width_ratios(),
+                height_ratios=gs.get_height_ratios())
+    else:
+        # this is a gridspecfromsubplotspec:
+        subplot_spec = gs._subplot_spec
+        parentgs = subplot_spec.get_gridspec()
+        # if a nested gridspec it is possible the parent is not in there yet:
+        if parentgs not in layoutgrids:
+            layoutgrids = make_layoutgrids_gs(layoutgrids, parentgs)
+        subspeclb = layoutgrids[parentgs]
+        # gridspecfromsubplotspec need an outer container:
+        # get a unique representation:
+        rep = (gs, 'top')
+        if rep not in layoutgrids:
+            layoutgrids[rep] = mlayoutgrid.LayoutGrid(
+                parent=subspeclb,
+                name='top',
+                nrows=1, ncols=1,
+                parent_pos=(subplot_spec.rowspan, subplot_spec.colspan))
+        layoutgrids[gs] = mlayoutgrid.LayoutGrid(
+                parent=layoutgrids[rep],
+                name='gridspec',
+                nrows=gs._nrows, ncols=gs._ncols,
+                width_ratios=gs.get_width_ratios(),
+                height_ratios=gs.get_height_ratios())
+    return layoutgrids
+
+
+def check_no_collapsed_axes(layoutgrids, fig):
+    """
+    Check that no Axes have collapsed to zero size.
+    """
+    for sfig in fig.subfigs:
+        ok = check_no_collapsed_axes(layoutgrids, sfig)
+        if not ok:
+            return False
+    for ax in fig.axes:
+        gs = ax.get_gridspec()
+        if gs in layoutgrids:  # also implies gs is not None.
+            lg = layoutgrids[gs]
+            for i in range(gs.nrows):
+                for j in range(gs.ncols):
+                    bb = lg.get_inner_bbox(i, j)
+                    if bb.width <= 0 or bb.height <= 0:
+                        return False
+    return True
+
+
+def compress_fixed_aspect(layoutgrids, fig):
+    gs = None
+    for ax in fig.axes:
+        if ax.get_subplotspec() is None:
+            continue
+        ax.apply_aspect()
+        sub = ax.get_subplotspec()
+        _gs = sub.get_gridspec()
+        if gs is None:
+            gs = _gs
+            extraw = np.zeros(gs.ncols)
+            extrah = np.zeros(gs.nrows)
+        elif _gs != gs:
+            raise ValueError('Cannot do compressed layout if Axes are not'
+                             'all from the same gridspec')
+        orig = ax.get_position(original=True)
+        actual = ax.get_position(original=False)
+        dw = orig.width - actual.width
+        if dw > 0:
+            extraw[sub.colspan] = np.maximum(extraw[sub.colspan], dw)
+        dh = orig.height - actual.height
+        if dh > 0:
+            extrah[sub.rowspan] = np.maximum(extrah[sub.rowspan], dh)
+
+    if gs is None:
+        raise ValueError('Cannot do compressed layout if no Axes '
+                         'are part of a gridspec.')
+    w = np.sum(extraw) / 2
+    layoutgrids[fig].edit_margin_min('left', w)
+    layoutgrids[fig].edit_margin_min('right', w)
+
+    h = np.sum(extrah) / 2
+    layoutgrids[fig].edit_margin_min('top', h)
+    layoutgrids[fig].edit_margin_min('bottom', h)
+    return layoutgrids
+
+
+def get_margin_from_padding(obj, *, w_pad=0, h_pad=0,
+                            hspace=0, wspace=0):
+
+    ss = obj._subplotspec
+    gs = ss.get_gridspec()
+
+    if hasattr(gs, 'hspace'):
+        _hspace = (gs.hspace if gs.hspace is not None else hspace)
+        _wspace = (gs.wspace if gs.wspace is not None else wspace)
+    else:
+        _hspace = (gs._hspace if gs._hspace is not None else hspace)
+        _wspace = (gs._wspace if gs._wspace is not None else wspace)
+
+    _wspace = _wspace / 2
+    _hspace = _hspace / 2
+
+    nrows, ncols = gs.get_geometry()
+    # there are two margins for each direction.  The "cb"
+    # margins are for pads and colorbars, the non-"cb" are
+    # for the Axes decorations (labels etc).
+    margin = {'leftcb': w_pad, 'rightcb': w_pad,
+              'bottomcb': h_pad, 'topcb': h_pad,
+              'left': 0, 'right': 0,
+              'top': 0, 'bottom': 0}
+    if _wspace / ncols > w_pad:
+        if ss.colspan.start > 0:
+            margin['leftcb'] = _wspace / ncols
+        if ss.colspan.stop < ncols:
+            margin['rightcb'] = _wspace / ncols
+    if _hspace / nrows > h_pad:
+        if ss.rowspan.stop < nrows:
+            margin['bottomcb'] = _hspace / nrows
+        if ss.rowspan.start > 0:
+            margin['topcb'] = _hspace / nrows
+
+    return margin
+
+
+def make_layout_margins(layoutgrids, fig, renderer, *, w_pad=0, h_pad=0,
+                        hspace=0, wspace=0):
+    """
+    For each Axes, make a margin between the *pos* layoutbox and the
+    *axes* layoutbox be a minimum size that can accommodate the
+    decorations on the axis.
+
+    Then make room for colorbars.
+
+    Parameters
+    ----------
+    layoutgrids : dict
+    fig : `~matplotlib.figure.Figure`
+        `.Figure` instance to do the layout in.
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+        The renderer to use.
+    w_pad, h_pad : float, default: 0
+        Width and height padding (in fraction of figure).
+    hspace, wspace : float, default: 0
+        Width and height padding as fraction of figure size divided by
+        number of columns or rows.
+    """
+    for sfig in fig.subfigs:  # recursively make child panel margins
+        ss = sfig._subplotspec
+        gs = ss.get_gridspec()
+
+        make_layout_margins(layoutgrids, sfig, renderer,
+                            w_pad=w_pad, h_pad=h_pad,
+                            hspace=hspace, wspace=wspace)
+
+        margins = get_margin_from_padding(sfig, w_pad=0, h_pad=0,
+                                          hspace=hspace, wspace=wspace)
+        layoutgrids[gs].edit_outer_margin_mins(margins, ss)
+
+    for ax in fig._localaxes:
+        if not ax.get_subplotspec() or not ax.get_in_layout():
+            continue
+
+        ss = ax.get_subplotspec()
+        gs = ss.get_gridspec()
+
+        if gs not in layoutgrids:
+            return
+
+        margin = get_margin_from_padding(ax, w_pad=w_pad, h_pad=h_pad,
+                                         hspace=hspace, wspace=wspace)
+        pos, bbox = get_pos_and_bbox(ax, renderer)
+        # the margin is the distance between the bounding box of the Axes
+        # and its position (plus the padding from above)
+        margin['left'] += pos.x0 - bbox.x0
+        margin['right'] += bbox.x1 - pos.x1
+        # remember that rows are ordered from top:
+        margin['bottom'] += pos.y0 - bbox.y0
+        margin['top'] += bbox.y1 - pos.y1
+
+        # make margin for colorbars.  These margins go in the
+        # padding margin, versus the margin for Axes decorators.
+        for cbax in ax._colorbars:
+            # note pad is a fraction of the parent width...
+            pad = colorbar_get_pad(layoutgrids, cbax)
+            # colorbars can be child of more than one subplot spec:
+            cbp_rspan, cbp_cspan = get_cb_parent_spans(cbax)
+            loc = cbax._colorbar_info['location']
+            cbpos, cbbbox = get_pos_and_bbox(cbax, renderer)
+            if loc == 'right':
+                if cbp_cspan.stop == ss.colspan.stop:
+                    # only increase if the colorbar is on the right edge
+                    margin['rightcb'] += cbbbox.width + pad
+            elif loc == 'left':
+                if cbp_cspan.start == ss.colspan.start:
+                    # only increase if the colorbar is on the left edge
+                    margin['leftcb'] += cbbbox.width + pad
+            elif loc == 'top':
+                if cbp_rspan.start == ss.rowspan.start:
+                    margin['topcb'] += cbbbox.height + pad
+            else:
+                if cbp_rspan.stop == ss.rowspan.stop:
+                    margin['bottomcb'] += cbbbox.height + pad
+            # If the colorbars are wider than the parent box in the
+            # cross direction
+            if loc in ['top', 'bottom']:
+                if (cbp_cspan.start == ss.colspan.start and
+                        cbbbox.x0 < bbox.x0):
+                    margin['left'] += bbox.x0 - cbbbox.x0
+                if (cbp_cspan.stop == ss.colspan.stop and
+                        cbbbox.x1 > bbox.x1):
+                    margin['right'] += cbbbox.x1 - bbox.x1
+            # or taller:
+            if loc in ['left', 'right']:
+                if (cbp_rspan.stop == ss.rowspan.stop and
+                        cbbbox.y0 < bbox.y0):
+                    margin['bottom'] += bbox.y0 - cbbbox.y0
+                if (cbp_rspan.start == ss.rowspan.start and
+                        cbbbox.y1 > bbox.y1):
+                    margin['top'] += cbbbox.y1 - bbox.y1
+        # pass the new margins down to the layout grid for the solution...
+        layoutgrids[gs].edit_outer_margin_mins(margin, ss)
+
+    # make margins for figure-level legends:
+    for leg in fig.legends:
+        inv_trans_fig = None
+        if leg._outside_loc and leg._bbox_to_anchor is None:
+            if inv_trans_fig is None:
+                inv_trans_fig = fig.transFigure.inverted().transform_bbox
+            bbox = inv_trans_fig(leg.get_tightbbox(renderer))
+            w = bbox.width + 2 * w_pad
+            h = bbox.height + 2 * h_pad
+            legendloc = leg._outside_loc
+            if legendloc == 'lower':
+                layoutgrids[fig].edit_margin_min('bottom', h)
+            elif legendloc == 'upper':
+                layoutgrids[fig].edit_margin_min('top', h)
+            if legendloc == 'right':
+                layoutgrids[fig].edit_margin_min('right', w)
+            elif legendloc == 'left':
+                layoutgrids[fig].edit_margin_min('left', w)
+
+
+def make_margin_suptitles(layoutgrids, fig, renderer, *, w_pad=0, h_pad=0):
+    # Figure out how large the suptitle is and make the
+    # top level figure margin larger.
+
+    inv_trans_fig = fig.transFigure.inverted().transform_bbox
+    # get the h_pad and w_pad as distances in the local subfigure coordinates:
+    padbox = mtransforms.Bbox([[0, 0], [w_pad, h_pad]])
+    padbox = (fig.transFigure -
+              fig.transSubfigure).transform_bbox(padbox)
+    h_pad_local = padbox.height
+    w_pad_local = padbox.width
+
+    for sfig in fig.subfigs:
+        make_margin_suptitles(layoutgrids, sfig, renderer,
+                              w_pad=w_pad, h_pad=h_pad)
+
+    if fig._suptitle is not None and fig._suptitle.get_in_layout():
+        p = fig._suptitle.get_position()
+        if getattr(fig._suptitle, '_autopos', False):
+            fig._suptitle.set_position((p[0], 1 - h_pad_local))
+            bbox = inv_trans_fig(fig._suptitle.get_tightbbox(renderer))
+            layoutgrids[fig].edit_margin_min('top', bbox.height + 2 * h_pad)
+
+    if fig._supxlabel is not None and fig._supxlabel.get_in_layout():
+        p = fig._supxlabel.get_position()
+        if getattr(fig._supxlabel, '_autopos', False):
+            fig._supxlabel.set_position((p[0], h_pad_local))
+            bbox = inv_trans_fig(fig._supxlabel.get_tightbbox(renderer))
+            layoutgrids[fig].edit_margin_min('bottom',
+                                             bbox.height + 2 * h_pad)
+
+    if fig._supylabel is not None and fig._supylabel.get_in_layout():
+        p = fig._supylabel.get_position()
+        if getattr(fig._supylabel, '_autopos', False):
+            fig._supylabel.set_position((w_pad_local, p[1]))
+            bbox = inv_trans_fig(fig._supylabel.get_tightbbox(renderer))
+            layoutgrids[fig].edit_margin_min('left', bbox.width + 2 * w_pad)
+
+
+def match_submerged_margins(layoutgrids, fig):
+    """
+    Make the margins that are submerged inside an Axes the same size.
+
+    This allows Axes that span two columns (or rows) that are offset
+    from one another to have the same size.
+
+    This gives the proper layout for something like::
+        fig = plt.figure(constrained_layout=True)
+        axs = fig.subplot_mosaic("AAAB\nCCDD")
+
+    Without this routine, the Axes D will be wider than C, because the
+    margin width between the two columns in C has no width by default,
+    whereas the margins between the two columns of D are set by the
+    width of the margin between A and B. However, obviously the user would
+    like C and D to be the same size, so we need to add constraints to these
+    "submerged" margins.
+
+    This routine makes all the interior margins the same, and the spacing
+    between the three columns in A and the two column in C are all set to the
+    margins between the two columns of D.
+
+    See test_constrained_layout::test_constrained_layout12 for an example.
+    """
+
+    for sfig in fig.subfigs:
+        match_submerged_margins(layoutgrids, sfig)
+
+    axs = [a for a in fig.get_axes()
+           if a.get_subplotspec() is not None and a.get_in_layout()]
+
+    for ax1 in axs:
+        ss1 = ax1.get_subplotspec()
+        if ss1.get_gridspec() not in layoutgrids:
+            axs.remove(ax1)
+            continue
+        lg1 = layoutgrids[ss1.get_gridspec()]
+
+        # interior columns:
+        if len(ss1.colspan) > 1:
+            maxsubl = np.max(
+                lg1.margin_vals['left'][ss1.colspan[1:]] +
+                lg1.margin_vals['leftcb'][ss1.colspan[1:]]
+            )
+            maxsubr = np.max(
+                lg1.margin_vals['right'][ss1.colspan[:-1]] +
+                lg1.margin_vals['rightcb'][ss1.colspan[:-1]]
+            )
+            for ax2 in axs:
+                ss2 = ax2.get_subplotspec()
+                lg2 = layoutgrids[ss2.get_gridspec()]
+                if lg2 is not None and len(ss2.colspan) > 1:
+                    maxsubl2 = np.max(
+                        lg2.margin_vals['left'][ss2.colspan[1:]] +
+                        lg2.margin_vals['leftcb'][ss2.colspan[1:]])
+                    if maxsubl2 > maxsubl:
+                        maxsubl = maxsubl2
+                    maxsubr2 = np.max(
+                        lg2.margin_vals['right'][ss2.colspan[:-1]] +
+                        lg2.margin_vals['rightcb'][ss2.colspan[:-1]])
+                    if maxsubr2 > maxsubr:
+                        maxsubr = maxsubr2
+            for i in ss1.colspan[1:]:
+                lg1.edit_margin_min('left', maxsubl, cell=i)
+            for i in ss1.colspan[:-1]:
+                lg1.edit_margin_min('right', maxsubr, cell=i)
+
+        # interior rows:
+        if len(ss1.rowspan) > 1:
+            maxsubt = np.max(
+                lg1.margin_vals['top'][ss1.rowspan[1:]] +
+                lg1.margin_vals['topcb'][ss1.rowspan[1:]]
+            )
+            maxsubb = np.max(
+                lg1.margin_vals['bottom'][ss1.rowspan[:-1]] +
+                lg1.margin_vals['bottomcb'][ss1.rowspan[:-1]]
+            )
+
+            for ax2 in axs:
+                ss2 = ax2.get_subplotspec()
+                lg2 = layoutgrids[ss2.get_gridspec()]
+                if lg2 is not None:
+                    if len(ss2.rowspan) > 1:
+                        maxsubt = np.max([np.max(
+                            lg2.margin_vals['top'][ss2.rowspan[1:]] +
+                            lg2.margin_vals['topcb'][ss2.rowspan[1:]]
+                        ), maxsubt])
+                        maxsubb = np.max([np.max(
+                            lg2.margin_vals['bottom'][ss2.rowspan[:-1]] +
+                            lg2.margin_vals['bottomcb'][ss2.rowspan[:-1]]
+                        ), maxsubb])
+            for i in ss1.rowspan[1:]:
+                lg1.edit_margin_min('top', maxsubt, cell=i)
+            for i in ss1.rowspan[:-1]:
+                lg1.edit_margin_min('bottom', maxsubb, cell=i)
+
+
+def get_cb_parent_spans(cbax):
+    """
+    Figure out which subplotspecs this colorbar belongs to.
+
+    Parameters
+    ----------
+    cbax : `~matplotlib.axes.Axes`
+        Axes for the colorbar.
+    """
+    rowstart = np.inf
+    rowstop = -np.inf
+    colstart = np.inf
+    colstop = -np.inf
+    for parent in cbax._colorbar_info['parents']:
+        ss = parent.get_subplotspec()
+        rowstart = min(ss.rowspan.start, rowstart)
+        rowstop = max(ss.rowspan.stop, rowstop)
+        colstart = min(ss.colspan.start, colstart)
+        colstop = max(ss.colspan.stop, colstop)
+
+    rowspan = range(rowstart, rowstop)
+    colspan = range(colstart, colstop)
+    return rowspan, colspan
+
+
+def get_pos_and_bbox(ax, renderer):
+    """
+    Get the position and the bbox for the Axes.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+
+    Returns
+    -------
+    pos : `~matplotlib.transforms.Bbox`
+        Position in figure coordinates.
+    bbox : `~matplotlib.transforms.Bbox`
+        Tight bounding box in figure coordinates.
+    """
+    fig = ax.get_figure(root=False)
+    pos = ax.get_position(original=True)
+    # pos is in panel co-ords, but we need in figure for the layout
+    pos = pos.transformed(fig.transSubfigure - fig.transFigure)
+    tightbbox = martist._get_tightbbox_for_layout_only(ax, renderer)
+    if tightbbox is None:
+        bbox = pos
+    else:
+        bbox = tightbbox.transformed(fig.transFigure.inverted())
+    return pos, bbox
+
+
+def reposition_axes(layoutgrids, fig, renderer, *,
+                    w_pad=0, h_pad=0, hspace=0, wspace=0):
+    """
+    Reposition all the Axes based on the new inner bounding box.
+    """
+    trans_fig_to_subfig = fig.transFigure - fig.transSubfigure
+    for sfig in fig.subfigs:
+        bbox = layoutgrids[sfig].get_outer_bbox()
+        sfig._redo_transform_rel_fig(
+            bbox=bbox.transformed(trans_fig_to_subfig))
+        reposition_axes(layoutgrids, sfig, renderer,
+                        w_pad=w_pad, h_pad=h_pad,
+                        wspace=wspace, hspace=hspace)
+
+    for ax in fig._localaxes:
+        if ax.get_subplotspec() is None or not ax.get_in_layout():
+            continue
+
+        # grid bbox is in Figure coordinates, but we specify in panel
+        # coordinates...
+        ss = ax.get_subplotspec()
+        gs = ss.get_gridspec()
+        if gs not in layoutgrids:
+            return
+
+        bbox = layoutgrids[gs].get_inner_bbox(rows=ss.rowspan,
+                                              cols=ss.colspan)
+
+        # transform from figure to panel for set_position:
+        newbbox = trans_fig_to_subfig.transform_bbox(bbox)
+        ax._set_position(newbbox)
+
+        # move the colorbars:
+        # we need to keep track of oldw and oldh if there is more than
+        # one colorbar:
+        offset = {'left': 0, 'right': 0, 'bottom': 0, 'top': 0}
+        for nn, cbax in enumerate(ax._colorbars[::-1]):
+            if ax == cbax._colorbar_info['parents'][0]:
+                reposition_colorbar(layoutgrids, cbax, renderer,
+                                    offset=offset)
+
+
+def reposition_colorbar(layoutgrids, cbax, renderer, *, offset=None):
+    """
+    Place the colorbar in its new place.
+
+    Parameters
+    ----------
+    layoutgrids : dict
+    cbax : `~matplotlib.axes.Axes`
+        Axes for the colorbar.
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+        The renderer to use.
+    offset : array-like
+        Offset the colorbar needs to be pushed to in order to
+        account for multiple colorbars.
+    """
+
+    parents = cbax._colorbar_info['parents']
+    gs = parents[0].get_gridspec()
+    fig = cbax.get_figure(root=False)
+    trans_fig_to_subfig = fig.transFigure - fig.transSubfigure
+
+    cb_rspans, cb_cspans = get_cb_parent_spans(cbax)
+    bboxparent = layoutgrids[gs].get_bbox_for_cb(rows=cb_rspans,
+                                                 cols=cb_cspans)
+    pb = layoutgrids[gs].get_inner_bbox(rows=cb_rspans, cols=cb_cspans)
+
+    location = cbax._colorbar_info['location']
+    anchor = cbax._colorbar_info['anchor']
+    fraction = cbax._colorbar_info['fraction']
+    aspect = cbax._colorbar_info['aspect']
+    shrink = cbax._colorbar_info['shrink']
+
+    cbpos, cbbbox = get_pos_and_bbox(cbax, renderer)
+
+    # Colorbar gets put at extreme edge of outer bbox of the subplotspec
+    # It needs to be moved in by: 1) a pad 2) its "margin" 3) by
+    # any colorbars already added at this location:
+    cbpad = colorbar_get_pad(layoutgrids, cbax)
+    if location in ('left', 'right'):
+        # fraction and shrink are fractions of parent
+        pbcb = pb.shrunk(fraction, shrink).anchored(anchor, pb)
+        # The colorbar is at the left side of the parent.  Need
+        # to translate to right (or left)
+        if location == 'right':
+            lmargin = cbpos.x0 - cbbbox.x0
+            dx = bboxparent.x1 - pbcb.x0 + offset['right']
+            dx += cbpad + lmargin
+            offset['right'] += cbbbox.width + cbpad
+            pbcb = pbcb.translated(dx, 0)
+        else:
+            lmargin = cbpos.x0 - cbbbox.x0
+            dx = bboxparent.x0 - pbcb.x0  # edge of parent
+            dx += -cbbbox.width - cbpad + lmargin - offset['left']
+            offset['left'] += cbbbox.width + cbpad
+            pbcb = pbcb.translated(dx, 0)
+    else:  # horizontal axes:
+        pbcb = pb.shrunk(shrink, fraction).anchored(anchor, pb)
+        if location == 'top':
+            bmargin = cbpos.y0 - cbbbox.y0
+            dy = bboxparent.y1 - pbcb.y0 + offset['top']
+            dy += cbpad + bmargin
+            offset['top'] += cbbbox.height + cbpad
+            pbcb = pbcb.translated(0, dy)
+        else:
+            bmargin = cbpos.y0 - cbbbox.y0
+            dy = bboxparent.y0 - pbcb.y0
+            dy += -cbbbox.height - cbpad + bmargin - offset['bottom']
+            offset['bottom'] += cbbbox.height + cbpad
+            pbcb = pbcb.translated(0, dy)
+
+    pbcb = trans_fig_to_subfig.transform_bbox(pbcb)
+    cbax.set_transform(fig.transSubfigure)
+    cbax._set_position(pbcb)
+    cbax.set_anchor(anchor)
+    if location in ['bottom', 'top']:
+        aspect = 1 / aspect
+    cbax.set_box_aspect(aspect)
+    cbax.set_aspect('auto')
+    return offset
+
+
+def reset_margins(layoutgrids, fig):
+    """
+    Reset the margins in the layoutboxes of *fig*.
+
+    Margins are usually set as a minimum, so if the figure gets smaller
+    the minimum needs to be zero in order for it to grow again.
+    """
+    for sfig in fig.subfigs:
+        reset_margins(layoutgrids, sfig)
+    for ax in fig.axes:
+        if ax.get_in_layout():
+            gs = ax.get_gridspec()
+            if gs in layoutgrids:  # also implies gs is not None.
+                layoutgrids[gs].reset_margins()
+    layoutgrids[fig].reset_margins()
+
+
+def colorbar_get_pad(layoutgrids, cax):
+    parents = cax._colorbar_info['parents']
+    gs = parents[0].get_gridspec()
+
+    cb_rspans, cb_cspans = get_cb_parent_spans(cax)
+    bboxouter = layoutgrids[gs].get_inner_bbox(rows=cb_rspans, cols=cb_cspans)
+
+    if cax._colorbar_info['location'] in ['right', 'left']:
+        size = bboxouter.width
+    else:
+        size = bboxouter.height
+
+    return cax._colorbar_info['pad'] * size
diff --git a/lib/python3.12/site-packages/matplotlib/_enums.pyi b/lib/python3.12/site-packages/matplotlib/_enums.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..714e6cfe03faab19b2a3f939a6be4ac95415e061
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_enums.pyi
@@ -0,0 +1,19 @@
+from typing import cast
+from enum import Enum
+
+
+class JoinStyle(str, Enum):
+    miter = "miter"
+    round = "round"
+    bevel = "bevel"
+    @staticmethod
+    def demo() -> None: ...
+
+
+class CapStyle(str, Enum):
+    butt = "butt"
+    projecting = "projecting"
+    round = "round"
+
+    @staticmethod
+    def demo() -> None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/_fontconfig_pattern.py b/lib/python3.12/site-packages/matplotlib/_fontconfig_pattern.py
new file mode 100644
index 0000000000000000000000000000000000000000..a1341c633243905be30141ecb7273d0fb325f2de
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_fontconfig_pattern.py
@@ -0,0 +1,111 @@
+"""
+A module for parsing and generating `fontconfig patterns`_.
+
+.. _fontconfig patterns:
+   https://www.freedesktop.org/software/fontconfig/fontconfig-user.html
+"""
+
+# This class logically belongs in `matplotlib.font_manager`, but placing it
+# there would have created cyclical dependency problems, because it also needs
+# to be available from `matplotlib.rcsetup` (for parsing matplotlibrc files).
+
+from functools import lru_cache, partial
+import re
+
+from pyparsing import (
+    Group, Optional, ParseException, Regex, StringEnd, Suppress, ZeroOrMore, oneOf)
+
+
+_family_punc = r'\\\-:,'
+_family_unescape = partial(re.compile(r'\\(?=[%s])' % _family_punc).sub, '')
+_family_escape = partial(re.compile(r'(?=[%s])' % _family_punc).sub, r'\\')
+_value_punc = r'\\=_:,'
+_value_unescape = partial(re.compile(r'\\(?=[%s])' % _value_punc).sub, '')
+_value_escape = partial(re.compile(r'(?=[%s])' % _value_punc).sub, r'\\')
+
+
+_CONSTANTS = {
+    'thin':           ('weight', 'light'),
+    'extralight':     ('weight', 'light'),
+    'ultralight':     ('weight', 'light'),
+    'light':          ('weight', 'light'),
+    'book':           ('weight', 'book'),
+    'regular':        ('weight', 'regular'),
+    'normal':         ('weight', 'normal'),
+    'medium':         ('weight', 'medium'),
+    'demibold':       ('weight', 'demibold'),
+    'semibold':       ('weight', 'semibold'),
+    'bold':           ('weight', 'bold'),
+    'extrabold':      ('weight', 'extra bold'),
+    'black':          ('weight', 'black'),
+    'heavy':          ('weight', 'heavy'),
+    'roman':          ('slant', 'normal'),
+    'italic':         ('slant', 'italic'),
+    'oblique':        ('slant', 'oblique'),
+    'ultracondensed': ('width', 'ultra-condensed'),
+    'extracondensed': ('width', 'extra-condensed'),
+    'condensed':      ('width', 'condensed'),
+    'semicondensed':  ('width', 'semi-condensed'),
+    'expanded':       ('width', 'expanded'),
+    'extraexpanded':  ('width', 'extra-expanded'),
+    'ultraexpanded':  ('width', 'ultra-expanded'),
+}
+
+
+@lru_cache  # The parser instance is a singleton.
+def _make_fontconfig_parser():
+    def comma_separated(elem):
+        return elem + ZeroOrMore(Suppress(",") + elem)
+
+    family = Regex(fr"([^{_family_punc}]|(\\[{_family_punc}]))*")
+    size = Regex(r"([0-9]+\.?[0-9]*|\.[0-9]+)")
+    name = Regex(r"[a-z]+")
+    value = Regex(fr"([^{_value_punc}]|(\\[{_value_punc}]))*")
+    prop = Group((name + Suppress("=") + comma_separated(value)) | oneOf(_CONSTANTS))
+    return (
+        Optional(comma_separated(family)("families"))
+        + Optional("-" + comma_separated(size)("sizes"))
+        + ZeroOrMore(":" + prop("properties*"))
+        + StringEnd()
+    )
+
+
+# `parse_fontconfig_pattern` is a bottleneck during the tests because it is
+# repeatedly called when the rcParams are reset (to validate the default
+# fonts).  In practice, the cache size doesn't grow beyond a few dozen entries
+# during the test suite.
+@lru_cache
+def parse_fontconfig_pattern(pattern):
+    """
+    Parse a fontconfig *pattern* into a dict that can initialize a
+    `.font_manager.FontProperties` object.
+    """
+    parser = _make_fontconfig_parser()
+    try:
+        parse = parser.parseString(pattern)
+    except ParseException as err:
+        # explain becomes a plain method on pyparsing 3 (err.explain(0)).
+        raise ValueError("\n" + ParseException.explain(err, 0)) from None
+    parser.resetCache()
+    props = {}
+    if "families" in parse:
+        props["family"] = [*map(_family_unescape, parse["families"])]
+    if "sizes" in parse:
+        props["size"] = [*parse["sizes"]]
+    for prop in parse.get("properties", []):
+        if len(prop) == 1:
+            prop = _CONSTANTS[prop[0]]
+        k, *v = prop
+        props.setdefault(k, []).extend(map(_value_unescape, v))
+    return props
+
+
+def generate_fontconfig_pattern(d):
+    """Convert a `.FontProperties` to a fontconfig pattern string."""
+    kvs = [(k, getattr(d, f"get_{k}")())
+           for k in ["style", "variant", "weight", "stretch", "file", "size"]]
+    # Families is given first without a leading keyword.  Other entries (which
+    # are necessarily scalar) are given as key=value, skipping Nones.
+    return (",".join(_family_escape(f) for f in d.get_family())
+            + "".join(f":{k}={_value_escape(str(v))}"
+                      for k, v in kvs if v is not None))
diff --git a/lib/python3.12/site-packages/matplotlib/_image.pyi b/lib/python3.12/site-packages/matplotlib/_image.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/lib/python3.12/site-packages/matplotlib/_internal_utils.py b/lib/python3.12/site-packages/matplotlib/_internal_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..0223aa593bb2cb20b58f2b9e41bdc0dfa5ceed35
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_internal_utils.py
@@ -0,0 +1,64 @@
+"""
+Internal debugging utilities, that are not expected to be used in the rest of
+the codebase.
+
+WARNING: Code in this module may change without prior notice!
+"""
+
+from io import StringIO
+from pathlib import Path
+import subprocess
+
+from matplotlib.transforms import TransformNode
+
+
+def graphviz_dump_transform(transform, dest, *, highlight=None):
+    """
+    Generate a graphical representation of the transform tree for *transform*
+    using the :program:`dot` program (which this function depends on).  The
+    output format (png, dot, etc.) is determined from the suffix of *dest*.
+
+    Parameters
+    ----------
+    transform : `~matplotlib.transform.Transform`
+        The represented transform.
+    dest : str
+        Output filename.  The extension must be one of the formats supported
+        by :program:`dot`, e.g. png, svg, dot, ...
+        (see https://www.graphviz.org/doc/info/output.html).
+    highlight : list of `~matplotlib.transform.Transform` or None
+        The transforms in the tree to be drawn in bold.
+        If *None*, *transform* is highlighted.
+    """
+
+    if highlight is None:
+        highlight = [transform]
+    seen = set()
+
+    def recurse(root, buf):
+        if id(root) in seen:
+            return
+        seen.add(id(root))
+        props = {}
+        label = type(root).__name__
+        if root._invalid:
+            label = f'[{label}]'
+        if root in highlight:
+            props['style'] = 'bold'
+        props['shape'] = 'box'
+        props['label'] = '"%s"' % label
+        props = ' '.join(map('{0[0]}={0[1]}'.format, props.items()))
+        buf.write(f'{id(root)} [{props}];\n')
+        for key, val in vars(root).items():
+            if isinstance(val, TransformNode) and id(root) in val._parents:
+                buf.write(f'"{id(root)}" -> "{id(val)}" '
+                          f'[label="{key}", fontsize=10];\n')
+                recurse(val, buf)
+
+    buf = StringIO()
+    buf.write('digraph G {\n')
+    recurse(transform, buf)
+    buf.write('}\n')
+    subprocess.run(
+        ['dot', '-T', Path(dest).suffix[1:], '-o', dest],
+        input=buf.getvalue().encode('utf-8'), check=True)
diff --git a/lib/python3.12/site-packages/matplotlib/_mathtext.py b/lib/python3.12/site-packages/matplotlib/_mathtext.py
new file mode 100644
index 0000000000000000000000000000000000000000..7085a986414e74c046998ebc5925e803656074e7
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_mathtext.py
@@ -0,0 +1,2861 @@
+"""
+Implementation details for :mod:`.mathtext`.
+"""
+
+from __future__ import annotations
+
+import abc
+import copy
+import enum
+import functools
+import logging
+import os
+import re
+import types
+import unicodedata
+import string
+import typing as T
+from typing import NamedTuple
+
+import numpy as np
+from pyparsing import (
+    Empty, Forward, Literal, NotAny, oneOf, OneOrMore, Optional,
+    ParseBaseException, ParseException, ParseExpression, ParseFatalException,
+    ParserElement, ParseResults, QuotedString, Regex, StringEnd, ZeroOrMore,
+    pyparsing_common, Group)
+
+import matplotlib as mpl
+from . import cbook
+from ._mathtext_data import (
+    latex_to_bakoma, stix_glyph_fixes, stix_virtual_fonts, tex2uni)
+from .font_manager import FontProperties, findfont, get_font
+from .ft2font import FT2Font, FT2Image, Kerning, LoadFlags
+
+from packaging.version import parse as parse_version
+from pyparsing import __version__ as pyparsing_version
+if parse_version(pyparsing_version).major < 3:
+    from pyparsing import nestedExpr as nested_expr
+else:
+    from pyparsing import nested_expr
+
+if T.TYPE_CHECKING:
+    from collections.abc import Iterable
+    from .ft2font import Glyph
+
+ParserElement.enablePackrat()
+_log = logging.getLogger("matplotlib.mathtext")
+
+
+##############################################################################
+# FONTS
+
+
+def get_unicode_index(symbol: str) -> int:  # Publicly exported.
+    r"""
+    Return the integer index (from the Unicode table) of *symbol*.
+
+    Parameters
+    ----------
+    symbol : str
+        A single (Unicode) character, a TeX command (e.g. r'\pi') or a Type1
+        symbol name (e.g. 'phi').
+    """
+    try:  # This will succeed if symbol is a single Unicode char
+        return ord(symbol)
+    except TypeError:
+        pass
+    try:  # Is symbol a TeX symbol (i.e. \alpha)
+        return tex2uni[symbol.strip("\\")]
+    except KeyError as err:
+        raise ValueError(
+            f"{symbol!r} is not a valid Unicode character or TeX/Type1 symbol"
+            ) from err
+
+
+class VectorParse(NamedTuple):
+    """
+    The namedtuple type returned by ``MathTextParser("path").parse(...)``.
+
+    Attributes
+    ----------
+    width, height, depth : float
+        The global metrics.
+    glyphs : list
+        The glyphs including their positions.
+    rect : list
+        The list of rectangles.
+    """
+    width: float
+    height: float
+    depth: float
+    glyphs: list[tuple[FT2Font, float, int, float, float]]
+    rects: list[tuple[float, float, float, float]]
+
+VectorParse.__module__ = "matplotlib.mathtext"
+
+
+class RasterParse(NamedTuple):
+    """
+    The namedtuple type returned by ``MathTextParser("agg").parse(...)``.
+
+    Attributes
+    ----------
+    ox, oy : float
+        The offsets are always zero.
+    width, height, depth : float
+        The global metrics.
+    image : FT2Image
+        A raster image.
+    """
+    ox: float
+    oy: float
+    width: float
+    height: float
+    depth: float
+    image: FT2Image
+
+RasterParse.__module__ = "matplotlib.mathtext"
+
+
+class Output:
+    r"""
+    Result of `ship`\ping a box: lists of positioned glyphs and rectangles.
+
+    This class is not exposed to end users, but converted to a `VectorParse` or
+    a `RasterParse` by `.MathTextParser.parse`.
+    """
+
+    def __init__(self, box: Box):
+        self.box = box
+        self.glyphs: list[tuple[float, float, FontInfo]] = []  # (ox, oy, info)
+        self.rects: list[tuple[float, float, float, float]] = []  # (x1, y1, x2, y2)
+
+    def to_vector(self) -> VectorParse:
+        w, h, d = map(
+            np.ceil, [self.box.width, self.box.height, self.box.depth])
+        gs = [(info.font, info.fontsize, info.num, ox, h - oy + info.offset)
+              for ox, oy, info in self.glyphs]
+        rs = [(x1, h - y2, x2 - x1, y2 - y1)
+              for x1, y1, x2, y2 in self.rects]
+        return VectorParse(w, h + d, d, gs, rs)
+
+    def to_raster(self, *, antialiased: bool) -> RasterParse:
+        # Metrics y's and mathtext y's are oriented in opposite directions,
+        # hence the switch between ymin and ymax.
+        xmin = min([*[ox + info.metrics.xmin for ox, oy, info in self.glyphs],
+                    *[x1 for x1, y1, x2, y2 in self.rects], 0]) - 1
+        ymin = min([*[oy - info.metrics.ymax for ox, oy, info in self.glyphs],
+                    *[y1 for x1, y1, x2, y2 in self.rects], 0]) - 1
+        xmax = max([*[ox + info.metrics.xmax for ox, oy, info in self.glyphs],
+                    *[x2 for x1, y1, x2, y2 in self.rects], 0]) + 1
+        ymax = max([*[oy - info.metrics.ymin for ox, oy, info in self.glyphs],
+                    *[y2 for x1, y1, x2, y2 in self.rects], 0]) + 1
+        w = xmax - xmin
+        h = ymax - ymin - self.box.depth
+        d = ymax - ymin - self.box.height
+        image = FT2Image(int(np.ceil(w)), int(np.ceil(h + max(d, 0))))
+
+        # Ideally, we could just use self.glyphs and self.rects here, shifting
+        # their coordinates by (-xmin, -ymin), but this yields slightly
+        # different results due to floating point slop; shipping twice is the
+        # old approach and keeps baseline images backcompat.
+        shifted = ship(self.box, (-xmin, -ymin))
+
+        for ox, oy, info in shifted.glyphs:
+            info.font.draw_glyph_to_bitmap(
+                image, int(ox), int(oy - info.metrics.iceberg), info.glyph,
+                antialiased=antialiased)
+        for x1, y1, x2, y2 in shifted.rects:
+            height = max(int(y2 - y1) - 1, 0)
+            if height == 0:
+                center = (y2 + y1) / 2
+                y = int(center - (height + 1) / 2)
+            else:
+                y = int(y1)
+            image.draw_rect_filled(int(x1), y, int(np.ceil(x2)), y + height)
+        return RasterParse(0, 0, w, h + d, d, image)
+
+
+class FontMetrics(NamedTuple):
+    """
+    Metrics of a font.
+
+    Attributes
+    ----------
+    advance : float
+        The advance distance (in points) of the glyph.
+    height : float
+        The height of the glyph in points.
+    width : float
+        The width of the glyph in points.
+    xmin, xmax, ymin, ymax : float
+        The ink rectangle of the glyph.
+    iceberg : float
+        The distance from the baseline to the top of the glyph. (This corresponds to
+        TeX's definition of "height".)
+    slanted : bool
+        Whether the glyph should be considered as "slanted" (currently used for kerning
+        sub/superscripts).
+    """
+    advance: float
+    height: float
+    width: float
+    xmin: float
+    xmax: float
+    ymin: float
+    ymax: float
+    iceberg: float
+    slanted: bool
+
+
+class FontInfo(NamedTuple):
+    font: FT2Font
+    fontsize: float
+    postscript_name: str
+    metrics: FontMetrics
+    num: int
+    glyph: Glyph
+    offset: float
+
+
+class Fonts(abc.ABC):
+    """
+    An abstract base class for a system of fonts to use for mathtext.
+
+    The class must be able to take symbol keys and font file names and
+    return the character metrics.  It also delegates to a backend class
+    to do the actual drawing.
+    """
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        """
+        Parameters
+        ----------
+        default_font_prop : `~.font_manager.FontProperties`
+            The default non-math font, or the base font for Unicode (generic)
+            font rendering.
+        load_glyph_flags : `.ft2font.LoadFlags`
+            Flags passed to the glyph loader (e.g. ``FT_Load_Glyph`` and
+            ``FT_Load_Char`` for FreeType-based fonts).
+        """
+        self.default_font_prop = default_font_prop
+        self.load_glyph_flags = load_glyph_flags
+
+    def get_kern(self, font1: str, fontclass1: str, sym1: str, fontsize1: float,
+                 font2: str, fontclass2: str, sym2: str, fontsize2: float,
+                 dpi: float) -> float:
+        """
+        Get the kerning distance for font between *sym1* and *sym2*.
+
+        See `~.Fonts.get_metrics` for a detailed description of the parameters.
+        """
+        return 0.
+
+    def _get_font(self, font: str) -> FT2Font:
+        raise NotImplementedError
+
+    def _get_info(self, font: str, font_class: str, sym: str, fontsize: float,
+                  dpi: float) -> FontInfo:
+        raise NotImplementedError
+
+    def get_metrics(self, font: str, font_class: str, sym: str, fontsize: float,
+                    dpi: float) -> FontMetrics:
+        r"""
+        Parameters
+        ----------
+        font : str
+            One of the TeX font names: "tt", "it", "rm", "cal", "sf", "bf",
+            "default", "regular", "bb", "frak", "scr".  "default" and "regular"
+            are synonyms and use the non-math font.
+        font_class : str
+            One of the TeX font names (as for *font*), but **not** "bb",
+            "frak", or "scr".  This is used to combine two font classes.  The
+            only supported combination currently is ``get_metrics("frak", "bf",
+            ...)``.
+        sym : str
+            A symbol in raw TeX form, e.g., "1", "x", or "\sigma".
+        fontsize : float
+            Font size in points.
+        dpi : float
+            Rendering dots-per-inch.
+
+        Returns
+        -------
+        FontMetrics
+        """
+        info = self._get_info(font, font_class, sym, fontsize, dpi)
+        return info.metrics
+
+    def render_glyph(self, output: Output, ox: float, oy: float, font: str,
+                     font_class: str, sym: str, fontsize: float, dpi: float) -> None:
+        """
+        At position (*ox*, *oy*), draw the glyph specified by the remaining
+        parameters (see `get_metrics` for their detailed description).
+        """
+        info = self._get_info(font, font_class, sym, fontsize, dpi)
+        output.glyphs.append((ox, oy, info))
+
+    def render_rect_filled(self, output: Output,
+                           x1: float, y1: float, x2: float, y2: float) -> None:
+        """
+        Draw a filled rectangle from (*x1*, *y1*) to (*x2*, *y2*).
+        """
+        output.rects.append((x1, y1, x2, y2))
+
+    def get_xheight(self, font: str, fontsize: float, dpi: float) -> float:
+        """
+        Get the xheight for the given *font* and *fontsize*.
+        """
+        raise NotImplementedError()
+
+    def get_underline_thickness(self, font: str, fontsize: float, dpi: float) -> float:
+        """
+        Get the line thickness that matches the given font.  Used as a
+        base unit for drawing lines such as in a fraction or radical.
+        """
+        raise NotImplementedError()
+
+    def get_sized_alternatives_for_symbol(self, fontname: str,
+                                          sym: str) -> list[tuple[str, str]]:
+        """
+        Override if your font provides multiple sizes of the same
+        symbol.  Should return a list of symbols matching *sym* in
+        various sizes.  The expression renderer will select the most
+        appropriate size for a given situation from this list.
+        """
+        return [(fontname, sym)]
+
+
+class TruetypeFonts(Fonts, metaclass=abc.ABCMeta):
+    """
+    A generic base class for all font setups that use Truetype fonts
+    (through FT2Font).
+    """
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        super().__init__(default_font_prop, load_glyph_flags)
+        # Per-instance cache.
+        self._get_info = functools.cache(self._get_info)  # type: ignore[method-assign]
+        self._fonts = {}
+        self.fontmap: dict[str | int, str] = {}
+
+        filename = findfont(self.default_font_prop)
+        default_font = get_font(filename)
+        self._fonts['default'] = default_font
+        self._fonts['regular'] = default_font
+
+    def _get_font(self, font: str | int) -> FT2Font:
+        if font in self.fontmap:
+            basename = self.fontmap[font]
+        else:
+            # NOTE: An int is only passed by subclasses which have placed int keys into
+            # `self.fontmap`, so we must cast this to confirm it to typing.
+            basename = T.cast(str, font)
+        cached_font = self._fonts.get(basename)
+        if cached_font is None and os.path.exists(basename):
+            cached_font = get_font(basename)
+            self._fonts[basename] = cached_font
+            self._fonts[cached_font.postscript_name] = cached_font
+            self._fonts[cached_font.postscript_name.lower()] = cached_font
+        return T.cast(FT2Font, cached_font)  # FIXME: Not sure this is guaranteed.
+
+    def _get_offset(self, font: FT2Font, glyph: Glyph, fontsize: float,
+                    dpi: float) -> float:
+        if font.postscript_name == 'Cmex10':
+            return (glyph.height / 64 / 2) + (fontsize/3 * dpi/72)
+        return 0.
+
+    def _get_glyph(self, fontname: str, font_class: str,
+                   sym: str) -> tuple[FT2Font, int, bool]:
+        raise NotImplementedError
+
+    # The return value of _get_info is cached per-instance.
+    def _get_info(self, fontname: str, font_class: str, sym: str, fontsize: float,
+                  dpi: float) -> FontInfo:
+        font, num, slanted = self._get_glyph(fontname, font_class, sym)
+        font.set_size(fontsize, dpi)
+        glyph = font.load_char(num, flags=self.load_glyph_flags)
+
+        xmin, ymin, xmax, ymax = (val / 64 for val in glyph.bbox)
+        offset = self._get_offset(font, glyph, fontsize, dpi)
+        metrics = FontMetrics(
+            advance=glyph.linearHoriAdvance / 65536,
+            height=glyph.height / 64,
+            width=glyph.width / 64,
+            xmin=xmin,
+            xmax=xmax,
+            ymin=ymin + offset,
+            ymax=ymax + offset,
+            # iceberg is the equivalent of TeX's "height"
+            iceberg=glyph.horiBearingY / 64 + offset,
+            slanted=slanted
+        )
+
+        return FontInfo(
+            font=font,
+            fontsize=fontsize,
+            postscript_name=font.postscript_name,
+            metrics=metrics,
+            num=num,
+            glyph=glyph,
+            offset=offset
+        )
+
+    def get_xheight(self, fontname: str, fontsize: float, dpi: float) -> float:
+        font = self._get_font(fontname)
+        font.set_size(fontsize, dpi)
+        pclt = font.get_sfnt_table('pclt')
+        if pclt is None:
+            # Some fonts don't store the xHeight, so we do a poor man's xHeight
+            metrics = self.get_metrics(
+                fontname, mpl.rcParams['mathtext.default'], 'x', fontsize, dpi)
+            return metrics.iceberg
+        xHeight = (pclt['xHeight'] / 64.0) * (fontsize / 12.0) * (dpi / 100.0)
+        return xHeight
+
+    def get_underline_thickness(self, font: str, fontsize: float, dpi: float) -> float:
+        # This function used to grab underline thickness from the font
+        # metrics, but that information is just too un-reliable, so it
+        # is now hardcoded.
+        return ((0.75 / 12.0) * fontsize * dpi) / 72.0
+
+    def get_kern(self, font1: str, fontclass1: str, sym1: str, fontsize1: float,
+                 font2: str, fontclass2: str, sym2: str, fontsize2: float,
+                 dpi: float) -> float:
+        if font1 == font2 and fontsize1 == fontsize2:
+            info1 = self._get_info(font1, fontclass1, sym1, fontsize1, dpi)
+            info2 = self._get_info(font2, fontclass2, sym2, fontsize2, dpi)
+            font = info1.font
+            return font.get_kerning(info1.num, info2.num, Kerning.DEFAULT) / 64
+        return super().get_kern(font1, fontclass1, sym1, fontsize1,
+                                font2, fontclass2, sym2, fontsize2, dpi)
+
+
+class BakomaFonts(TruetypeFonts):
+    """
+    Use the Bakoma TrueType fonts for rendering.
+
+    Symbols are strewn about a number of font files, each of which has
+    its own proprietary 8-bit encoding.
+    """
+    _fontmap = {
+        'cal': 'cmsy10',
+        'rm':  'cmr10',
+        'tt':  'cmtt10',
+        'it':  'cmmi10',
+        'bf':  'cmb10',
+        'sf':  'cmss10',
+        'ex':  'cmex10',
+    }
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        self._stix_fallback = StixFonts(default_font_prop, load_glyph_flags)
+
+        super().__init__(default_font_prop, load_glyph_flags)
+        for key, val in self._fontmap.items():
+            fullpath = findfont(val)
+            self.fontmap[key] = fullpath
+            self.fontmap[val] = fullpath
+
+    _slanted_symbols = set(r"\int \oint".split())
+
+    def _get_glyph(self, fontname: str, font_class: str,
+                   sym: str) -> tuple[FT2Font, int, bool]:
+        font = None
+        if fontname in self.fontmap and sym in latex_to_bakoma:
+            basename, num = latex_to_bakoma[sym]
+            slanted = (basename == "cmmi10") or sym in self._slanted_symbols
+            font = self._get_font(basename)
+        elif len(sym) == 1:
+            slanted = (fontname == "it")
+            font = self._get_font(fontname)
+            if font is not None:
+                num = ord(sym)
+        if font is not None and font.get_char_index(num) != 0:
+            return font, num, slanted
+        else:
+            return self._stix_fallback._get_glyph(fontname, font_class, sym)
+
+    # The Bakoma fonts contain many pre-sized alternatives for the
+    # delimiters.  The AutoSizedChar class will use these alternatives
+    # and select the best (closest sized) glyph.
+    _size_alternatives = {
+        '(':           [('rm', '('), ('ex', '\xa1'), ('ex', '\xb3'),
+                        ('ex', '\xb5'), ('ex', '\xc3')],
+        ')':           [('rm', ')'), ('ex', '\xa2'), ('ex', '\xb4'),
+                        ('ex', '\xb6'), ('ex', '\x21')],
+        '{':           [('cal', '{'), ('ex', '\xa9'), ('ex', '\x6e'),
+                        ('ex', '\xbd'), ('ex', '\x28')],
+        '}':           [('cal', '}'), ('ex', '\xaa'), ('ex', '\x6f'),
+                        ('ex', '\xbe'), ('ex', '\x29')],
+        # The fourth size of '[' is mysteriously missing from the BaKoMa
+        # font, so I've omitted it for both '[' and ']'
+        '[':           [('rm', '['), ('ex', '\xa3'), ('ex', '\x68'),
+                        ('ex', '\x22')],
+        ']':           [('rm', ']'), ('ex', '\xa4'), ('ex', '\x69'),
+                        ('ex', '\x23')],
+        r'\lfloor':    [('ex', '\xa5'), ('ex', '\x6a'),
+                        ('ex', '\xb9'), ('ex', '\x24')],
+        r'\rfloor':    [('ex', '\xa6'), ('ex', '\x6b'),
+                        ('ex', '\xba'), ('ex', '\x25')],
+        r'\lceil':     [('ex', '\xa7'), ('ex', '\x6c'),
+                        ('ex', '\xbb'), ('ex', '\x26')],
+        r'\rceil':     [('ex', '\xa8'), ('ex', '\x6d'),
+                        ('ex', '\xbc'), ('ex', '\x27')],
+        r'\langle':    [('ex', '\xad'), ('ex', '\x44'),
+                        ('ex', '\xbf'), ('ex', '\x2a')],
+        r'\rangle':    [('ex', '\xae'), ('ex', '\x45'),
+                        ('ex', '\xc0'), ('ex', '\x2b')],
+        r'\__sqrt__':  [('ex', '\x70'), ('ex', '\x71'),
+                        ('ex', '\x72'), ('ex', '\x73')],
+        r'\backslash': [('ex', '\xb2'), ('ex', '\x2f'),
+                        ('ex', '\xc2'), ('ex', '\x2d')],
+        r'/':          [('rm', '/'), ('ex', '\xb1'), ('ex', '\x2e'),
+                        ('ex', '\xcb'), ('ex', '\x2c')],
+        r'\widehat':   [('rm', '\x5e'), ('ex', '\x62'), ('ex', '\x63'),
+                        ('ex', '\x64')],
+        r'\widetilde': [('rm', '\x7e'), ('ex', '\x65'), ('ex', '\x66'),
+                        ('ex', '\x67')],
+        r'<':          [('cal', 'h'), ('ex', 'D')],
+        r'>':          [('cal', 'i'), ('ex', 'E')]
+        }
+
+    for alias, target in [(r'\leftparen', '('),
+                          (r'\rightparen', ')'),
+                          (r'\leftbrace', '{'),
+                          (r'\rightbrace', '}'),
+                          (r'\leftbracket', '['),
+                          (r'\rightbracket', ']'),
+                          (r'\{', '{'),
+                          (r'\}', '}'),
+                          (r'\[', '['),
+                          (r'\]', ']')]:
+        _size_alternatives[alias] = _size_alternatives[target]
+
+    def get_sized_alternatives_for_symbol(self, fontname: str,
+                                          sym: str) -> list[tuple[str, str]]:
+        return self._size_alternatives.get(sym, [(fontname, sym)])
+
+
+class UnicodeFonts(TruetypeFonts):
+    """
+    An abstract base class for handling Unicode fonts.
+
+    While some reasonably complete Unicode fonts (such as DejaVu) may
+    work in some situations, the only Unicode font I'm aware of with a
+    complete set of math symbols is STIX.
+
+    This class will "fallback" on the Bakoma fonts when a required
+    symbol cannot be found in the font.
+    """
+
+    # Some glyphs are not present in the `cmr10` font, and must be brought in
+    # from `cmsy10`. Map the Unicode indices of those glyphs to the indices at
+    # which they are found in `cmsy10`.
+    _cmr10_substitutions = {
+        0x00D7: 0x00A3,  # Multiplication sign.
+        0x2212: 0x00A1,  # Minus sign.
+    }
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        # This must come first so the backend's owner is set correctly
+        fallback_rc = mpl.rcParams['mathtext.fallback']
+        font_cls: type[TruetypeFonts] | None = {
+            'stix': StixFonts,
+            'stixsans': StixSansFonts,
+            'cm': BakomaFonts
+        }.get(fallback_rc)
+        self._fallback_font = (font_cls(default_font_prop, load_glyph_flags)
+                               if font_cls else None)
+
+        super().__init__(default_font_prop, load_glyph_flags)
+        for texfont in "cal rm tt it bf sf bfit".split():
+            prop = mpl.rcParams['mathtext.' + texfont]
+            font = findfont(prop)
+            self.fontmap[texfont] = font
+        prop = FontProperties('cmex10')
+        font = findfont(prop)
+        self.fontmap['ex'] = font
+
+        # include STIX sized alternatives for glyphs if fallback is STIX
+        if isinstance(self._fallback_font, StixFonts):
+            stixsizedaltfonts = {
+                 0: 'STIXGeneral',
+                 1: 'STIXSizeOneSym',
+                 2: 'STIXSizeTwoSym',
+                 3: 'STIXSizeThreeSym',
+                 4: 'STIXSizeFourSym',
+                 5: 'STIXSizeFiveSym'}
+
+            for size, name in stixsizedaltfonts.items():
+                fullpath = findfont(name)
+                self.fontmap[size] = fullpath
+                self.fontmap[name] = fullpath
+
+    _slanted_symbols = set(r"\int \oint".split())
+
+    def _map_virtual_font(self, fontname: str, font_class: str,
+                          uniindex: int) -> tuple[str, int]:
+        return fontname, uniindex
+
+    def _get_glyph(self, fontname: str, font_class: str,
+                   sym: str) -> tuple[FT2Font, int, bool]:
+        try:
+            uniindex = get_unicode_index(sym)
+            found_symbol = True
+        except ValueError:
+            uniindex = ord('?')
+            found_symbol = False
+            _log.warning("No TeX to Unicode mapping for %a.", sym)
+
+        fontname, uniindex = self._map_virtual_font(
+            fontname, font_class, uniindex)
+
+        new_fontname = fontname
+
+        # Only characters in the "Letter" class should be italicized in 'it'
+        # mode.  Greek capital letters should be Roman.
+        if found_symbol:
+            if fontname == 'it' and uniindex < 0x10000:
+                char = chr(uniindex)
+                if (unicodedata.category(char)[0] != "L"
+                        or unicodedata.name(char).startswith("GREEK CAPITAL")):
+                    new_fontname = 'rm'
+
+            slanted = (new_fontname == 'it') or sym in self._slanted_symbols
+            found_symbol = False
+            font = self._get_font(new_fontname)
+            if font is not None:
+                if (uniindex in self._cmr10_substitutions
+                        and font.family_name == "cmr10"):
+                    font = get_font(
+                        cbook._get_data_path("fonts/ttf/cmsy10.ttf"))
+                    uniindex = self._cmr10_substitutions[uniindex]
+                glyphindex = font.get_char_index(uniindex)
+                if glyphindex != 0:
+                    found_symbol = True
+
+        if not found_symbol:
+            if self._fallback_font:
+                if (fontname in ('it', 'regular')
+                        and isinstance(self._fallback_font, StixFonts)):
+                    fontname = 'rm'
+
+                g = self._fallback_font._get_glyph(fontname, font_class, sym)
+                family = g[0].family_name
+                if family in list(BakomaFonts._fontmap.values()):
+                    family = "Computer Modern"
+                _log.info("Substituting symbol %s from %s", sym, family)
+                return g
+
+            else:
+                if (fontname in ('it', 'regular')
+                        and isinstance(self, StixFonts)):
+                    return self._get_glyph('rm', font_class, sym)
+                _log.warning("Font %r does not have a glyph for %a [U+%x], "
+                             "substituting with a dummy symbol.",
+                             new_fontname, sym, uniindex)
+                font = self._get_font('rm')
+                uniindex = 0xA4  # currency char, for lack of anything better
+                slanted = False
+
+        return font, uniindex, slanted
+
+    def get_sized_alternatives_for_symbol(self, fontname: str,
+                                          sym: str) -> list[tuple[str, str]]:
+        if self._fallback_font:
+            return self._fallback_font.get_sized_alternatives_for_symbol(
+                fontname, sym)
+        return [(fontname, sym)]
+
+
+class DejaVuFonts(UnicodeFonts, metaclass=abc.ABCMeta):
+    _fontmap: dict[str | int, str] = {}
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        # This must come first so the backend's owner is set correctly
+        if isinstance(self, DejaVuSerifFonts):
+            self._fallback_font = StixFonts(default_font_prop, load_glyph_flags)
+        else:
+            self._fallback_font = StixSansFonts(default_font_prop, load_glyph_flags)
+        self.bakoma = BakomaFonts(default_font_prop, load_glyph_flags)
+        TruetypeFonts.__init__(self, default_font_prop, load_glyph_flags)
+        # Include Stix sized alternatives for glyphs
+        self._fontmap.update({
+            1: 'STIXSizeOneSym',
+            2: 'STIXSizeTwoSym',
+            3: 'STIXSizeThreeSym',
+            4: 'STIXSizeFourSym',
+            5: 'STIXSizeFiveSym',
+        })
+        for key, name in self._fontmap.items():
+            fullpath = findfont(name)
+            self.fontmap[key] = fullpath
+            self.fontmap[name] = fullpath
+
+    def _get_glyph(self, fontname: str, font_class: str,
+                   sym: str) -> tuple[FT2Font, int, bool]:
+        # Override prime symbol to use Bakoma.
+        if sym == r'\prime':
+            return self.bakoma._get_glyph(fontname, font_class, sym)
+        else:
+            # check whether the glyph is available in the display font
+            uniindex = get_unicode_index(sym)
+            font = self._get_font('ex')
+            if font is not None:
+                glyphindex = font.get_char_index(uniindex)
+                if glyphindex != 0:
+                    return super()._get_glyph('ex', font_class, sym)
+            # otherwise return regular glyph
+            return super()._get_glyph(fontname, font_class, sym)
+
+
+class DejaVuSerifFonts(DejaVuFonts):
+    """
+    A font handling class for the DejaVu Serif fonts
+
+    If a glyph is not found it will fallback to Stix Serif
+    """
+    _fontmap = {
+        'rm': 'DejaVu Serif',
+        'it': 'DejaVu Serif:italic',
+        'bf': 'DejaVu Serif:weight=bold',
+        'bfit': 'DejaVu Serif:italic:bold',
+        'sf': 'DejaVu Sans',
+        'tt': 'DejaVu Sans Mono',
+        'ex': 'DejaVu Serif Display',
+        0:    'DejaVu Serif',
+    }
+
+
+class DejaVuSansFonts(DejaVuFonts):
+    """
+    A font handling class for the DejaVu Sans fonts
+
+    If a glyph is not found it will fallback to Stix Sans
+    """
+    _fontmap = {
+        'rm': 'DejaVu Sans',
+        'it': 'DejaVu Sans:italic',
+        'bf': 'DejaVu Sans:weight=bold',
+        'bfit': 'DejaVu Sans:italic:bold',
+        'sf': 'DejaVu Sans',
+        'tt': 'DejaVu Sans Mono',
+        'ex': 'DejaVu Sans Display',
+        0:    'DejaVu Sans',
+    }
+
+
+class StixFonts(UnicodeFonts):
+    """
+    A font handling class for the STIX fonts.
+
+    In addition to what UnicodeFonts provides, this class:
+
+    - supports "virtual fonts" which are complete alpha numeric
+      character sets with different font styles at special Unicode
+      code points, such as "Blackboard".
+
+    - handles sized alternative characters for the STIXSizeX fonts.
+    """
+    _fontmap: dict[str | int, str] = {
+        'rm': 'STIXGeneral',
+        'it': 'STIXGeneral:italic',
+        'bf': 'STIXGeneral:weight=bold',
+        'bfit': 'STIXGeneral:italic:bold',
+        'nonunirm': 'STIXNonUnicode',
+        'nonuniit': 'STIXNonUnicode:italic',
+        'nonunibf': 'STIXNonUnicode:weight=bold',
+        0: 'STIXGeneral',
+        1: 'STIXSizeOneSym',
+        2: 'STIXSizeTwoSym',
+        3: 'STIXSizeThreeSym',
+        4: 'STIXSizeFourSym',
+        5: 'STIXSizeFiveSym',
+    }
+    _fallback_font = None
+    _sans = False
+
+    def __init__(self, default_font_prop: FontProperties, load_glyph_flags: LoadFlags):
+        TruetypeFonts.__init__(self, default_font_prop, load_glyph_flags)
+        for key, name in self._fontmap.items():
+            fullpath = findfont(name)
+            self.fontmap[key] = fullpath
+            self.fontmap[name] = fullpath
+
+    def _map_virtual_font(self, fontname: str, font_class: str,
+                          uniindex: int) -> tuple[str, int]:
+        # Handle these "fonts" that are actually embedded in
+        # other fonts.
+        font_mapping = stix_virtual_fonts.get(fontname)
+        if (self._sans and font_mapping is None
+                and fontname not in ('regular', 'default')):
+            font_mapping = stix_virtual_fonts['sf']
+            doing_sans_conversion = True
+        else:
+            doing_sans_conversion = False
+
+        if isinstance(font_mapping, dict):
+            try:
+                mapping = font_mapping[font_class]
+            except KeyError:
+                mapping = font_mapping['rm']
+        elif isinstance(font_mapping, list):
+            mapping = font_mapping
+        else:
+            mapping = None
+
+        if mapping is not None:
+            # Binary search for the source glyph
+            lo = 0
+            hi = len(mapping)
+            while lo < hi:
+                mid = (lo+hi)//2
+                range = mapping[mid]
+                if uniindex < range[0]:
+                    hi = mid
+                elif uniindex <= range[1]:
+                    break
+                else:
+                    lo = mid + 1
+
+            if range[0] <= uniindex <= range[1]:
+                uniindex = uniindex - range[0] + range[3]
+                fontname = range[2]
+            elif not doing_sans_conversion:
+                # This will generate a dummy character
+                uniindex = 0x1
+                fontname = mpl.rcParams['mathtext.default']
+
+        # Fix some incorrect glyphs.
+        if fontname in ('rm', 'it'):
+            uniindex = stix_glyph_fixes.get(uniindex, uniindex)
+
+        # Handle private use area glyphs
+        if fontname in ('it', 'rm', 'bf', 'bfit') and 0xe000 <= uniindex <= 0xf8ff:
+            fontname = 'nonuni' + fontname
+
+        return fontname, uniindex
+
+    @functools.cache
+    def get_sized_alternatives_for_symbol(  # type: ignore[override]
+            self,
+            fontname: str,
+            sym: str) -> list[tuple[str, str]] | list[tuple[int, str]]:
+        fixes = {
+            '\\{': '{', '\\}': '}', '\\[': '[', '\\]': ']',
+            '<': '\N{MATHEMATICAL LEFT ANGLE BRACKET}',
+            '>': '\N{MATHEMATICAL RIGHT ANGLE BRACKET}',
+        }
+        sym = fixes.get(sym, sym)
+        try:
+            uniindex = get_unicode_index(sym)
+        except ValueError:
+            return [(fontname, sym)]
+        alternatives = [(i, chr(uniindex)) for i in range(6)
+                        if self._get_font(i).get_char_index(uniindex) != 0]
+        # The largest size of the radical symbol in STIX has incorrect
+        # metrics that cause it to be disconnected from the stem.
+        if sym == r'\__sqrt__':
+            alternatives = alternatives[:-1]
+        return alternatives
+
+
+class StixSansFonts(StixFonts):
+    """
+    A font handling class for the STIX fonts (that uses sans-serif
+    characters by default).
+    """
+    _sans = True
+
+
+##############################################################################
+# TeX-LIKE BOX MODEL
+
+# The following is based directly on the document 'woven' from the
+# TeX82 source code.  This information is also available in printed
+# form:
+#
+#    Knuth, Donald E.. 1986.  Computers and Typesetting, Volume B:
+#    TeX: The Program.  Addison-Wesley Professional.
+#
+# The most relevant "chapters" are:
+#    Data structures for boxes and their friends
+#    Shipping pages out (ship())
+#    Packaging (hpack() and vpack())
+#    Data structures for math mode
+#    Subroutines for math mode
+#    Typesetting math formulas
+#
+# Many of the docstrings below refer to a numbered "node" in that
+# book, e.g., node123
+#
+# Note that (as TeX) y increases downward, unlike many other parts of
+# matplotlib.
+
+# How much text shrinks when going to the next-smallest level.
+SHRINK_FACTOR   = 0.7
+# The number of different sizes of chars to use, beyond which they will not
+# get any smaller
+NUM_SIZE_LEVELS = 6
+
+
+class FontConstantsBase:
+    """
+    A set of constants that controls how certain things, such as sub-
+    and superscripts are laid out.  These are all metrics that can't
+    be reliably retrieved from the font metrics in the font itself.
+    """
+    # Percentage of x-height of additional horiz. space after sub/superscripts
+    script_space: T.ClassVar[float] = 0.05
+
+    # Percentage of x-height that sub/superscripts drop below the baseline
+    subdrop: T.ClassVar[float] = 0.4
+
+    # Percentage of x-height that superscripts are raised from the baseline
+    sup1: T.ClassVar[float] = 0.7
+
+    # Percentage of x-height that subscripts drop below the baseline
+    sub1: T.ClassVar[float] = 0.3
+
+    # Percentage of x-height that subscripts drop below the baseline when a
+    # superscript is present
+    sub2: T.ClassVar[float] = 0.5
+
+    # Percentage of x-height that sub/superscripts are offset relative to the
+    # nucleus edge for non-slanted nuclei
+    delta: T.ClassVar[float] = 0.025
+
+    # Additional percentage of last character height above 2/3 of the
+    # x-height that superscripts are offset relative to the subscript
+    # for slanted nuclei
+    delta_slanted: T.ClassVar[float] = 0.2
+
+    # Percentage of x-height that superscripts and subscripts are offset for
+    # integrals
+    delta_integral: T.ClassVar[float] = 0.1
+
+
+class ComputerModernFontConstants(FontConstantsBase):
+    script_space = 0.075
+    subdrop = 0.2
+    sup1 = 0.45
+    sub1 = 0.2
+    sub2 = 0.3
+    delta = 0.075
+    delta_slanted = 0.3
+    delta_integral = 0.3
+
+
+class STIXFontConstants(FontConstantsBase):
+    script_space = 0.1
+    sup1 = 0.8
+    sub2 = 0.6
+    delta = 0.05
+    delta_slanted = 0.3
+    delta_integral = 0.3
+
+
+class STIXSansFontConstants(FontConstantsBase):
+    script_space = 0.05
+    sup1 = 0.8
+    delta_slanted = 0.6
+    delta_integral = 0.3
+
+
+class DejaVuSerifFontConstants(FontConstantsBase):
+    pass
+
+
+class DejaVuSansFontConstants(FontConstantsBase):
+    pass
+
+
+# Maps font family names to the FontConstantBase subclass to use
+_font_constant_mapping = {
+    'DejaVu Sans': DejaVuSansFontConstants,
+    'DejaVu Sans Mono': DejaVuSansFontConstants,
+    'DejaVu Serif': DejaVuSerifFontConstants,
+    'cmb10': ComputerModernFontConstants,
+    'cmex10': ComputerModernFontConstants,
+    'cmmi10': ComputerModernFontConstants,
+    'cmr10': ComputerModernFontConstants,
+    'cmss10': ComputerModernFontConstants,
+    'cmsy10': ComputerModernFontConstants,
+    'cmtt10': ComputerModernFontConstants,
+    'STIXGeneral': STIXFontConstants,
+    'STIXNonUnicode': STIXFontConstants,
+    'STIXSizeFiveSym': STIXFontConstants,
+    'STIXSizeFourSym': STIXFontConstants,
+    'STIXSizeThreeSym': STIXFontConstants,
+    'STIXSizeTwoSym': STIXFontConstants,
+    'STIXSizeOneSym': STIXFontConstants,
+    # Map the fonts we used to ship, just for good measure
+    'Bitstream Vera Sans': DejaVuSansFontConstants,
+    'Bitstream Vera': DejaVuSansFontConstants,
+    }
+
+
+def _get_font_constant_set(state: ParserState) -> type[FontConstantsBase]:
+    constants = _font_constant_mapping.get(
+        state.fontset._get_font(state.font).family_name, FontConstantsBase)
+    # STIX sans isn't really its own fonts, just different code points
+    # in the STIX fonts, so we have to detect this one separately.
+    if (constants is STIXFontConstants and
+            isinstance(state.fontset, StixSansFonts)):
+        return STIXSansFontConstants
+    return constants
+
+
+class Node:
+    """A node in the TeX box model."""
+
+    def __init__(self) -> None:
+        self.size = 0
+
+    def __repr__(self) -> str:
+        return type(self).__name__
+
+    def get_kerning(self, next: Node | None) -> float:
+        return 0.0
+
+    def shrink(self) -> None:
+        """
+        Shrinks one level smaller.  There are only three levels of
+        sizes, after which things will no longer get smaller.
+        """
+        self.size += 1
+
+    def render(self, output: Output, x: float, y: float) -> None:
+        """Render this node."""
+
+
+class Box(Node):
+    """A node with a physical location."""
+
+    def __init__(self, width: float, height: float, depth: float) -> None:
+        super().__init__()
+        self.width  = width
+        self.height = height
+        self.depth  = depth
+
+    def shrink(self) -> None:
+        super().shrink()
+        if self.size < NUM_SIZE_LEVELS:
+            self.width  *= SHRINK_FACTOR
+            self.height *= SHRINK_FACTOR
+            self.depth  *= SHRINK_FACTOR
+
+    def render(self, output: Output,  # type: ignore[override]
+               x1: float, y1: float, x2: float, y2: float) -> None:
+        pass
+
+
+class Vbox(Box):
+    """A box with only height (zero width)."""
+
+    def __init__(self, height: float, depth: float):
+        super().__init__(0., height, depth)
+
+
+class Hbox(Box):
+    """A box with only width (zero height and depth)."""
+
+    def __init__(self, width: float):
+        super().__init__(width, 0., 0.)
+
+
+class Char(Node):
+    """
+    A single character.
+
+    Unlike TeX, the font information and metrics are stored with each `Char`
+    to make it easier to lookup the font metrics when needed.  Note that TeX
+    boxes have a width, height, and depth, unlike Type1 and TrueType which use
+    a full bounding box and an advance in the x-direction.  The metrics must
+    be converted to the TeX model, and the advance (if different from width)
+    must be converted into a `Kern` node when the `Char` is added to its parent
+    `Hlist`.
+    """
+
+    def __init__(self, c: str, state: ParserState):
+        super().__init__()
+        self.c = c
+        self.fontset = state.fontset
+        self.font = state.font
+        self.font_class = state.font_class
+        self.fontsize = state.fontsize
+        self.dpi = state.dpi
+        # The real width, height and depth will be set during the
+        # pack phase, after we know the real fontsize
+        self._update_metrics()
+
+    def __repr__(self) -> str:
+        return '`%s`' % self.c
+
+    def _update_metrics(self) -> None:
+        metrics = self._metrics = self.fontset.get_metrics(
+            self.font, self.font_class, self.c, self.fontsize, self.dpi)
+        if self.c == ' ':
+            self.width = metrics.advance
+        else:
+            self.width = metrics.width
+        self.height = metrics.iceberg
+        self.depth = -(metrics.iceberg - metrics.height)
+
+    def is_slanted(self) -> bool:
+        return self._metrics.slanted
+
+    def get_kerning(self, next: Node | None) -> float:
+        """
+        Return the amount of kerning between this and the given character.
+
+        This method is called when characters are strung together into `Hlist`
+        to create `Kern` nodes.
+        """
+        advance = self._metrics.advance - self.width
+        kern = 0.
+        if isinstance(next, Char):
+            kern = self.fontset.get_kern(
+                self.font, self.font_class, self.c, self.fontsize,
+                next.font, next.font_class, next.c, next.fontsize,
+                self.dpi)
+        return advance + kern
+
+    def render(self, output: Output, x: float, y: float) -> None:
+        self.fontset.render_glyph(
+            output, x, y,
+            self.font, self.font_class, self.c, self.fontsize, self.dpi)
+
+    def shrink(self) -> None:
+        super().shrink()
+        if self.size < NUM_SIZE_LEVELS:
+            self.fontsize *= SHRINK_FACTOR
+            self.width    *= SHRINK_FACTOR
+            self.height   *= SHRINK_FACTOR
+            self.depth    *= SHRINK_FACTOR
+
+
+class Accent(Char):
+    """
+    The font metrics need to be dealt with differently for accents,
+    since they are already offset correctly from the baseline in
+    TrueType fonts.
+    """
+    def _update_metrics(self) -> None:
+        metrics = self._metrics = self.fontset.get_metrics(
+            self.font, self.font_class, self.c, self.fontsize, self.dpi)
+        self.width = metrics.xmax - metrics.xmin
+        self.height = metrics.ymax - metrics.ymin
+        self.depth = 0
+
+    def shrink(self) -> None:
+        super().shrink()
+        self._update_metrics()
+
+    def render(self, output: Output, x: float, y: float) -> None:
+        self.fontset.render_glyph(
+            output, x - self._metrics.xmin, y + self._metrics.ymin,
+            self.font, self.font_class, self.c, self.fontsize, self.dpi)
+
+
+class List(Box):
+    """A list of nodes (either horizontal or vertical)."""
+
+    def __init__(self, elements: T.Sequence[Node]):
+        super().__init__(0., 0., 0.)
+        self.shift_amount = 0.   # An arbitrary offset
+        self.children = [*elements]  # The child nodes of this list
+        # The following parameters are set in the vpack and hpack functions
+        self.glue_set     = 0.   # The glue setting of this list
+        self.glue_sign    = 0    # 0: normal, -1: shrinking, 1: stretching
+        self.glue_order   = 0    # The order of infinity (0 - 3) for the glue
+
+    def __repr__(self) -> str:
+        return '{}<w={:.02f} h={:.02f} d={:.02f} s={:.02f}>[{}]'.format(
+            super().__repr__(),
+            self.width, self.height,
+            self.depth, self.shift_amount,
+            ', '.join([repr(x) for x in self.children]))
+
+    def _set_glue(self, x: float, sign: int, totals: list[float],
+                  error_type: str) -> None:
+        self.glue_order = o = next(
+            # Highest order of glue used by the members of this list.
+            (i for i in range(len(totals))[::-1] if totals[i] != 0), 0)
+        self.glue_sign = sign
+        if totals[o] != 0.:
+            self.glue_set = x / totals[o]
+        else:
+            self.glue_sign = 0
+            self.glue_ratio = 0.
+        if o == 0:
+            if len(self.children):
+                _log.warning("%s %s: %r",
+                             error_type, type(self).__name__, self)
+
+    def shrink(self) -> None:
+        for child in self.children:
+            child.shrink()
+        super().shrink()
+        if self.size < NUM_SIZE_LEVELS:
+            self.shift_amount *= SHRINK_FACTOR
+            self.glue_set     *= SHRINK_FACTOR
+
+
+class Hlist(List):
+    """A horizontal list of boxes."""
+
+    def __init__(self, elements: T.Sequence[Node], w: float = 0.0,
+                 m: T.Literal['additional', 'exactly'] = 'additional',
+                 do_kern: bool = True):
+        super().__init__(elements)
+        if do_kern:
+            self.kern()
+        self.hpack(w=w, m=m)
+
+    def kern(self) -> None:
+        """
+        Insert `Kern` nodes between `Char` nodes to set kerning.
+
+        The `Char` nodes themselves determine the amount of kerning they need
+        (in `~Char.get_kerning`), and this function just creates the correct
+        linked list.
+        """
+        new_children = []
+        num_children = len(self.children)
+        if num_children:
+            for i in range(num_children):
+                elem = self.children[i]
+                if i < num_children - 1:
+                    next = self.children[i + 1]
+                else:
+                    next = None
+
+                new_children.append(elem)
+                kerning_distance = elem.get_kerning(next)
+                if kerning_distance != 0.:
+                    kern = Kern(kerning_distance)
+                    new_children.append(kern)
+            self.children = new_children
+
+    def hpack(self, w: float = 0.0,
+              m: T.Literal['additional', 'exactly'] = 'additional') -> None:
+        r"""
+        Compute the dimensions of the resulting boxes, and adjust the glue if
+        one of those dimensions is pre-specified.  The computed sizes normally
+        enclose all of the material inside the new box; but some items may
+        stick out if negative glue is used, if the box is overfull, or if a
+        ``\vbox`` includes other boxes that have been shifted left.
+
+        Parameters
+        ----------
+        w : float, default: 0
+            A width.
+        m : {'exactly', 'additional'}, default: 'additional'
+            Whether to produce a box whose width is 'exactly' *w*; or a box
+            with the natural width of the contents, plus *w* ('additional').
+
+        Notes
+        -----
+        The defaults produce a box with the natural width of the contents.
+        """
+        # I don't know why these get reset in TeX.  Shift_amount is pretty
+        # much useless if we do.
+        # self.shift_amount = 0.
+        h = 0.
+        d = 0.
+        x = 0.
+        total_stretch = [0.] * 4
+        total_shrink = [0.] * 4
+        for p in self.children:
+            if isinstance(p, Char):
+                x += p.width
+                h = max(h, p.height)
+                d = max(d, p.depth)
+            elif isinstance(p, Box):
+                x += p.width
+                if not np.isinf(p.height) and not np.isinf(p.depth):
+                    s = getattr(p, 'shift_amount', 0.)
+                    h = max(h, p.height - s)
+                    d = max(d, p.depth + s)
+            elif isinstance(p, Glue):
+                glue_spec = p.glue_spec
+                x += glue_spec.width
+                total_stretch[glue_spec.stretch_order] += glue_spec.stretch
+                total_shrink[glue_spec.shrink_order] += glue_spec.shrink
+            elif isinstance(p, Kern):
+                x += p.width
+        self.height = h
+        self.depth = d
+
+        if m == 'additional':
+            w += x
+        self.width = w
+        x = w - x
+
+        if x == 0.:
+            self.glue_sign = 0
+            self.glue_order = 0
+            self.glue_ratio = 0.
+            return
+        if x > 0.:
+            self._set_glue(x, 1, total_stretch, "Overful")
+        else:
+            self._set_glue(x, -1, total_shrink, "Underful")
+
+
+class Vlist(List):
+    """A vertical list of boxes."""
+
+    def __init__(self, elements: T.Sequence[Node], h: float = 0.0,
+                 m: T.Literal['additional', 'exactly'] = 'additional'):
+        super().__init__(elements)
+        self.vpack(h=h, m=m)
+
+    def vpack(self, h: float = 0.0,
+              m: T.Literal['additional', 'exactly'] = 'additional',
+              l: float = np.inf) -> None:
+        """
+        Compute the dimensions of the resulting boxes, and to adjust the glue
+        if one of those dimensions is pre-specified.
+
+        Parameters
+        ----------
+        h : float, default: 0
+            A height.
+        m : {'exactly', 'additional'}, default: 'additional'
+            Whether to produce a box whose height is 'exactly' *h*; or a box
+            with the natural height of the contents, plus *h* ('additional').
+        l : float, default: np.inf
+            The maximum height.
+
+        Notes
+        -----
+        The defaults produce a box with the natural height of the contents.
+        """
+        # I don't know why these get reset in TeX.  Shift_amount is pretty
+        # much useless if we do.
+        # self.shift_amount = 0.
+        w = 0.
+        d = 0.
+        x = 0.
+        total_stretch = [0.] * 4
+        total_shrink = [0.] * 4
+        for p in self.children:
+            if isinstance(p, Box):
+                x += d + p.height
+                d = p.depth
+                if not np.isinf(p.width):
+                    s = getattr(p, 'shift_amount', 0.)
+                    w = max(w, p.width + s)
+            elif isinstance(p, Glue):
+                x += d
+                d = 0.
+                glue_spec = p.glue_spec
+                x += glue_spec.width
+                total_stretch[glue_spec.stretch_order] += glue_spec.stretch
+                total_shrink[glue_spec.shrink_order] += glue_spec.shrink
+            elif isinstance(p, Kern):
+                x += d + p.width
+                d = 0.
+            elif isinstance(p, Char):
+                raise RuntimeError(
+                    "Internal mathtext error: Char node found in Vlist")
+
+        self.width = w
+        if d > l:
+            x += d - l
+            self.depth = l
+        else:
+            self.depth = d
+
+        if m == 'additional':
+            h += x
+        self.height = h
+        x = h - x
+
+        if x == 0:
+            self.glue_sign = 0
+            self.glue_order = 0
+            self.glue_ratio = 0.
+            return
+
+        if x > 0.:
+            self._set_glue(x, 1, total_stretch, "Overful")
+        else:
+            self._set_glue(x, -1, total_shrink, "Underful")
+
+
+class Rule(Box):
+    """
+    A solid black rectangle.
+
+    It has *width*, *depth*, and *height* fields just as in an `Hlist`.
+    However, if any of these dimensions is inf, the actual value will be
+    determined by running the rule up to the boundary of the innermost
+    enclosing box.  This is called a "running dimension".  The width is never
+    running in an `Hlist`; the height and depth are never running in a `Vlist`.
+    """
+
+    def __init__(self, width: float, height: float, depth: float, state: ParserState):
+        super().__init__(width, height, depth)
+        self.fontset = state.fontset
+
+    def render(self, output: Output,  # type: ignore[override]
+               x: float, y: float, w: float, h: float) -> None:
+        self.fontset.render_rect_filled(output, x, y, x + w, y + h)
+
+
+class Hrule(Rule):
+    """Convenience class to create a horizontal rule."""
+
+    def __init__(self, state: ParserState, thickness: float | None = None):
+        if thickness is None:
+            thickness = state.get_current_underline_thickness()
+        height = depth = thickness * 0.5
+        super().__init__(np.inf, height, depth, state)
+
+
+class Vrule(Rule):
+    """Convenience class to create a vertical rule."""
+
+    def __init__(self, state: ParserState):
+        thickness = state.get_current_underline_thickness()
+        super().__init__(thickness, np.inf, np.inf, state)
+
+
+class _GlueSpec(NamedTuple):
+    width: float
+    stretch: float
+    stretch_order: int
+    shrink: float
+    shrink_order: int
+
+
+_GlueSpec._named = {  # type: ignore[attr-defined]
+    'fil':         _GlueSpec(0., 1., 1, 0., 0),
+    'fill':        _GlueSpec(0., 1., 2, 0., 0),
+    'filll':       _GlueSpec(0., 1., 3, 0., 0),
+    'neg_fil':     _GlueSpec(0., 0., 0, 1., 1),
+    'neg_fill':    _GlueSpec(0., 0., 0, 1., 2),
+    'neg_filll':   _GlueSpec(0., 0., 0, 1., 3),
+    'empty':       _GlueSpec(0., 0., 0, 0., 0),
+    'ss':          _GlueSpec(0., 1., 1, -1., 1),
+}
+
+
+class Glue(Node):
+    """
+    Most of the information in this object is stored in the underlying
+    ``_GlueSpec`` class, which is shared between multiple glue objects.
+    (This is a memory optimization which probably doesn't matter anymore, but
+    it's easier to stick to what TeX does.)
+    """
+
+    def __init__(self,
+                 glue_type: _GlueSpec | T.Literal["fil", "fill", "filll",
+                                                  "neg_fil", "neg_fill", "neg_filll",
+                                                  "empty", "ss"]):
+        super().__init__()
+        if isinstance(glue_type, str):
+            glue_spec = _GlueSpec._named[glue_type]  # type: ignore[attr-defined]
+        elif isinstance(glue_type, _GlueSpec):
+            glue_spec = glue_type
+        else:
+            raise ValueError("glue_type must be a glue spec name or instance")
+        self.glue_spec = glue_spec
+
+    def shrink(self) -> None:
+        super().shrink()
+        if self.size < NUM_SIZE_LEVELS:
+            g = self.glue_spec
+            self.glue_spec = g._replace(width=g.width * SHRINK_FACTOR)
+
+
+class HCentered(Hlist):
+    """
+    A convenience class to create an `Hlist` whose contents are
+    centered within its enclosing box.
+    """
+
+    def __init__(self, elements: list[Node]):
+        super().__init__([Glue('ss'), *elements, Glue('ss')], do_kern=False)
+
+
+class VCentered(Vlist):
+    """
+    A convenience class to create a `Vlist` whose contents are
+    centered within its enclosing box.
+    """
+
+    def __init__(self, elements: list[Node]):
+        super().__init__([Glue('ss'), *elements, Glue('ss')])
+
+
+class Kern(Node):
+    """
+    A `Kern` node has a width field to specify a (normally
+    negative) amount of spacing. This spacing correction appears in
+    horizontal lists between letters like A and V when the font
+    designer said that it looks better to move them closer together or
+    further apart. A kern node can also appear in a vertical list,
+    when its *width* denotes additional spacing in the vertical
+    direction.
+    """
+
+    height = 0
+    depth = 0
+
+    def __init__(self, width: float):
+        super().__init__()
+        self.width = width
+
+    def __repr__(self) -> str:
+        return "k%.02f" % self.width
+
+    def shrink(self) -> None:
+        super().shrink()
+        if self.size < NUM_SIZE_LEVELS:
+            self.width *= SHRINK_FACTOR
+
+
+class AutoHeightChar(Hlist):
+    """
+    A character as close to the given height and depth as possible.
+
+    When using a font with multiple height versions of some characters (such as
+    the BaKoMa fonts), the correct glyph will be selected, otherwise this will
+    always just return a scaled version of the glyph.
+    """
+
+    def __init__(self, c: str, height: float, depth: float, state: ParserState,
+                 always: bool = False, factor: float | None = None):
+        alternatives = state.fontset.get_sized_alternatives_for_symbol(
+            state.font, c)
+
+        xHeight = state.fontset.get_xheight(
+            state.font, state.fontsize, state.dpi)
+
+        state = state.copy()
+        target_total = height + depth
+        for fontname, sym in alternatives:
+            state.font = fontname
+            char = Char(sym, state)
+            # Ensure that size 0 is chosen when the text is regular sized but
+            # with descender glyphs by subtracting 0.2 * xHeight
+            if char.height + char.depth >= target_total - 0.2 * xHeight:
+                break
+
+        shift = 0.0
+        if state.font != 0 or len(alternatives) == 1:
+            if factor is None:
+                factor = target_total / (char.height + char.depth)
+            state.fontsize *= factor
+            char = Char(sym, state)
+
+            shift = (depth - char.depth)
+
+        super().__init__([char])
+        self.shift_amount = shift
+
+
+class AutoWidthChar(Hlist):
+    """
+    A character as close to the given width as possible.
+
+    When using a font with multiple width versions of some characters (such as
+    the BaKoMa fonts), the correct glyph will be selected, otherwise this will
+    always just return a scaled version of the glyph.
+    """
+
+    def __init__(self, c: str, width: float, state: ParserState, always: bool = False,
+                 char_class: type[Char] = Char):
+        alternatives = state.fontset.get_sized_alternatives_for_symbol(
+            state.font, c)
+
+        state = state.copy()
+        for fontname, sym in alternatives:
+            state.font = fontname
+            char = char_class(sym, state)
+            if char.width >= width:
+                break
+
+        factor = width / char.width
+        state.fontsize *= factor
+        char = char_class(sym, state)
+
+        super().__init__([char])
+        self.width = char.width
+
+
+def ship(box: Box, xy: tuple[float, float] = (0, 0)) -> Output:
+    """
+    Ship out *box* at offset *xy*, converting it to an `Output`.
+
+    Since boxes can be inside of boxes inside of boxes, the main work of `ship`
+    is done by two mutually recursive routines, `hlist_out` and `vlist_out`,
+    which traverse the `Hlist` nodes and `Vlist` nodes inside of horizontal
+    and vertical boxes.  The global variables used in TeX to store state as it
+    processes have become local variables here.
+    """
+    ox, oy = xy
+    cur_v = 0.
+    cur_h = 0.
+    off_h = ox
+    off_v = oy + box.height
+    output = Output(box)
+
+    def clamp(value: float) -> float:
+        return -1e9 if value < -1e9 else +1e9 if value > +1e9 else value
+
+    def hlist_out(box: Hlist) -> None:
+        nonlocal cur_v, cur_h, off_h, off_v
+
+        cur_g = 0
+        cur_glue = 0.
+        glue_order = box.glue_order
+        glue_sign = box.glue_sign
+        base_line = cur_v
+        left_edge = cur_h
+
+        for p in box.children:
+            if isinstance(p, Char):
+                p.render(output, cur_h + off_h, cur_v + off_v)
+                cur_h += p.width
+            elif isinstance(p, Kern):
+                cur_h += p.width
+            elif isinstance(p, List):
+                # node623
+                if len(p.children) == 0:
+                    cur_h += p.width
+                else:
+                    edge = cur_h
+                    cur_v = base_line + p.shift_amount
+                    if isinstance(p, Hlist):
+                        hlist_out(p)
+                    elif isinstance(p, Vlist):
+                        # p.vpack(box.height + box.depth, 'exactly')
+                        vlist_out(p)
+                    else:
+                        assert False, "unreachable code"
+                    cur_h = edge + p.width
+                    cur_v = base_line
+            elif isinstance(p, Box):
+                # node624
+                rule_height = p.height
+                rule_depth = p.depth
+                rule_width = p.width
+                if np.isinf(rule_height):
+                    rule_height = box.height
+                if np.isinf(rule_depth):
+                    rule_depth = box.depth
+                if rule_height > 0 and rule_width > 0:
+                    cur_v = base_line + rule_depth
+                    p.render(output,
+                             cur_h + off_h, cur_v + off_v,
+                             rule_width, rule_height)
+                    cur_v = base_line
+                cur_h += rule_width
+            elif isinstance(p, Glue):
+                # node625
+                glue_spec = p.glue_spec
+                rule_width = glue_spec.width - cur_g
+                if glue_sign != 0:  # normal
+                    if glue_sign == 1:  # stretching
+                        if glue_spec.stretch_order == glue_order:
+                            cur_glue += glue_spec.stretch
+                            cur_g = round(clamp(box.glue_set * cur_glue))
+                    elif glue_spec.shrink_order == glue_order:
+                        cur_glue += glue_spec.shrink
+                        cur_g = round(clamp(box.glue_set * cur_glue))
+                rule_width += cur_g
+                cur_h += rule_width
+
+    def vlist_out(box: Vlist) -> None:
+        nonlocal cur_v, cur_h, off_h, off_v
+
+        cur_g = 0
+        cur_glue = 0.
+        glue_order = box.glue_order
+        glue_sign = box.glue_sign
+        left_edge = cur_h
+        cur_v -= box.height
+        top_edge = cur_v
+
+        for p in box.children:
+            if isinstance(p, Kern):
+                cur_v += p.width
+            elif isinstance(p, List):
+                if len(p.children) == 0:
+                    cur_v += p.height + p.depth
+                else:
+                    cur_v += p.height
+                    cur_h = left_edge + p.shift_amount
+                    save_v = cur_v
+                    p.width = box.width
+                    if isinstance(p, Hlist):
+                        hlist_out(p)
+                    elif isinstance(p, Vlist):
+                        vlist_out(p)
+                    else:
+                        assert False, "unreachable code"
+                    cur_v = save_v + p.depth
+                    cur_h = left_edge
+            elif isinstance(p, Box):
+                rule_height = p.height
+                rule_depth = p.depth
+                rule_width = p.width
+                if np.isinf(rule_width):
+                    rule_width = box.width
+                rule_height += rule_depth
+                if rule_height > 0 and rule_depth > 0:
+                    cur_v += rule_height
+                    p.render(output,
+                             cur_h + off_h, cur_v + off_v,
+                             rule_width, rule_height)
+            elif isinstance(p, Glue):
+                glue_spec = p.glue_spec
+                rule_height = glue_spec.width - cur_g
+                if glue_sign != 0:  # normal
+                    if glue_sign == 1:  # stretching
+                        if glue_spec.stretch_order == glue_order:
+                            cur_glue += glue_spec.stretch
+                            cur_g = round(clamp(box.glue_set * cur_glue))
+                    elif glue_spec.shrink_order == glue_order:  # shrinking
+                        cur_glue += glue_spec.shrink
+                        cur_g = round(clamp(box.glue_set * cur_glue))
+                rule_height += cur_g
+                cur_v += rule_height
+            elif isinstance(p, Char):
+                raise RuntimeError(
+                    "Internal mathtext error: Char node found in vlist")
+
+    assert isinstance(box, Hlist)
+    hlist_out(box)
+    return output
+
+
+##############################################################################
+# PARSER
+
+
+def Error(msg: str) -> ParserElement:
+    """Helper class to raise parser errors."""
+    def raise_error(s: str, loc: int, toks: ParseResults) -> T.Any:
+        raise ParseFatalException(s, loc, msg)
+
+    return Empty().setParseAction(raise_error)
+
+
+class ParserState:
+    """
+    Parser state.
+
+    States are pushed and popped from a stack as necessary, and the "current"
+    state is always at the top of the stack.
+
+    Upon entering and leaving a group { } or math/non-math, the stack is pushed
+    and popped accordingly.
+    """
+
+    def __init__(self, fontset: Fonts, font: str, font_class: str, fontsize: float,
+                 dpi: float):
+        self.fontset = fontset
+        self._font = font
+        self.font_class = font_class
+        self.fontsize = fontsize
+        self.dpi = dpi
+
+    def copy(self) -> ParserState:
+        return copy.copy(self)
+
+    @property
+    def font(self) -> str:
+        return self._font
+
+    @font.setter
+    def font(self, name: str) -> None:
+        if name in ('rm', 'it', 'bf', 'bfit'):
+            self.font_class = name
+        self._font = name
+
+    def get_current_underline_thickness(self) -> float:
+        """Return the underline thickness for this state."""
+        return self.fontset.get_underline_thickness(
+            self.font, self.fontsize, self.dpi)
+
+
+def cmd(expr: str, args: ParserElement) -> ParserElement:
+    r"""
+    Helper to define TeX commands.
+
+    ``cmd("\cmd", args)`` is equivalent to
+    ``"\cmd" - (args | Error("Expected \cmd{arg}{...}"))`` where the names in
+    the error message are taken from element names in *args*.  If *expr*
+    already includes arguments (e.g. "\cmd{arg}{...}"), then they are stripped
+    when constructing the parse element, but kept (and *expr* is used as is) in
+    the error message.
+    """
+
+    def names(elt: ParserElement) -> T.Generator[str, None, None]:
+        if isinstance(elt, ParseExpression):
+            for expr in elt.exprs:
+                yield from names(expr)
+        elif elt.resultsName:
+            yield elt.resultsName
+
+    csname = expr.split("{", 1)[0]
+    err = (csname + "".join("{%s}" % name for name in names(args))
+           if expr == csname else expr)
+    return csname - (args | Error(f"Expected {err}"))
+
+
+class Parser:
+    """
+    A pyparsing-based parser for strings containing math expressions.
+
+    Raw text may also appear outside of pairs of ``$``.
+
+    The grammar is based directly on that in TeX, though it cuts a few corners.
+    """
+
+    class _MathStyle(enum.Enum):
+        DISPLAYSTYLE = 0
+        TEXTSTYLE = 1
+        SCRIPTSTYLE = 2
+        SCRIPTSCRIPTSTYLE = 3
+
+    _binary_operators = set(
+      '+ * - \N{MINUS SIGN}'
+      r'''
+      \pm             \sqcap                   \rhd
+      \mp             \sqcup                   \unlhd
+      \times          \vee                     \unrhd
+      \div            \wedge                   \oplus
+      \ast            \setminus                \ominus
+      \star           \wr                      \otimes
+      \circ           \diamond                 \oslash
+      \bullet         \bigtriangleup           \odot
+      \cdot           \bigtriangledown         \bigcirc
+      \cap            \triangleleft            \dagger
+      \cup            \triangleright           \ddagger
+      \uplus          \lhd                     \amalg
+      \dotplus        \dotminus                \Cap
+      \Cup            \barwedge                \boxdot
+      \boxminus       \boxplus                 \boxtimes
+      \curlyvee       \curlywedge              \divideontimes
+      \doublebarwedge \leftthreetimes          \rightthreetimes
+      \slash          \veebar                  \barvee
+      \cupdot         \intercal                \amalg
+      \circledcirc    \circleddash             \circledast
+      \boxbar         \obar                    \merge
+      \minuscolon     \dotsminusdots
+      '''.split())
+
+    _relation_symbols = set(r'''
+      = < > :
+      \leq          \geq          \equiv       \models
+      \prec         \succ         \sim         \perp
+      \preceq       \succeq       \simeq       \mid
+      \ll           \gg           \asymp       \parallel
+      \subset       \supset       \approx      \bowtie
+      \subseteq     \supseteq     \cong        \Join
+      \sqsubset     \sqsupset     \neq         \smile
+      \sqsubseteq   \sqsupseteq   \doteq       \frown
+      \in           \ni           \propto      \vdash
+      \dashv        \dots         \doteqdot    \leqq
+      \geqq         \lneqq        \gneqq       \lessgtr
+      \leqslant     \geqslant     \eqgtr       \eqless
+      \eqslantless  \eqslantgtr   \lesseqgtr   \backsim
+      \backsimeq    \lesssim      \gtrsim      \precsim
+      \precnsim     \gnsim        \lnsim       \succsim
+      \succnsim     \nsim         \lesseqqgtr  \gtreqqless
+      \gtreqless    \subseteqq    \supseteqq   \subsetneqq
+      \supsetneqq   \lessapprox   \approxeq    \gtrapprox
+      \precapprox   \succapprox   \precnapprox \succnapprox
+      \npreccurlyeq \nsucccurlyeq \nsqsubseteq \nsqsupseteq
+      \sqsubsetneq  \sqsupsetneq  \nlesssim    \ngtrsim
+      \nlessgtr     \ngtrless     \lnapprox    \gnapprox
+      \napprox      \approxeq     \approxident \lll
+      \ggg          \nparallel    \Vdash       \Vvdash
+      \nVdash       \nvdash       \vDash       \nvDash
+      \nVDash       \oequal       \simneqq     \triangle
+      \triangleq         \triangleeq         \triangleleft
+      \triangleright     \ntriangleleft      \ntriangleright
+      \trianglelefteq    \ntrianglelefteq    \trianglerighteq
+      \ntrianglerighteq  \blacktriangleleft  \blacktriangleright
+      \equalparallel     \measuredrightangle \varlrtriangle
+      \Doteq        \Bumpeq       \Subset      \Supset
+      \backepsilon  \because      \therefore   \bot
+      \top          \bumpeq       \circeq      \coloneq
+      \curlyeqprec  \curlyeqsucc  \eqcirc      \eqcolon
+      \eqsim        \fallingdotseq \gtrdot     \gtrless
+      \ltimes       \rtimes       \lessdot     \ne
+      \ncong        \nequiv       \ngeq        \ngtr
+      \nleq         \nless        \nmid        \notin
+      \nprec        \nsubset      \nsubseteq   \nsucc
+      \nsupset      \nsupseteq    \pitchfork   \preccurlyeq
+      \risingdotseq \subsetneq    \succcurlyeq \supsetneq
+      \varpropto    \vartriangleleft \scurel
+      \vartriangleright \rightangle \equal     \backcong
+      \eqdef        \wedgeq       \questeq     \between
+      \veeeq        \disin        \varisins    \isins
+      \isindot      \varisinobar  \isinobar    \isinvb
+      \isinE        \nisd         \varnis      \nis
+      \varniobar    \niobar       \bagmember   \ratio
+      \Equiv        \stareq       \measeq      \arceq
+      \rightassert  \rightModels  \smallin     \smallowns
+      \notsmallowns \nsimeq'''.split())
+
+    _arrow_symbols = set(r"""
+     \leftarrow \longleftarrow \uparrow \Leftarrow \Longleftarrow
+     \Uparrow \rightarrow \longrightarrow \downarrow \Rightarrow
+     \Longrightarrow \Downarrow \leftrightarrow \updownarrow
+     \longleftrightarrow \updownarrow \Leftrightarrow
+     \Longleftrightarrow \Updownarrow \mapsto \longmapsto \nearrow
+     \hookleftarrow \hookrightarrow \searrow \leftharpoonup
+     \rightharpoonup \swarrow \leftharpoondown \rightharpoondown
+     \nwarrow \rightleftharpoons \leadsto \dashrightarrow
+     \dashleftarrow \leftleftarrows \leftrightarrows \Lleftarrow
+     \Rrightarrow \twoheadleftarrow \leftarrowtail \looparrowleft
+     \leftrightharpoons \curvearrowleft \circlearrowleft \Lsh
+     \upuparrows \upharpoonleft \downharpoonleft \multimap
+     \leftrightsquigarrow \rightrightarrows \rightleftarrows
+     \rightrightarrows \rightleftarrows \twoheadrightarrow
+     \rightarrowtail \looparrowright \rightleftharpoons
+     \curvearrowright \circlearrowright \Rsh \downdownarrows
+     \upharpoonright \downharpoonright \rightsquigarrow \nleftarrow
+     \nrightarrow \nLeftarrow \nRightarrow \nleftrightarrow
+     \nLeftrightarrow \to \Swarrow \Searrow \Nwarrow \Nearrow
+     \leftsquigarrow \overleftarrow \overleftrightarrow \cwopencirclearrow
+     \downzigzagarrow \cupleftarrow \rightzigzagarrow \twoheaddownarrow
+     \updownarrowbar \twoheaduparrow \rightarrowbar \updownarrows
+     \barleftarrow \mapsfrom \mapsdown \mapsup \Ldsh \Rdsh
+     """.split())
+
+    _spaced_symbols = _binary_operators | _relation_symbols | _arrow_symbols
+
+    _punctuation_symbols = set(r', ; . ! \ldotp \cdotp'.split())
+
+    _overunder_symbols = set(r'''
+       \sum \prod \coprod \bigcap \bigcup \bigsqcup \bigvee
+       \bigwedge \bigodot \bigotimes \bigoplus \biguplus
+       '''.split())
+
+    _overunder_functions = set("lim liminf limsup sup max min".split())
+
+    _dropsub_symbols = set(r'\int \oint \iint \oiint \iiint \oiiint \iiiint'.split())
+
+    _fontnames = set("rm cal it tt sf bf bfit "
+                     "default bb frak scr regular".split())
+
+    _function_names = set("""
+      arccos csc ker min arcsin deg lg Pr arctan det lim sec arg dim
+      liminf sin cos exp limsup sinh cosh gcd ln sup cot hom log tan
+      coth inf max tanh""".split())
+
+    _ambi_delims = set(r"""
+      | \| / \backslash \uparrow \downarrow \updownarrow \Uparrow
+      \Downarrow \Updownarrow . \vert \Vert""".split())
+    _left_delims = set(r"""
+      ( [ \{ < \lfloor \langle \lceil \lbrace \leftbrace \lbrack \leftparen \lgroup
+      """.split())
+    _right_delims = set(r"""
+      ) ] \} > \rfloor \rangle \rceil \rbrace \rightbrace \rbrack \rightparen \rgroup
+      """.split())
+    _delims = _left_delims | _right_delims | _ambi_delims
+
+    _small_greek = set([unicodedata.name(chr(i)).split()[-1].lower() for i in
+                       range(ord('\N{GREEK SMALL LETTER ALPHA}'),
+                             ord('\N{GREEK SMALL LETTER OMEGA}') + 1)])
+    _latin_alphabets = set(string.ascii_letters)
+
+    def __init__(self) -> None:
+        p = types.SimpleNamespace()
+
+        def set_names_and_parse_actions() -> None:
+            for key, val in vars(p).items():
+                if not key.startswith('_'):
+                    # Set names on (almost) everything -- very useful for debugging
+                    # token, placeable, and auto_delim are forward references which
+                    # are left without names to ensure useful error messages
+                    if key not in ("token", "placeable", "auto_delim"):
+                        val.setName(key)
+                    # Set actions
+                    if hasattr(self, key):
+                        val.setParseAction(getattr(self, key))
+
+        # Root definitions.
+
+        # In TeX parlance, a csname is a control sequence name (a "\foo").
+        def csnames(group: str, names: Iterable[str]) -> Regex:
+            ends_with_alpha = []
+            ends_with_nonalpha = []
+            for name in names:
+                if name[-1].isalpha():
+                    ends_with_alpha.append(name)
+                else:
+                    ends_with_nonalpha.append(name)
+            return Regex(
+                r"\\(?P<{group}>(?:{alpha})(?![A-Za-z]){additional}{nonalpha})".format(
+                    group=group,
+                    alpha="|".join(map(re.escape, ends_with_alpha)),
+                    additional="|" if ends_with_nonalpha else "",
+                    nonalpha="|".join(map(re.escape, ends_with_nonalpha)),
+                )
+            )
+
+        p.float_literal  = Regex(r"[-+]?([0-9]+\.?[0-9]*|\.[0-9]+)")
+        p.space          = oneOf(self._space_widths)("space")
+
+        p.style_literal  = oneOf(
+            [str(e.value) for e in self._MathStyle])("style_literal")
+
+        p.symbol         = Regex(
+            r"[a-zA-Z0-9 +\-*/<>=:,.;!\?&'@()\[\]|\U00000080-\U0001ffff]"
+            r"|\\[%${}\[\]_|]"
+            + r"|\\(?:{})(?![A-Za-z])".format(
+                "|".join(map(re.escape, tex2uni)))
+        )("sym").leaveWhitespace()
+        p.unknown_symbol = Regex(r"\\[A-Za-z]+")("name")
+
+        p.font           = csnames("font", self._fontnames)
+        p.start_group    = Optional(r"\math" + oneOf(self._fontnames)("font")) + "{"
+        p.end_group      = Literal("}")
+
+        p.delim          = oneOf(self._delims)
+
+        # Mutually recursive definitions.  (Minimizing the number of Forward
+        # elements is important for speed.)
+        p.auto_delim       = Forward()
+        p.placeable        = Forward()
+        p.named_placeable  = Forward()
+        p.required_group   = Forward()
+        p.optional_group   = Forward()
+        p.token            = Forward()
+
+        # Workaround for placable being part of a cycle of definitions
+        # calling `p.placeable("name")` results in a copy, so not guaranteed
+        # to get the definition added after it is used.
+        # ref https://github.com/matplotlib/matplotlib/issues/25204
+        # xref https://github.com/pyparsing/pyparsing/issues/95
+        p.named_placeable <<= p.placeable
+
+        set_names_and_parse_actions()  # for mutually recursive definitions.
+
+        p.optional_group <<= "{" + ZeroOrMore(p.token)("group") + "}"
+        p.required_group <<= "{" + OneOrMore(p.token)("group") + "}"
+
+        p.customspace = cmd(r"\hspace", "{" + p.float_literal("space") + "}")
+
+        p.accent = (
+            csnames("accent", [*self._accent_map, *self._wide_accents])
+            - p.named_placeable("sym"))
+
+        p.function = csnames("name", self._function_names)
+
+        p.group = p.start_group + ZeroOrMore(p.token)("group") + p.end_group
+        p.unclosed_group = (p.start_group + ZeroOrMore(p.token)("group") + StringEnd())
+
+        p.frac  = cmd(r"\frac", p.required_group("num") + p.required_group("den"))
+        p.dfrac = cmd(r"\dfrac", p.required_group("num") + p.required_group("den"))
+        p.binom = cmd(r"\binom", p.required_group("num") + p.required_group("den"))
+
+        p.genfrac = cmd(
+            r"\genfrac",
+            "{" + Optional(p.delim)("ldelim") + "}"
+            + "{" + Optional(p.delim)("rdelim") + "}"
+            + "{" + p.float_literal("rulesize") + "}"
+            + "{" + Optional(p.style_literal)("style") + "}"
+            + p.required_group("num")
+            + p.required_group("den"))
+
+        p.sqrt = cmd(
+            r"\sqrt{value}",
+            Optional("[" + OneOrMore(NotAny("]") + p.token)("root") + "]")
+            + p.required_group("value"))
+
+        p.overline = cmd(r"\overline", p.required_group("body"))
+
+        p.overset  = cmd(
+            r"\overset",
+            p.optional_group("annotation") + p.optional_group("body"))
+        p.underset = cmd(
+            r"\underset",
+            p.optional_group("annotation") + p.optional_group("body"))
+
+        p.text = cmd(r"\text", QuotedString('{', '\\', endQuoteChar="}"))
+
+        p.substack = cmd(r"\substack",
+                           nested_expr(opener="{", closer="}",
+                                       content=Group(OneOrMore(p.token)) +
+                                       ZeroOrMore(Literal("\\\\").suppress()))("parts"))
+
+        p.subsuper = (
+            (Optional(p.placeable)("nucleus")
+             + OneOrMore(oneOf(["_", "^"]) - p.placeable)("subsuper")
+             + Regex("'*")("apostrophes"))
+            | Regex("'+")("apostrophes")
+            | (p.named_placeable("nucleus") + Regex("'*")("apostrophes"))
+        )
+
+        p.simple = p.space | p.customspace | p.font | p.subsuper
+
+        p.token <<= (
+            p.simple
+            | p.auto_delim
+            | p.unclosed_group
+            | p.unknown_symbol  # Must be last
+        )
+
+        p.operatorname = cmd(r"\operatorname", "{" + ZeroOrMore(p.simple)("name") + "}")
+
+        p.boldsymbol = cmd(
+            r"\boldsymbol", "{" + ZeroOrMore(p.simple)("value") + "}")
+
+        p.placeable     <<= (
+            p.accent     # Must be before symbol as all accents are symbols
+            | p.symbol   # Must be second to catch all named symbols and single
+                         # chars not in a group
+            | p.function
+            | p.operatorname
+            | p.group
+            | p.frac
+            | p.dfrac
+            | p.binom
+            | p.genfrac
+            | p.overset
+            | p.underset
+            | p.sqrt
+            | p.overline
+            | p.text
+            | p.boldsymbol
+            | p.substack
+        )
+
+        mdelim = r"\middle" - (p.delim("mdelim") | Error("Expected a delimiter"))
+        p.auto_delim    <<= (
+            r"\left" - (p.delim("left") | Error("Expected a delimiter"))
+            + ZeroOrMore(p.simple | p.auto_delim | mdelim)("mid")
+            + r"\right" - (p.delim("right") | Error("Expected a delimiter"))
+        )
+
+        # Leaf definitions.
+        p.math          = OneOrMore(p.token)
+        p.math_string   = QuotedString('$', '\\', unquoteResults=False)
+        p.non_math      = Regex(r"(?:(?:\\[$])|[^$])*").leaveWhitespace()
+        p.main          = (
+            p.non_math + ZeroOrMore(p.math_string + p.non_math) + StringEnd()
+        )
+        set_names_and_parse_actions()  # for leaf definitions.
+
+        self._expression = p.main
+        self._math_expression = p.math
+
+        # To add space to nucleus operators after sub/superscripts
+        self._in_subscript_or_superscript = False
+
+    def parse(self, s: str, fonts_object: Fonts, fontsize: float, dpi: float) -> Hlist:
+        """
+        Parse expression *s* using the given *fonts_object* for
+        output, at the given *fontsize* and *dpi*.
+
+        Returns the parse tree of `Node` instances.
+        """
+        self._state_stack = [
+            ParserState(fonts_object, 'default', 'rm', fontsize, dpi)]
+        self._em_width_cache: dict[tuple[str, float, float], float] = {}
+        try:
+            result = self._expression.parseString(s)
+        except ParseBaseException as err:
+            # explain becomes a plain method on pyparsing 3 (err.explain(0)).
+            raise ValueError("\n" + ParseException.explain(err, 0)) from None
+        self._state_stack = []
+        self._in_subscript_or_superscript = False
+        # prevent operator spacing from leaking into a new expression
+        self._em_width_cache = {}
+        ParserElement.resetCache()
+        return T.cast(Hlist, result[0])  # Known return type from main.
+
+    def get_state(self) -> ParserState:
+        """Get the current `State` of the parser."""
+        return self._state_stack[-1]
+
+    def pop_state(self) -> None:
+        """Pop a `State` off of the stack."""
+        self._state_stack.pop()
+
+    def push_state(self) -> None:
+        """Push a new `State` onto the stack, copying the current state."""
+        self._state_stack.append(self.get_state().copy())
+
+    def main(self, toks: ParseResults) -> list[Hlist]:
+        return [Hlist(toks.asList())]
+
+    def math_string(self, toks: ParseResults) -> ParseResults:
+        return self._math_expression.parseString(toks[0][1:-1], parseAll=True)
+
+    def math(self, toks: ParseResults) -> T.Any:
+        hlist = Hlist(toks.asList())
+        self.pop_state()
+        return [hlist]
+
+    def non_math(self, toks: ParseResults) -> T.Any:
+        s = toks[0].replace(r'\$', '$')
+        symbols = [Char(c, self.get_state()) for c in s]
+        hlist = Hlist(symbols)
+        # We're going into math now, so set font to 'it'
+        self.push_state()
+        self.get_state().font = mpl.rcParams['mathtext.default']
+        return [hlist]
+
+    float_literal = staticmethod(pyparsing_common.convertToFloat)
+
+    def text(self, toks: ParseResults) -> T.Any:
+        self.push_state()
+        state = self.get_state()
+        state.font = 'rm'
+        hlist = Hlist([Char(c, state) for c in toks[1]])
+        self.pop_state()
+        return [hlist]
+
+    def _make_space(self, percentage: float) -> Kern:
+        # In TeX, an em (the unit usually used to measure horizontal lengths)
+        # is not the width of the character 'm'; it is the same in different
+        # font styles (e.g. roman or italic). Mathtext, however, uses 'm' in
+        # the italic style so that horizontal spaces don't depend on the
+        # current font style.
+        state = self.get_state()
+        key = (state.font, state.fontsize, state.dpi)
+        width = self._em_width_cache.get(key)
+        if width is None:
+            metrics = state.fontset.get_metrics(
+                'it', mpl.rcParams['mathtext.default'], 'm',
+                state.fontsize, state.dpi)
+            width = metrics.advance
+            self._em_width_cache[key] = width
+        return Kern(width * percentage)
+
+    _space_widths = {
+        r'\,':         0.16667,   # 3/18 em = 3 mu
+        r'\thinspace': 0.16667,   # 3/18 em = 3 mu
+        r'\/':         0.16667,   # 3/18 em = 3 mu
+        r'\>':         0.22222,   # 4/18 em = 4 mu
+        r'\:':         0.22222,   # 4/18 em = 4 mu
+        r'\;':         0.27778,   # 5/18 em = 5 mu
+        r'\ ':         0.33333,   # 6/18 em = 6 mu
+        r'~':          0.33333,   # 6/18 em = 6 mu, nonbreakable
+        r'\enspace':   0.5,       # 9/18 em = 9 mu
+        r'\quad':      1,         # 1 em = 18 mu
+        r'\qquad':     2,         # 2 em = 36 mu
+        r'\!':         -0.16667,  # -3/18 em = -3 mu
+    }
+
+    def space(self, toks: ParseResults) -> T.Any:
+        num = self._space_widths[toks["space"]]
+        box = self._make_space(num)
+        return [box]
+
+    def customspace(self, toks: ParseResults) -> T.Any:
+        return [self._make_space(toks["space"])]
+
+    def symbol(self, s: str, loc: int,
+               toks: ParseResults | dict[str, str]) -> T.Any:
+        c = toks["sym"]
+        if c == "-":
+            # "U+2212 minus sign is the preferred representation of the unary
+            # and binary minus sign rather than the ASCII-derived U+002D
+            # hyphen-minus, because minus sign is unambiguous and because it
+            # is rendered with a more desirable length, usually longer than a
+            # hyphen." (https://www.unicode.org/reports/tr25/)
+            c = "\N{MINUS SIGN}"
+        try:
+            char = Char(c, self.get_state())
+        except ValueError as err:
+            raise ParseFatalException(s, loc,
+                                      "Unknown symbol: %s" % c) from err
+
+        if c in self._spaced_symbols:
+            # iterate until we find previous character, needed for cases
+            # such as $=-2$, ${ -2}$, $ -2$, or $   -2$.
+            prev_char = next((c for c in s[:loc][::-1] if c != ' '), '')
+            # Binary operators at start of string should not be spaced
+            # Also, operators in sub- or superscripts should not be spaced
+            if (self._in_subscript_or_superscript or (
+                    c in self._binary_operators and (
+                    len(s[:loc].split()) == 0 or prev_char in {
+                        '{', *self._left_delims, *self._relation_symbols}))):
+                return [char]
+            else:
+                return [Hlist([self._make_space(0.2),
+                               char,
+                               self._make_space(0.2)],
+                              do_kern=True)]
+        elif c in self._punctuation_symbols:
+            prev_char = next((c for c in s[:loc][::-1] if c != ' '), '')
+            next_char = next((c for c in s[loc + 1:] if c != ' '), '')
+
+            # Do not space commas between brackets
+            if c == ',':
+                if prev_char == '{' and next_char == '}':
+                    return [char]
+
+            # Do not space dots as decimal separators
+            if c == '.' and prev_char.isdigit() and next_char.isdigit():
+                return [char]
+            else:
+                return [Hlist([char, self._make_space(0.2)], do_kern=True)]
+        return [char]
+
+    def unknown_symbol(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        raise ParseFatalException(s, loc, f"Unknown symbol: {toks['name']}")
+
+    _accent_map = {
+        r'hat':            r'\circumflexaccent',
+        r'breve':          r'\combiningbreve',
+        r'bar':            r'\combiningoverline',
+        r'grave':          r'\combininggraveaccent',
+        r'acute':          r'\combiningacuteaccent',
+        r'tilde':          r'\combiningtilde',
+        r'dot':            r'\combiningdotabove',
+        r'ddot':           r'\combiningdiaeresis',
+        r'dddot':          r'\combiningthreedotsabove',
+        r'ddddot':         r'\combiningfourdotsabove',
+        r'vec':            r'\combiningrightarrowabove',
+        r'"':              r'\combiningdiaeresis',
+        r"`":              r'\combininggraveaccent',
+        r"'":              r'\combiningacuteaccent',
+        r'~':              r'\combiningtilde',
+        r'.':              r'\combiningdotabove',
+        r'^':              r'\circumflexaccent',
+        r'overrightarrow': r'\rightarrow',
+        r'overleftarrow':  r'\leftarrow',
+        r'mathring':       r'\circ',
+    }
+
+    _wide_accents = set(r"widehat widetilde widebar".split())
+
+    def accent(self, toks: ParseResults) -> T.Any:
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+        accent = toks["accent"]
+        sym = toks["sym"]
+        accent_box: Node
+        if accent in self._wide_accents:
+            accent_box = AutoWidthChar(
+                '\\' + accent, sym.width, state, char_class=Accent)
+        else:
+            accent_box = Accent(self._accent_map[accent], state)
+        if accent == 'mathring':
+            accent_box.shrink()
+            accent_box.shrink()
+        centered = HCentered([Hbox(sym.width / 4.0), accent_box])
+        centered.hpack(sym.width, 'exactly')
+        return Vlist([
+                centered,
+                Vbox(0., thickness * 2.0),
+                Hlist([sym])
+                ])
+
+    def function(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        hlist = self.operatorname(s, loc, toks)
+        hlist.function_name = toks["name"]
+        return hlist
+
+    def operatorname(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        self.push_state()
+        state = self.get_state()
+        state.font = 'rm'
+        hlist_list: list[Node] = []
+        # Change the font of Chars, but leave Kerns alone
+        name = toks["name"]
+        for c in name:
+            if isinstance(c, Char):
+                c.font = 'rm'
+                c._update_metrics()
+                hlist_list.append(c)
+            elif isinstance(c, str):
+                hlist_list.append(Char(c, state))
+            else:
+                hlist_list.append(c)
+        next_char_loc = loc + len(name) + 1
+        if isinstance(name, ParseResults):
+            next_char_loc += len('operatorname{}')
+        next_char = next((c for c in s[next_char_loc:] if c != ' '), '')
+        delimiters = self._delims | {'^', '_'}
+        if (next_char not in delimiters and
+                name not in self._overunder_functions):
+            # Add thin space except when followed by parenthesis, bracket, etc.
+            hlist_list += [self._make_space(self._space_widths[r'\,'])]
+        self.pop_state()
+        # if followed by a super/subscript, set flag to true
+        # This flag tells subsuper to add space after this operator
+        if next_char in {'^', '_'}:
+            self._in_subscript_or_superscript = True
+        else:
+            self._in_subscript_or_superscript = False
+
+        return Hlist(hlist_list)
+
+    def start_group(self, toks: ParseResults) -> T.Any:
+        self.push_state()
+        # Deal with LaTeX-style font tokens
+        if toks.get("font"):
+            self.get_state().font = toks.get("font")
+        return []
+
+    def group(self, toks: ParseResults) -> T.Any:
+        grp = Hlist(toks.get("group", []))
+        return [grp]
+
+    def required_group(self, toks: ParseResults) -> T.Any:
+        return Hlist(toks.get("group", []))
+
+    optional_group = required_group
+
+    def end_group(self) -> T.Any:
+        self.pop_state()
+        return []
+
+    def unclosed_group(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        raise ParseFatalException(s, len(s), "Expected '}'")
+
+    def font(self, toks: ParseResults) -> T.Any:
+        self.get_state().font = toks["font"]
+        return []
+
+    def is_overunder(self, nucleus: Node) -> bool:
+        if isinstance(nucleus, Char):
+            return nucleus.c in self._overunder_symbols
+        elif isinstance(nucleus, Hlist) and hasattr(nucleus, 'function_name'):
+            return nucleus.function_name in self._overunder_functions
+        return False
+
+    def is_dropsub(self, nucleus: Node) -> bool:
+        if isinstance(nucleus, Char):
+            return nucleus.c in self._dropsub_symbols
+        return False
+
+    def is_slanted(self, nucleus: Node) -> bool:
+        if isinstance(nucleus, Char):
+            return nucleus.is_slanted()
+        return False
+
+    def subsuper(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        nucleus = toks.get("nucleus", Hbox(0))
+        subsuper = toks.get("subsuper", [])
+        napostrophes = len(toks.get("apostrophes", []))
+
+        if not subsuper and not napostrophes:
+            return nucleus
+
+        sub = super = None
+        while subsuper:
+            op, arg, *subsuper = subsuper
+            if op == '_':
+                if sub is not None:
+                    raise ParseFatalException("Double subscript")
+                sub = arg
+            else:
+                if super is not None:
+                    raise ParseFatalException("Double superscript")
+                super = arg
+
+        state = self.get_state()
+        rule_thickness = state.fontset.get_underline_thickness(
+            state.font, state.fontsize, state.dpi)
+        xHeight = state.fontset.get_xheight(
+            state.font, state.fontsize, state.dpi)
+
+        if napostrophes:
+            if super is None:
+                super = Hlist([])
+            for i in range(napostrophes):
+                super.children.extend(self.symbol(s, loc, {"sym": "\\prime"}))
+            # kern() and hpack() needed to get the metrics right after
+            # extending
+            super.kern()
+            super.hpack()
+
+        # Handle over/under symbols, such as sum or prod
+        if self.is_overunder(nucleus):
+            vlist = []
+            shift = 0.
+            width = nucleus.width
+            if super is not None:
+                super.shrink()
+                width = max(width, super.width)
+            if sub is not None:
+                sub.shrink()
+                width = max(width, sub.width)
+
+            vgap = rule_thickness * 3.0
+            if super is not None:
+                hlist = HCentered([super])
+                hlist.hpack(width, 'exactly')
+                vlist.extend([hlist, Vbox(0, vgap)])
+            hlist = HCentered([nucleus])
+            hlist.hpack(width, 'exactly')
+            vlist.append(hlist)
+            if sub is not None:
+                hlist = HCentered([sub])
+                hlist.hpack(width, 'exactly')
+                vlist.extend([Vbox(0, vgap), hlist])
+                shift = hlist.height + vgap + nucleus.depth
+            vlt = Vlist(vlist)
+            vlt.shift_amount = shift
+            result = Hlist([vlt])
+            return [result]
+
+        # We remove kerning on the last character for consistency (otherwise
+        # it will compute kerning based on non-shrunk characters and may put
+        # them too close together when superscripted)
+        # We change the width of the last character to match the advance to
+        # consider some fonts with weird metrics: e.g. stix's f has a width of
+        # 7.75 and a kerning of -4.0 for an advance of 3.72, and we want to put
+        # the superscript at the advance
+        last_char = nucleus
+        if isinstance(nucleus, Hlist):
+            new_children = nucleus.children
+            if len(new_children):
+                # remove last kern
+                if (isinstance(new_children[-1], Kern) and
+                        hasattr(new_children[-2], '_metrics')):
+                    new_children = new_children[:-1]
+                last_char = new_children[-1]
+                if hasattr(last_char, '_metrics'):
+                    last_char.width = last_char._metrics.advance
+            # create new Hlist without kerning
+            nucleus = Hlist(new_children, do_kern=False)
+        else:
+            if isinstance(nucleus, Char):
+                last_char.width = last_char._metrics.advance
+            nucleus = Hlist([nucleus])
+
+        # Handle regular sub/superscripts
+        constants = _get_font_constant_set(state)
+        lc_height   = last_char.height
+        lc_baseline = 0
+        if self.is_dropsub(last_char):
+            lc_baseline = last_char.depth
+
+        # Compute kerning for sub and super
+        superkern = constants.delta * xHeight
+        subkern = constants.delta * xHeight
+        if self.is_slanted(last_char):
+            superkern += constants.delta * xHeight
+            superkern += (constants.delta_slanted *
+                          (lc_height - xHeight * 2. / 3.))
+            if self.is_dropsub(last_char):
+                subkern = (3 * constants.delta -
+                           constants.delta_integral) * lc_height
+                superkern = (3 * constants.delta +
+                             constants.delta_integral) * lc_height
+            else:
+                subkern = 0
+
+        x: List
+        if super is None:
+            # node757
+            # Note: One of super or sub must be a Node if we're in this function, but
+            # mypy can't know this, since it can't interpret pyparsing expressions,
+            # hence the cast.
+            x = Hlist([Kern(subkern), T.cast(Node, sub)])
+            x.shrink()
+            if self.is_dropsub(last_char):
+                shift_down = lc_baseline + constants.subdrop * xHeight
+            else:
+                shift_down = constants.sub1 * xHeight
+            x.shift_amount = shift_down
+        else:
+            x = Hlist([Kern(superkern), super])
+            x.shrink()
+            if self.is_dropsub(last_char):
+                shift_up = lc_height - constants.subdrop * xHeight
+            else:
+                shift_up = constants.sup1 * xHeight
+            if sub is None:
+                x.shift_amount = -shift_up
+            else:  # Both sub and superscript
+                y = Hlist([Kern(subkern), sub])
+                y.shrink()
+                if self.is_dropsub(last_char):
+                    shift_down = lc_baseline + constants.subdrop * xHeight
+                else:
+                    shift_down = constants.sub2 * xHeight
+                # If sub and superscript collide, move super up
+                clr = (2.0 * rule_thickness -
+                       ((shift_up - x.depth) - (y.height - shift_down)))
+                if clr > 0.:
+                    shift_up += clr
+                x = Vlist([
+                    x,
+                    Kern((shift_up - x.depth) - (y.height - shift_down)),
+                    y])
+                x.shift_amount = shift_down
+
+        if not self.is_dropsub(last_char):
+            x.width += constants.script_space * xHeight
+
+        # Do we need to add a space after the nucleus?
+        # To find out, check the flag set by operatorname
+        spaced_nucleus = [nucleus, x]
+        if self._in_subscript_or_superscript:
+            spaced_nucleus += [self._make_space(self._space_widths[r'\,'])]
+            self._in_subscript_or_superscript = False
+
+        result = Hlist(spaced_nucleus)
+        return [result]
+
+    def _genfrac(self, ldelim: str, rdelim: str, rule: float | None, style: _MathStyle,
+                 num: Hlist, den: Hlist) -> T.Any:
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+
+        for _ in range(style.value):
+            num.shrink()
+            den.shrink()
+        cnum = HCentered([num])
+        cden = HCentered([den])
+        width = max(num.width, den.width)
+        cnum.hpack(width, 'exactly')
+        cden.hpack(width, 'exactly')
+        vlist = Vlist([cnum,                      # numerator
+                       Vbox(0, thickness * 2.0),  # space
+                       Hrule(state, rule),        # rule
+                       Vbox(0, thickness * 2.0),  # space
+                       cden                       # denominator
+                       ])
+
+        # Shift so the fraction line sits in the middle of the
+        # equals sign
+        metrics = state.fontset.get_metrics(
+            state.font, mpl.rcParams['mathtext.default'],
+            '=', state.fontsize, state.dpi)
+        shift = (cden.height -
+                 ((metrics.ymax + metrics.ymin) / 2 -
+                  thickness * 3.0))
+        vlist.shift_amount = shift
+
+        result = [Hlist([vlist, Hbox(thickness * 2.)])]
+        if ldelim or rdelim:
+            if ldelim == '':
+                ldelim = '.'
+            if rdelim == '':
+                rdelim = '.'
+            return self._auto_sized_delimiter(ldelim,
+                                              T.cast(list[Box | Char | str],
+                                                     result),
+                                              rdelim)
+        return result
+
+    def style_literal(self, toks: ParseResults) -> T.Any:
+        return self._MathStyle(int(toks["style_literal"]))
+
+    def genfrac(self, toks: ParseResults) -> T.Any:
+        return self._genfrac(
+            toks.get("ldelim", ""), toks.get("rdelim", ""),
+            toks["rulesize"], toks.get("style", self._MathStyle.TEXTSTYLE),
+            toks["num"], toks["den"])
+
+    def frac(self, toks: ParseResults) -> T.Any:
+        return self._genfrac(
+            "", "", self.get_state().get_current_underline_thickness(),
+            self._MathStyle.TEXTSTYLE, toks["num"], toks["den"])
+
+    def dfrac(self, toks: ParseResults) -> T.Any:
+        return self._genfrac(
+            "", "", self.get_state().get_current_underline_thickness(),
+            self._MathStyle.DISPLAYSTYLE, toks["num"], toks["den"])
+
+    def binom(self, toks: ParseResults) -> T.Any:
+        return self._genfrac(
+            "(", ")", 0,
+            self._MathStyle.TEXTSTYLE, toks["num"], toks["den"])
+
+    def _genset(self, s: str, loc: int, toks: ParseResults) -> T.Any:
+        annotation = toks["annotation"]
+        body = toks["body"]
+        thickness = self.get_state().get_current_underline_thickness()
+
+        annotation.shrink()
+        centered_annotation = HCentered([annotation])
+        centered_body = HCentered([body])
+        width = max(centered_annotation.width, centered_body.width)
+        centered_annotation.hpack(width, 'exactly')
+        centered_body.hpack(width, 'exactly')
+
+        vgap = thickness * 3
+        if s[loc + 1] == "u":  # \underset
+            vlist = Vlist([
+                centered_body,               # body
+                Vbox(0, vgap),               # space
+                centered_annotation          # annotation
+            ])
+            # Shift so the body sits in the same vertical position
+            vlist.shift_amount = centered_body.depth + centered_annotation.height + vgap
+        else:  # \overset
+            vlist = Vlist([
+                centered_annotation,         # annotation
+                Vbox(0, vgap),               # space
+                centered_body                # body
+            ])
+
+        # To add horizontal gap between symbols: wrap the Vlist into
+        # an Hlist and extend it with an Hbox(0, horizontal_gap)
+        return vlist
+
+    overset = underset = _genset
+
+    def sqrt(self, toks: ParseResults) -> T.Any:
+        root = toks.get("root")
+        body = toks["value"]
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+
+        # Determine the height of the body, and add a little extra to
+        # the height so it doesn't seem cramped
+        height = body.height - body.shift_amount + thickness * 5.0
+        depth = body.depth + body.shift_amount
+        check = AutoHeightChar(r'\__sqrt__', height, depth, state, always=True)
+        height = check.height - check.shift_amount
+        depth = check.depth + check.shift_amount
+
+        # Put a little extra space to the left and right of the body
+        padded_body = Hlist([Hbox(2 * thickness), body, Hbox(2 * thickness)])
+        rightside = Vlist([Hrule(state), Glue('fill'), padded_body])
+        # Stretch the glue between the hrule and the body
+        rightside.vpack(height + (state.fontsize * state.dpi) / (100.0 * 12.0),
+                        'exactly', depth)
+
+        # Add the root and shift it upward so it is above the tick.
+        # The value of 0.6 is a hard-coded hack ;)
+        if not root:
+            root = Box(check.width * 0.5, 0., 0.)
+        else:
+            root = Hlist(root)
+            root.shrink()
+            root.shrink()
+
+        root_vlist = Vlist([Hlist([root])])
+        root_vlist.shift_amount = -height * 0.6
+
+        hlist = Hlist([root_vlist,               # Root
+                       # Negative kerning to put root over tick
+                       Kern(-check.width * 0.5),
+                       check,                    # Check
+                       rightside])               # Body
+        return [hlist]
+
+    def overline(self, toks: ParseResults) -> T.Any:
+        body = toks["body"]
+
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+
+        height = body.height - body.shift_amount + thickness * 3.0
+        depth = body.depth + body.shift_amount
+
+        # Place overline above body
+        rightside = Vlist([Hrule(state), Glue('fill'), Hlist([body])])
+
+        # Stretch the glue between the hrule and the body
+        rightside.vpack(height + (state.fontsize * state.dpi) / (100.0 * 12.0),
+                        'exactly', depth)
+
+        hlist = Hlist([rightside])
+        return [hlist]
+
+    def _auto_sized_delimiter(self, front: str,
+                              middle: list[Box | Char | str],
+                              back: str) -> T.Any:
+        state = self.get_state()
+        if len(middle):
+            height = max([x.height for x in middle if not isinstance(x, str)])
+            depth = max([x.depth for x in middle if not isinstance(x, str)])
+            factor = None
+            for idx, el in enumerate(middle):
+                if el == r'\middle':
+                    c = T.cast(str, middle[idx + 1])  # Should be one of p.delims.
+                    if c != '.':
+                        middle[idx + 1] = AutoHeightChar(
+                                c, height, depth, state, factor=factor)
+                    else:
+                        middle.remove(c)
+                    del middle[idx]
+            # There should only be \middle and its delimiter as str, which have
+            # just been removed.
+            middle_part = T.cast(list[Box | Char], middle)
+        else:
+            height = 0
+            depth = 0
+            factor = 1.0
+            middle_part = []
+
+        parts: list[Node] = []
+        # \left. and \right. aren't supposed to produce any symbols
+        if front != '.':
+            parts.append(
+                AutoHeightChar(front, height, depth, state, factor=factor))
+        parts.extend(middle_part)
+        if back != '.':
+            parts.append(
+                AutoHeightChar(back, height, depth, state, factor=factor))
+        hlist = Hlist(parts)
+        return hlist
+
+    def auto_delim(self, toks: ParseResults) -> T.Any:
+        return self._auto_sized_delimiter(
+            toks["left"],
+            # if "mid" in toks ... can be removed when requiring pyparsing 3.
+            toks["mid"].asList() if "mid" in toks else [],
+            toks["right"])
+
+    def boldsymbol(self, toks: ParseResults) -> T.Any:
+        self.push_state()
+        state = self.get_state()
+        hlist: list[Node] = []
+        name = toks["value"]
+        for c in name:
+            if isinstance(c, Hlist):
+                k = c.children[1]
+                if isinstance(k, Char):
+                    k.font = "bf"
+                    k._update_metrics()
+                hlist.append(c)
+            elif isinstance(c, Char):
+                c.font = "bf"
+                if (c.c in self._latin_alphabets or
+                   c.c[1:] in self._small_greek):
+                    c.font = "bfit"
+                    c._update_metrics()
+                c._update_metrics()
+                hlist.append(c)
+            else:
+                hlist.append(c)
+        self.pop_state()
+
+        return Hlist(hlist)
+
+    def substack(self, toks: ParseResults) -> T.Any:
+        parts = toks["parts"]
+        state = self.get_state()
+        thickness = state.get_current_underline_thickness()
+
+        hlist = [Hlist(k) for k in parts[0]]
+        max_width = max(map(lambda c: c.width, hlist))
+
+        vlist = []
+        for sub in hlist:
+            cp = HCentered([sub])
+            cp.hpack(max_width, 'exactly')
+            vlist.append(cp)
+
+        stack = [val
+                 for pair in zip(vlist, [Vbox(0, thickness * 2)] * len(vlist))
+                 for val in pair]
+        del stack[-1]
+        vlt = Vlist(stack)
+        result = [Hlist([vlt])]
+        return result
diff --git a/lib/python3.12/site-packages/matplotlib/_mathtext_data.py b/lib/python3.12/site-packages/matplotlib/_mathtext_data.py
new file mode 100644
index 0000000000000000000000000000000000000000..5819ee7430447f9ef5f6e760b65cdd5933ef9395
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_mathtext_data.py
@@ -0,0 +1,1742 @@
+"""
+font data tables for truetype and afm computer modern fonts
+"""
+
+from __future__ import annotations
+from typing import overload
+
+latex_to_bakoma = {
+    '\\__sqrt__'                 : ('cmex10', 0x70),
+    '\\bigcap'                   : ('cmex10', 0x5c),
+    '\\bigcup'                   : ('cmex10', 0x5b),
+    '\\bigodot'                  : ('cmex10', 0x4b),
+    '\\bigoplus'                 : ('cmex10', 0x4d),
+    '\\bigotimes'                : ('cmex10', 0x4f),
+    '\\biguplus'                 : ('cmex10', 0x5d),
+    '\\bigvee'                   : ('cmex10', 0x5f),
+    '\\bigwedge'                 : ('cmex10', 0x5e),
+    '\\coprod'                   : ('cmex10', 0x61),
+    '\\int'                      : ('cmex10', 0x5a),
+    '\\langle'                   : ('cmex10', 0xad),
+    '\\leftangle'                : ('cmex10', 0xad),
+    '\\leftbrace'                : ('cmex10', 0xa9),
+    '\\oint'                     : ('cmex10', 0x49),
+    '\\prod'                     : ('cmex10', 0x59),
+    '\\rangle'                   : ('cmex10', 0xae),
+    '\\rightangle'               : ('cmex10', 0xae),
+    '\\rightbrace'               : ('cmex10', 0xaa),
+    '\\sum'                      : ('cmex10', 0x58),
+    '\\widehat'                  : ('cmex10', 0x62),
+    '\\widetilde'                : ('cmex10', 0x65),
+    '\\{'                        : ('cmex10', 0xa9),
+    '\\}'                        : ('cmex10', 0xaa),
+    '{'                          : ('cmex10', 0xa9),
+    '}'                          : ('cmex10', 0xaa),
+
+    ','                          : ('cmmi10', 0x3b),
+    '.'                          : ('cmmi10', 0x3a),
+    '/'                          : ('cmmi10', 0x3d),
+    '<'                          : ('cmmi10', 0x3c),
+    '>'                          : ('cmmi10', 0x3e),
+    '\\alpha'                    : ('cmmi10', 0xae),
+    '\\beta'                     : ('cmmi10', 0xaf),
+    '\\chi'                      : ('cmmi10', 0xc2),
+    '\\combiningrightarrowabove' : ('cmmi10', 0x7e),
+    '\\delta'                    : ('cmmi10', 0xb1),
+    '\\ell'                      : ('cmmi10', 0x60),
+    '\\epsilon'                  : ('cmmi10', 0xb2),
+    '\\eta'                      : ('cmmi10', 0xb4),
+    '\\flat'                     : ('cmmi10', 0x5b),
+    '\\frown'                    : ('cmmi10', 0x5f),
+    '\\gamma'                    : ('cmmi10', 0xb0),
+    '\\imath'                    : ('cmmi10', 0x7b),
+    '\\iota'                     : ('cmmi10', 0xb6),
+    '\\jmath'                    : ('cmmi10', 0x7c),
+    '\\kappa'                    : ('cmmi10', 0x2219),
+    '\\lambda'                   : ('cmmi10', 0xb8),
+    '\\leftharpoondown'          : ('cmmi10', 0x29),
+    '\\leftharpoonup'            : ('cmmi10', 0x28),
+    '\\mu'                       : ('cmmi10', 0xb9),
+    '\\natural'                  : ('cmmi10', 0x5c),
+    '\\nu'                       : ('cmmi10', 0xba),
+    '\\omega'                    : ('cmmi10', 0x21),
+    '\\phi'                      : ('cmmi10', 0xc1),
+    '\\pi'                       : ('cmmi10', 0xbc),
+    '\\psi'                      : ('cmmi10', 0xc3),
+    '\\rho'                      : ('cmmi10', 0xbd),
+    '\\rightharpoondown'         : ('cmmi10', 0x2b),
+    '\\rightharpoonup'           : ('cmmi10', 0x2a),
+    '\\sharp'                    : ('cmmi10', 0x5d),
+    '\\sigma'                    : ('cmmi10', 0xbe),
+    '\\smile'                    : ('cmmi10', 0x5e),
+    '\\tau'                      : ('cmmi10', 0xbf),
+    '\\theta'                    : ('cmmi10', 0xb5),
+    '\\triangleleft'             : ('cmmi10', 0x2f),
+    '\\triangleright'            : ('cmmi10', 0x2e),
+    '\\upsilon'                  : ('cmmi10', 0xc0),
+    '\\varepsilon'               : ('cmmi10', 0x22),
+    '\\varphi'                   : ('cmmi10', 0x27),
+    '\\varrho'                   : ('cmmi10', 0x25),
+    '\\varsigma'                 : ('cmmi10', 0x26),
+    '\\vartheta'                 : ('cmmi10', 0x23),
+    '\\wp'                       : ('cmmi10', 0x7d),
+    '\\xi'                       : ('cmmi10', 0xbb),
+    '\\zeta'                     : ('cmmi10', 0xb3),
+
+    '!'                          : ('cmr10', 0x21),
+    '%'                          : ('cmr10', 0x25),
+    '&'                          : ('cmr10', 0x26),
+    '('                          : ('cmr10', 0x28),
+    ')'                          : ('cmr10', 0x29),
+    '+'                          : ('cmr10', 0x2b),
+    '0'                          : ('cmr10', 0x30),
+    '1'                          : ('cmr10', 0x31),
+    '2'                          : ('cmr10', 0x32),
+    '3'                          : ('cmr10', 0x33),
+    '4'                          : ('cmr10', 0x34),
+    '5'                          : ('cmr10', 0x35),
+    '6'                          : ('cmr10', 0x36),
+    '7'                          : ('cmr10', 0x37),
+    '8'                          : ('cmr10', 0x38),
+    '9'                          : ('cmr10', 0x39),
+    ':'                          : ('cmr10', 0x3a),
+    ';'                          : ('cmr10', 0x3b),
+    '='                          : ('cmr10', 0x3d),
+    '?'                          : ('cmr10', 0x3f),
+    '@'                          : ('cmr10', 0x40),
+    '['                          : ('cmr10', 0x5b),
+    '\\#'                        : ('cmr10', 0x23),
+    '\\$'                        : ('cmr10', 0x24),
+    '\\%'                        : ('cmr10', 0x25),
+    '\\Delta'                    : ('cmr10', 0xa2),
+    '\\Gamma'                    : ('cmr10', 0xa1),
+    '\\Lambda'                   : ('cmr10', 0xa4),
+    '\\Omega'                    : ('cmr10', 0xad),
+    '\\Phi'                      : ('cmr10', 0xa9),
+    '\\Pi'                       : ('cmr10', 0xa6),
+    '\\Psi'                      : ('cmr10', 0xaa),
+    '\\Sigma'                    : ('cmr10', 0xa7),
+    '\\Theta'                    : ('cmr10', 0xa3),
+    '\\Upsilon'                  : ('cmr10', 0xa8),
+    '\\Xi'                       : ('cmr10', 0xa5),
+    '\\circumflexaccent'         : ('cmr10', 0x5e),
+    '\\combiningacuteaccent'     : ('cmr10', 0xb6),
+    '\\combiningbreve'           : ('cmr10', 0xb8),
+    '\\combiningdiaeresis'       : ('cmr10', 0xc4),
+    '\\combiningdotabove'        : ('cmr10', 0x5f),
+    '\\combininggraveaccent'     : ('cmr10', 0xb5),
+    '\\combiningoverline'        : ('cmr10', 0xb9),
+    '\\combiningtilde'           : ('cmr10', 0x7e),
+    '\\leftbracket'              : ('cmr10', 0x5b),
+    '\\leftparen'                : ('cmr10', 0x28),
+    '\\rightbracket'             : ('cmr10', 0x5d),
+    '\\rightparen'               : ('cmr10', 0x29),
+    '\\widebar'                  : ('cmr10', 0xb9),
+    ']'                          : ('cmr10', 0x5d),
+
+    '*'                          : ('cmsy10', 0xa4),
+    '\N{MINUS SIGN}'             : ('cmsy10', 0xa1),
+    '\\Downarrow'                : ('cmsy10', 0x2b),
+    '\\Im'                       : ('cmsy10', 0x3d),
+    '\\Leftarrow'                : ('cmsy10', 0x28),
+    '\\Leftrightarrow'           : ('cmsy10', 0x2c),
+    '\\P'                        : ('cmsy10', 0x7b),
+    '\\Re'                       : ('cmsy10', 0x3c),
+    '\\Rightarrow'               : ('cmsy10', 0x29),
+    '\\S'                        : ('cmsy10', 0x78),
+    '\\Uparrow'                  : ('cmsy10', 0x2a),
+    '\\Updownarrow'              : ('cmsy10', 0x6d),
+    '\\Vert'                     : ('cmsy10', 0x6b),
+    '\\aleph'                    : ('cmsy10', 0x40),
+    '\\approx'                   : ('cmsy10', 0xbc),
+    '\\ast'                      : ('cmsy10', 0xa4),
+    '\\asymp'                    : ('cmsy10', 0xb3),
+    '\\backslash'                : ('cmsy10', 0x6e),
+    '\\bigcirc'                  : ('cmsy10', 0xb0),
+    '\\bigtriangledown'          : ('cmsy10', 0x35),
+    '\\bigtriangleup'            : ('cmsy10', 0x34),
+    '\\bot'                      : ('cmsy10', 0x3f),
+    '\\bullet'                   : ('cmsy10', 0xb2),
+    '\\cap'                      : ('cmsy10', 0x5c),
+    '\\cdot'                     : ('cmsy10', 0xa2),
+    '\\circ'                     : ('cmsy10', 0xb1),
+    '\\clubsuit'                 : ('cmsy10', 0x7c),
+    '\\cup'                      : ('cmsy10', 0x5b),
+    '\\dag'                      : ('cmsy10', 0x79),
+    '\\dashv'                    : ('cmsy10', 0x61),
+    '\\ddag'                     : ('cmsy10', 0x7a),
+    '\\diamond'                  : ('cmsy10', 0xa6),
+    '\\diamondsuit'              : ('cmsy10', 0x7d),
+    '\\div'                      : ('cmsy10', 0xa5),
+    '\\downarrow'                : ('cmsy10', 0x23),
+    '\\emptyset'                 : ('cmsy10', 0x3b),
+    '\\equiv'                    : ('cmsy10', 0xb4),
+    '\\exists'                   : ('cmsy10', 0x39),
+    '\\forall'                   : ('cmsy10', 0x38),
+    '\\geq'                      : ('cmsy10', 0xb8),
+    '\\gg'                       : ('cmsy10', 0xc0),
+    '\\heartsuit'                : ('cmsy10', 0x7e),
+    '\\in'                       : ('cmsy10', 0x32),
+    '\\infty'                    : ('cmsy10', 0x31),
+    '\\lbrace'                   : ('cmsy10', 0x66),
+    '\\lceil'                    : ('cmsy10', 0x64),
+    '\\leftarrow'                : ('cmsy10', 0xc3),
+    '\\leftrightarrow'           : ('cmsy10', 0x24),
+    '\\leq'                      : ('cmsy10', 0x2219),
+    '\\lfloor'                   : ('cmsy10', 0x62),
+    '\\ll'                       : ('cmsy10', 0xbf),
+    '\\mid'                      : ('cmsy10', 0x6a),
+    '\\mp'                       : ('cmsy10', 0xa8),
+    '\\nabla'                    : ('cmsy10', 0x72),
+    '\\nearrow'                  : ('cmsy10', 0x25),
+    '\\neg'                      : ('cmsy10', 0x3a),
+    '\\ni'                       : ('cmsy10', 0x33),
+    '\\nwarrow'                  : ('cmsy10', 0x2d),
+    '\\odot'                     : ('cmsy10', 0xaf),
+    '\\ominus'                   : ('cmsy10', 0xaa),
+    '\\oplus'                    : ('cmsy10', 0xa9),
+    '\\oslash'                   : ('cmsy10', 0xae),
+    '\\otimes'                   : ('cmsy10', 0xad),
+    '\\pm'                       : ('cmsy10', 0xa7),
+    '\\prec'                     : ('cmsy10', 0xc1),
+    '\\preceq'                   : ('cmsy10', 0xb9),
+    '\\prime'                    : ('cmsy10', 0x30),
+    '\\propto'                   : ('cmsy10', 0x2f),
+    '\\rbrace'                   : ('cmsy10', 0x67),
+    '\\rceil'                    : ('cmsy10', 0x65),
+    '\\rfloor'                   : ('cmsy10', 0x63),
+    '\\rightarrow'               : ('cmsy10', 0x21),
+    '\\searrow'                  : ('cmsy10', 0x26),
+    '\\sim'                      : ('cmsy10', 0xbb),
+    '\\simeq'                    : ('cmsy10', 0x27),
+    '\\slash'                    : ('cmsy10', 0x36),
+    '\\spadesuit'                : ('cmsy10', 0xc4),
+    '\\sqcap'                    : ('cmsy10', 0x75),
+    '\\sqcup'                    : ('cmsy10', 0x74),
+    '\\sqsubseteq'               : ('cmsy10', 0x76),
+    '\\sqsupseteq'               : ('cmsy10', 0x77),
+    '\\subset'                   : ('cmsy10', 0xbd),
+    '\\subseteq'                 : ('cmsy10', 0xb5),
+    '\\succ'                     : ('cmsy10', 0xc2),
+    '\\succeq'                   : ('cmsy10', 0xba),
+    '\\supset'                   : ('cmsy10', 0xbe),
+    '\\supseteq'                 : ('cmsy10', 0xb6),
+    '\\swarrow'                  : ('cmsy10', 0x2e),
+    '\\times'                    : ('cmsy10', 0xa3),
+    '\\to'                       : ('cmsy10', 0x21),
+    '\\top'                      : ('cmsy10', 0x3e),
+    '\\uparrow'                  : ('cmsy10', 0x22),
+    '\\updownarrow'              : ('cmsy10', 0x6c),
+    '\\uplus'                    : ('cmsy10', 0x5d),
+    '\\vdash'                    : ('cmsy10', 0x60),
+    '\\vee'                      : ('cmsy10', 0x5f),
+    '\\vert'                     : ('cmsy10', 0x6a),
+    '\\wedge'                    : ('cmsy10', 0x5e),
+    '\\wr'                       : ('cmsy10', 0x6f),
+    '\\|'                        : ('cmsy10', 0x6b),
+    '|'                          : ('cmsy10', 0x6a),
+
+    '\\_'                        : ('cmtt10', 0x5f)
+}
+
+# Automatically generated.
+
+type12uni = {
+    'aring'          : 229,
+    'quotedblright'  : 8221,
+    'V'              : 86,
+    'dollar'         : 36,
+    'four'           : 52,
+    'Yacute'         : 221,
+    'P'              : 80,
+    'underscore'     : 95,
+    'p'              : 112,
+    'Otilde'         : 213,
+    'perthousand'    : 8240,
+    'zero'           : 48,
+    'dotlessi'       : 305,
+    'Scaron'         : 352,
+    'zcaron'         : 382,
+    'egrave'         : 232,
+    'section'        : 167,
+    'Icircumflex'    : 206,
+    'ntilde'         : 241,
+    'ampersand'      : 38,
+    'dotaccent'      : 729,
+    'degree'         : 176,
+    'K'              : 75,
+    'acircumflex'    : 226,
+    'Aring'          : 197,
+    'k'              : 107,
+    'smalltilde'     : 732,
+    'Agrave'         : 192,
+    'divide'         : 247,
+    'ocircumflex'    : 244,
+    'asciitilde'     : 126,
+    'two'            : 50,
+    'E'              : 69,
+    'scaron'         : 353,
+    'F'              : 70,
+    'bracketleft'    : 91,
+    'asciicircum'    : 94,
+    'f'              : 102,
+    'ordmasculine'   : 186,
+    'mu'             : 181,
+    'paragraph'      : 182,
+    'nine'           : 57,
+    'v'              : 118,
+    'guilsinglleft'  : 8249,
+    'backslash'      : 92,
+    'six'            : 54,
+    'A'              : 65,
+    'icircumflex'    : 238,
+    'a'              : 97,
+    'ogonek'         : 731,
+    'q'              : 113,
+    'oacute'         : 243,
+    'ograve'         : 242,
+    'edieresis'      : 235,
+    'comma'          : 44,
+    'otilde'         : 245,
+    'guillemotright' : 187,
+    'ecircumflex'    : 234,
+    'greater'        : 62,
+    'uacute'         : 250,
+    'L'              : 76,
+    'bullet'         : 8226,
+    'cedilla'        : 184,
+    'ydieresis'      : 255,
+    'l'              : 108,
+    'logicalnot'     : 172,
+    'exclamdown'     : 161,
+    'endash'         : 8211,
+    'agrave'         : 224,
+    'Adieresis'      : 196,
+    'germandbls'     : 223,
+    'Odieresis'      : 214,
+    'space'          : 32,
+    'quoteright'     : 8217,
+    'ucircumflex'    : 251,
+    'G'              : 71,
+    'quoteleft'      : 8216,
+    'W'              : 87,
+    'Q'              : 81,
+    'g'              : 103,
+    'w'              : 119,
+    'question'       : 63,
+    'one'            : 49,
+    'ring'           : 730,
+    'figuredash'     : 8210,
+    'B'              : 66,
+    'iacute'         : 237,
+    'Ydieresis'      : 376,
+    'R'              : 82,
+    'b'              : 98,
+    'r'              : 114,
+    'Ccedilla'       : 199,
+    'minus'          : 8722,
+    'Lslash'         : 321,
+    'Uacute'         : 218,
+    'yacute'         : 253,
+    'Ucircumflex'    : 219,
+    'quotedbl'       : 34,
+    'onehalf'        : 189,
+    'Thorn'          : 222,
+    'M'              : 77,
+    'eight'          : 56,
+    'multiply'       : 215,
+    'grave'          : 96,
+    'Ocircumflex'    : 212,
+    'm'              : 109,
+    'Ugrave'         : 217,
+    'guilsinglright' : 8250,
+    'Ntilde'         : 209,
+    'questiondown'   : 191,
+    'Atilde'         : 195,
+    'ccedilla'       : 231,
+    'Z'              : 90,
+    'copyright'      : 169,
+    'yen'            : 165,
+    'Eacute'         : 201,
+    'H'              : 72,
+    'X'              : 88,
+    'Idieresis'      : 207,
+    'bar'            : 124,
+    'h'              : 104,
+    'x'              : 120,
+    'udieresis'      : 252,
+    'ordfeminine'    : 170,
+    'braceleft'      : 123,
+    'macron'         : 175,
+    'atilde'         : 227,
+    'Acircumflex'    : 194,
+    'Oslash'         : 216,
+    'C'              : 67,
+    'quotedblleft'   : 8220,
+    'S'              : 83,
+    'exclam'         : 33,
+    'Zcaron'         : 381,
+    'equal'          : 61,
+    's'              : 115,
+    'eth'            : 240,
+    'Egrave'         : 200,
+    'hyphen'         : 45,
+    'period'         : 46,
+    'igrave'         : 236,
+    'colon'          : 58,
+    'Ecircumflex'    : 202,
+    'trademark'      : 8482,
+    'Aacute'         : 193,
+    'cent'           : 162,
+    'lslash'         : 322,
+    'c'              : 99,
+    'N'              : 78,
+    'breve'          : 728,
+    'Oacute'         : 211,
+    'guillemotleft'  : 171,
+    'n'              : 110,
+    'idieresis'      : 239,
+    'braceright'     : 125,
+    'seven'          : 55,
+    'brokenbar'      : 166,
+    'ugrave'         : 249,
+    'periodcentered' : 183,
+    'sterling'       : 163,
+    'I'              : 73,
+    'Y'              : 89,
+    'Eth'            : 208,
+    'emdash'         : 8212,
+    'i'              : 105,
+    'daggerdbl'      : 8225,
+    'y'              : 121,
+    'plusminus'      : 177,
+    'less'           : 60,
+    'Udieresis'      : 220,
+    'D'              : 68,
+    'five'           : 53,
+    'T'              : 84,
+    'oslash'         : 248,
+    'acute'          : 180,
+    'd'              : 100,
+    'OE'             : 338,
+    'Igrave'         : 204,
+    't'              : 116,
+    'parenright'     : 41,
+    'adieresis'      : 228,
+    'quotesingle'    : 39,
+    'twodotenleader' : 8229,
+    'slash'          : 47,
+    'ellipsis'       : 8230,
+    'numbersign'     : 35,
+    'odieresis'      : 246,
+    'O'              : 79,
+    'oe'             : 339,
+    'o'              : 111,
+    'Edieresis'      : 203,
+    'plus'           : 43,
+    'dagger'         : 8224,
+    'three'          : 51,
+    'hungarumlaut'   : 733,
+    'parenleft'      : 40,
+    'fraction'       : 8260,
+    'registered'     : 174,
+    'J'              : 74,
+    'dieresis'       : 168,
+    'Ograve'         : 210,
+    'j'              : 106,
+    'z'              : 122,
+    'ae'             : 230,
+    'semicolon'      : 59,
+    'at'             : 64,
+    'Iacute'         : 205,
+    'percent'        : 37,
+    'bracketright'   : 93,
+    'AE'             : 198,
+    'asterisk'       : 42,
+    'aacute'         : 225,
+    'U'              : 85,
+    'eacute'         : 233,
+    'e'              : 101,
+    'thorn'          : 254,
+    'u'              : 117,
+}
+
+uni2type1 = {v: k for k, v in type12uni.items()}
+
+#  The script below is to sort and format the tex2uni dict
+
+## For decimal values: int(hex(v), 16)
+#  newtex = {k: hex(v) for k, v in tex2uni.items()}
+#  sd = dict(sorted(newtex.items(), key=lambda item: item[0]))
+#
+## For formatting the sorted dictionary with proper spacing
+## the value '24' comes from finding the longest string in
+## the newtex keys with len(max(newtex, key=len))
+#  for key in sd:
+#      print("{0:24} : {1: <s},".format("'" + key + "'", sd[key]))
+
+tex2uni = {
+    '#'                      : 0x23,
+    '$'                      : 0x24,
+    '%'                      : 0x25,
+    'AA'                     : 0xc5,
+    'AE'                     : 0xc6,
+    'BbbC'                   : 0x2102,
+    'BbbN'                   : 0x2115,
+    'BbbP'                   : 0x2119,
+    'BbbQ'                   : 0x211a,
+    'BbbR'                   : 0x211d,
+    'BbbZ'                   : 0x2124,
+    'Bumpeq'                 : 0x224e,
+    'Cap'                    : 0x22d2,
+    'Colon'                  : 0x2237,
+    'Cup'                    : 0x22d3,
+    'DH'                     : 0xd0,
+    'Delta'                  : 0x394,
+    'Doteq'                  : 0x2251,
+    'Downarrow'              : 0x21d3,
+    'Equiv'                  : 0x2263,
+    'Finv'                   : 0x2132,
+    'Game'                   : 0x2141,
+    'Gamma'                  : 0x393,
+    'H'                      : 0x30b,
+    'Im'                     : 0x2111,
+    'Join'                   : 0x2a1d,
+    'L'                      : 0x141,
+    'Lambda'                 : 0x39b,
+    'Ldsh'                   : 0x21b2,
+    'Leftarrow'              : 0x21d0,
+    'Leftrightarrow'         : 0x21d4,
+    'Lleftarrow'             : 0x21da,
+    'Longleftarrow'          : 0x27f8,
+    'Longleftrightarrow'     : 0x27fa,
+    'Longrightarrow'         : 0x27f9,
+    'Lsh'                    : 0x21b0,
+    'Nearrow'                : 0x21d7,
+    'Nwarrow'                : 0x21d6,
+    'O'                      : 0xd8,
+    'OE'                     : 0x152,
+    'Omega'                  : 0x3a9,
+    'P'                      : 0xb6,
+    'Phi'                    : 0x3a6,
+    'Pi'                     : 0x3a0,
+    'Psi'                    : 0x3a8,
+    'QED'                    : 0x220e,
+    'Rdsh'                   : 0x21b3,
+    'Re'                     : 0x211c,
+    'Rightarrow'             : 0x21d2,
+    'Rrightarrow'            : 0x21db,
+    'Rsh'                    : 0x21b1,
+    'S'                      : 0xa7,
+    'Searrow'                : 0x21d8,
+    'Sigma'                  : 0x3a3,
+    'Subset'                 : 0x22d0,
+    'Supset'                 : 0x22d1,
+    'Swarrow'                : 0x21d9,
+    'Theta'                  : 0x398,
+    'Thorn'                  : 0xde,
+    'Uparrow'                : 0x21d1,
+    'Updownarrow'            : 0x21d5,
+    'Upsilon'                : 0x3a5,
+    'Vdash'                  : 0x22a9,
+    'Vert'                   : 0x2016,
+    'Vvdash'                 : 0x22aa,
+    'Xi'                     : 0x39e,
+    '_'                      : 0x5f,
+    '__sqrt__'               : 0x221a,
+    'aa'                     : 0xe5,
+    'ac'                     : 0x223e,
+    'acute'                  : 0x301,
+    'acwopencirclearrow'     : 0x21ba,
+    'adots'                  : 0x22f0,
+    'ae'                     : 0xe6,
+    'aleph'                  : 0x2135,
+    'alpha'                  : 0x3b1,
+    'amalg'                  : 0x2a3f,
+    'angle'                  : 0x2220,
+    'approx'                 : 0x2248,
+    'approxeq'               : 0x224a,
+    'approxident'            : 0x224b,
+    'arceq'                  : 0x2258,
+    'ast'                    : 0x2217,
+    'asterisk'               : 0x2a,
+    'asymp'                  : 0x224d,
+    'backcong'               : 0x224c,
+    'backepsilon'            : 0x3f6,
+    'backprime'              : 0x2035,
+    'backsim'                : 0x223d,
+    'backsimeq'              : 0x22cd,
+    'backslash'              : 0x5c,
+    'bagmember'              : 0x22ff,
+    'bar'                    : 0x304,
+    'barleftarrow'           : 0x21e4,
+    'barvee'                 : 0x22bd,
+    'barwedge'               : 0x22bc,
+    'because'                : 0x2235,
+    'beta'                   : 0x3b2,
+    'beth'                   : 0x2136,
+    'between'                : 0x226c,
+    'bigcap'                 : 0x22c2,
+    'bigcirc'                : 0x25cb,
+    'bigcup'                 : 0x22c3,
+    'bigodot'                : 0x2a00,
+    'bigoplus'               : 0x2a01,
+    'bigotimes'              : 0x2a02,
+    'bigsqcup'               : 0x2a06,
+    'bigstar'                : 0x2605,
+    'bigtriangledown'        : 0x25bd,
+    'bigtriangleup'          : 0x25b3,
+    'biguplus'               : 0x2a04,
+    'bigvee'                 : 0x22c1,
+    'bigwedge'               : 0x22c0,
+    'blacksquare'            : 0x25a0,
+    'blacktriangle'          : 0x25b4,
+    'blacktriangledown'      : 0x25be,
+    'blacktriangleleft'      : 0x25c0,
+    'blacktriangleright'     : 0x25b6,
+    'bot'                    : 0x22a5,
+    'bowtie'                 : 0x22c8,
+    'boxbar'                 : 0x25eb,
+    'boxdot'                 : 0x22a1,
+    'boxminus'               : 0x229f,
+    'boxplus'                : 0x229e,
+    'boxtimes'               : 0x22a0,
+    'breve'                  : 0x306,
+    'bullet'                 : 0x2219,
+    'bumpeq'                 : 0x224f,
+    'c'                      : 0x327,
+    'candra'                 : 0x310,
+    'cap'                    : 0x2229,
+    'carriagereturn'         : 0x21b5,
+    'cdot'                   : 0x22c5,
+    'cdotp'                  : 0xb7,
+    'cdots'                  : 0x22ef,
+    'cent'                   : 0xa2,
+    'check'                  : 0x30c,
+    'checkmark'              : 0x2713,
+    'chi'                    : 0x3c7,
+    'circ'                   : 0x2218,
+    'circeq'                 : 0x2257,
+    'circlearrowleft'        : 0x21ba,
+    'circlearrowright'       : 0x21bb,
+    'circledR'               : 0xae,
+    'circledS'               : 0x24c8,
+    'circledast'             : 0x229b,
+    'circledcirc'            : 0x229a,
+    'circleddash'            : 0x229d,
+    'circumflexaccent'       : 0x302,
+    'clubsuit'               : 0x2663,
+    'clubsuitopen'           : 0x2667,
+    'colon'                  : 0x3a,
+    'coloneq'                : 0x2254,
+    'combiningacuteaccent'   : 0x301,
+    'combiningbreve'         : 0x306,
+    'combiningdiaeresis'     : 0x308,
+    'combiningdotabove'      : 0x307,
+    'combiningfourdotsabove' : 0x20dc,
+    'combininggraveaccent'   : 0x300,
+    'combiningoverline'      : 0x304,
+    'combiningrightarrowabove' : 0x20d7,
+    'combiningthreedotsabove' : 0x20db,
+    'combiningtilde'         : 0x303,
+    'complement'             : 0x2201,
+    'cong'                   : 0x2245,
+    'coprod'                 : 0x2210,
+    'copyright'              : 0xa9,
+    'cup'                    : 0x222a,
+    'cupdot'                 : 0x228d,
+    'cupleftarrow'           : 0x228c,
+    'curlyeqprec'            : 0x22de,
+    'curlyeqsucc'            : 0x22df,
+    'curlyvee'               : 0x22ce,
+    'curlywedge'             : 0x22cf,
+    'curvearrowleft'         : 0x21b6,
+    'curvearrowright'        : 0x21b7,
+    'cwopencirclearrow'      : 0x21bb,
+    'd'                      : 0x323,
+    'dag'                    : 0x2020,
+    'dagger'                 : 0x2020,
+    'daleth'                 : 0x2138,
+    'danger'                 : 0x2621,
+    'dashleftarrow'          : 0x290e,
+    'dashrightarrow'         : 0x290f,
+    'dashv'                  : 0x22a3,
+    'ddag'                   : 0x2021,
+    'ddagger'                : 0x2021,
+    'ddddot'                 : 0x20dc,
+    'dddot'                  : 0x20db,
+    'ddot'                   : 0x308,
+    'ddots'                  : 0x22f1,
+    'degree'                 : 0xb0,
+    'delta'                  : 0x3b4,
+    'dh'                     : 0xf0,
+    'diamond'                : 0x22c4,
+    'diamondsuit'            : 0x2662,
+    'digamma'                : 0x3dd,
+    'disin'                  : 0x22f2,
+    'div'                    : 0xf7,
+    'divideontimes'          : 0x22c7,
+    'dot'                    : 0x307,
+    'doteq'                  : 0x2250,
+    'doteqdot'               : 0x2251,
+    'dotminus'               : 0x2238,
+    'dotplus'                : 0x2214,
+    'dots'                   : 0x2026,
+    'dotsminusdots'          : 0x223a,
+    'doublebarwedge'         : 0x2306,
+    'downarrow'              : 0x2193,
+    'downdownarrows'         : 0x21ca,
+    'downharpoonleft'        : 0x21c3,
+    'downharpoonright'       : 0x21c2,
+    'downzigzagarrow'        : 0x21af,
+    'ell'                    : 0x2113,
+    'emdash'                 : 0x2014,
+    'emptyset'               : 0x2205,
+    'endash'                 : 0x2013,
+    'epsilon'                : 0x3b5,
+    'eqcirc'                 : 0x2256,
+    'eqcolon'                : 0x2255,
+    'eqdef'                  : 0x225d,
+    'eqgtr'                  : 0x22dd,
+    'eqless'                 : 0x22dc,
+    'eqsim'                  : 0x2242,
+    'eqslantgtr'             : 0x2a96,
+    'eqslantless'            : 0x2a95,
+    'equal'                  : 0x3d,
+    'equalparallel'          : 0x22d5,
+    'equiv'                  : 0x2261,
+    'eta'                    : 0x3b7,
+    'eth'                    : 0xf0,
+    'exists'                 : 0x2203,
+    'fallingdotseq'          : 0x2252,
+    'flat'                   : 0x266d,
+    'forall'                 : 0x2200,
+    'frakC'                  : 0x212d,
+    'frakZ'                  : 0x2128,
+    'frown'                  : 0x2322,
+    'gamma'                  : 0x3b3,
+    'geq'                    : 0x2265,
+    'geqq'                   : 0x2267,
+    'geqslant'               : 0x2a7e,
+    'gg'                     : 0x226b,
+    'ggg'                    : 0x22d9,
+    'gimel'                  : 0x2137,
+    'gnapprox'               : 0x2a8a,
+    'gneqq'                  : 0x2269,
+    'gnsim'                  : 0x22e7,
+    'grave'                  : 0x300,
+    'greater'                : 0x3e,
+    'gtrapprox'              : 0x2a86,
+    'gtrdot'                 : 0x22d7,
+    'gtreqless'              : 0x22db,
+    'gtreqqless'             : 0x2a8c,
+    'gtrless'                : 0x2277,
+    'gtrsim'                 : 0x2273,
+    'guillemotleft'          : 0xab,
+    'guillemotright'         : 0xbb,
+    'guilsinglleft'          : 0x2039,
+    'guilsinglright'         : 0x203a,
+    'hat'                    : 0x302,
+    'hbar'                   : 0x127,
+    'heartsuit'              : 0x2661,
+    'hermitmatrix'           : 0x22b9,
+    'hookleftarrow'          : 0x21a9,
+    'hookrightarrow'         : 0x21aa,
+    'hslash'                 : 0x210f,
+    'i'                      : 0x131,
+    'iiiint'                 : 0x2a0c,
+    'iiint'                  : 0x222d,
+    'iint'                   : 0x222c,
+    'imageof'                : 0x22b7,
+    'imath'                  : 0x131,
+    'in'                     : 0x2208,
+    'increment'              : 0x2206,
+    'infty'                  : 0x221e,
+    'int'                    : 0x222b,
+    'intercal'               : 0x22ba,
+    'invnot'                 : 0x2310,
+    'iota'                   : 0x3b9,
+    'isinE'                  : 0x22f9,
+    'isindot'                : 0x22f5,
+    'isinobar'               : 0x22f7,
+    'isins'                  : 0x22f4,
+    'isinvb'                 : 0x22f8,
+    'jmath'                  : 0x237,
+    'k'                      : 0x328,
+    'kappa'                  : 0x3ba,
+    'kernelcontraction'      : 0x223b,
+    'l'                      : 0x142,
+    'lambda'                 : 0x3bb,
+    'lambdabar'              : 0x19b,
+    'langle'                 : 0x27e8,
+    'lasp'                   : 0x2bd,
+    'lbrace'                 : 0x7b,
+    'lbrack'                 : 0x5b,
+    'lceil'                  : 0x2308,
+    'ldots'                  : 0x2026,
+    'leadsto'                : 0x21dd,
+    'leftarrow'              : 0x2190,
+    'leftarrowtail'          : 0x21a2,
+    'leftbrace'              : 0x7b,
+    'leftharpoonaccent'      : 0x20d0,
+    'leftharpoondown'        : 0x21bd,
+    'leftharpoonup'          : 0x21bc,
+    'leftleftarrows'         : 0x21c7,
+    'leftparen'              : 0x28,
+    'leftrightarrow'         : 0x2194,
+    'leftrightarrows'        : 0x21c6,
+    'leftrightharpoons'      : 0x21cb,
+    'leftrightsquigarrow'    : 0x21ad,
+    'leftsquigarrow'         : 0x219c,
+    'leftthreetimes'         : 0x22cb,
+    'leq'                    : 0x2264,
+    'leqq'                   : 0x2266,
+    'leqslant'               : 0x2a7d,
+    'less'                   : 0x3c,
+    'lessapprox'             : 0x2a85,
+    'lessdot'                : 0x22d6,
+    'lesseqgtr'              : 0x22da,
+    'lesseqqgtr'             : 0x2a8b,
+    'lessgtr'                : 0x2276,
+    'lesssim'                : 0x2272,
+    'lfloor'                 : 0x230a,
+    'lgroup'                 : 0x27ee,
+    'lhd'                    : 0x25c1,
+    'll'                     : 0x226a,
+    'llcorner'               : 0x231e,
+    'lll'                    : 0x22d8,
+    'lnapprox'               : 0x2a89,
+    'lneqq'                  : 0x2268,
+    'lnsim'                  : 0x22e6,
+    'longleftarrow'          : 0x27f5,
+    'longleftrightarrow'     : 0x27f7,
+    'longmapsto'             : 0x27fc,
+    'longrightarrow'         : 0x27f6,
+    'looparrowleft'          : 0x21ab,
+    'looparrowright'         : 0x21ac,
+    'lq'                     : 0x2018,
+    'lrcorner'               : 0x231f,
+    'ltimes'                 : 0x22c9,
+    'macron'                 : 0xaf,
+    'maltese'                : 0x2720,
+    'mapsdown'               : 0x21a7,
+    'mapsfrom'               : 0x21a4,
+    'mapsto'                 : 0x21a6,
+    'mapsup'                 : 0x21a5,
+    'measeq'                 : 0x225e,
+    'measuredangle'          : 0x2221,
+    'measuredrightangle'     : 0x22be,
+    'merge'                  : 0x2a55,
+    'mho'                    : 0x2127,
+    'mid'                    : 0x2223,
+    'minus'                  : 0x2212,
+    'minuscolon'             : 0x2239,
+    'models'                 : 0x22a7,
+    'mp'                     : 0x2213,
+    'mu'                     : 0x3bc,
+    'multimap'               : 0x22b8,
+    'nLeftarrow'             : 0x21cd,
+    'nLeftrightarrow'        : 0x21ce,
+    'nRightarrow'            : 0x21cf,
+    'nVDash'                 : 0x22af,
+    'nVdash'                 : 0x22ae,
+    'nabla'                  : 0x2207,
+    'napprox'                : 0x2249,
+    'natural'                : 0x266e,
+    'ncong'                  : 0x2247,
+    'ne'                     : 0x2260,
+    'nearrow'                : 0x2197,
+    'neg'                    : 0xac,
+    'neq'                    : 0x2260,
+    'nequiv'                 : 0x2262,
+    'nexists'                : 0x2204,
+    'ngeq'                   : 0x2271,
+    'ngtr'                   : 0x226f,
+    'ngtrless'               : 0x2279,
+    'ngtrsim'                : 0x2275,
+    'ni'                     : 0x220b,
+    'niobar'                 : 0x22fe,
+    'nis'                    : 0x22fc,
+    'nisd'                   : 0x22fa,
+    'nleftarrow'             : 0x219a,
+    'nleftrightarrow'        : 0x21ae,
+    'nleq'                   : 0x2270,
+    'nless'                  : 0x226e,
+    'nlessgtr'               : 0x2278,
+    'nlesssim'               : 0x2274,
+    'nmid'                   : 0x2224,
+    'not'                    : 0x338,
+    'notin'                  : 0x2209,
+    'notsmallowns'           : 0x220c,
+    'nparallel'              : 0x2226,
+    'nprec'                  : 0x2280,
+    'npreccurlyeq'           : 0x22e0,
+    'nrightarrow'            : 0x219b,
+    'nsim'                   : 0x2241,
+    'nsimeq'                 : 0x2244,
+    'nsqsubseteq'            : 0x22e2,
+    'nsqsupseteq'            : 0x22e3,
+    'nsubset'                : 0x2284,
+    'nsubseteq'              : 0x2288,
+    'nsucc'                  : 0x2281,
+    'nsucccurlyeq'           : 0x22e1,
+    'nsupset'                : 0x2285,
+    'nsupseteq'              : 0x2289,
+    'ntriangleleft'          : 0x22ea,
+    'ntrianglelefteq'        : 0x22ec,
+    'ntriangleright'         : 0x22eb,
+    'ntrianglerighteq'       : 0x22ed,
+    'nu'                     : 0x3bd,
+    'nvDash'                 : 0x22ad,
+    'nvdash'                 : 0x22ac,
+    'nwarrow'                : 0x2196,
+    'o'                      : 0xf8,
+    'obar'                   : 0x233d,
+    'ocirc'                  : 0x30a,
+    'odot'                   : 0x2299,
+    'oe'                     : 0x153,
+    'oequal'                 : 0x229c,
+    'oiiint'                 : 0x2230,
+    'oiint'                  : 0x222f,
+    'oint'                   : 0x222e,
+    'omega'                  : 0x3c9,
+    'ominus'                 : 0x2296,
+    'oplus'                  : 0x2295,
+    'origof'                 : 0x22b6,
+    'oslash'                 : 0x2298,
+    'otimes'                 : 0x2297,
+    'overarc'                : 0x311,
+    'overleftarrow'          : 0x20d6,
+    'overleftrightarrow'     : 0x20e1,
+    'parallel'               : 0x2225,
+    'partial'                : 0x2202,
+    'perp'                   : 0x27c2,
+    'perthousand'            : 0x2030,
+    'phi'                    : 0x3d5,
+    'pi'                     : 0x3c0,
+    'pitchfork'              : 0x22d4,
+    'plus'                   : 0x2b,
+    'pm'                     : 0xb1,
+    'prec'                   : 0x227a,
+    'precapprox'             : 0x2ab7,
+    'preccurlyeq'            : 0x227c,
+    'preceq'                 : 0x227c,
+    'precnapprox'            : 0x2ab9,
+    'precnsim'               : 0x22e8,
+    'precsim'                : 0x227e,
+    'prime'                  : 0x2032,
+    'prod'                   : 0x220f,
+    'propto'                 : 0x221d,
+    'prurel'                 : 0x22b0,
+    'psi'                    : 0x3c8,
+    'quad'                   : 0x2003,
+    'questeq'                : 0x225f,
+    'rangle'                 : 0x27e9,
+    'rasp'                   : 0x2bc,
+    'ratio'                  : 0x2236,
+    'rbrace'                 : 0x7d,
+    'rbrack'                 : 0x5d,
+    'rceil'                  : 0x2309,
+    'rfloor'                 : 0x230b,
+    'rgroup'                 : 0x27ef,
+    'rhd'                    : 0x25b7,
+    'rho'                    : 0x3c1,
+    'rightModels'            : 0x22ab,
+    'rightangle'             : 0x221f,
+    'rightarrow'             : 0x2192,
+    'rightarrowbar'          : 0x21e5,
+    'rightarrowtail'         : 0x21a3,
+    'rightassert'            : 0x22a6,
+    'rightbrace'             : 0x7d,
+    'rightharpoonaccent'     : 0x20d1,
+    'rightharpoondown'       : 0x21c1,
+    'rightharpoonup'         : 0x21c0,
+    'rightleftarrows'        : 0x21c4,
+    'rightleftharpoons'      : 0x21cc,
+    'rightparen'             : 0x29,
+    'rightrightarrows'       : 0x21c9,
+    'rightsquigarrow'        : 0x219d,
+    'rightthreetimes'        : 0x22cc,
+    'rightzigzagarrow'       : 0x21dd,
+    'ring'                   : 0x2da,
+    'risingdotseq'           : 0x2253,
+    'rq'                     : 0x2019,
+    'rtimes'                 : 0x22ca,
+    'scrB'                   : 0x212c,
+    'scrE'                   : 0x2130,
+    'scrF'                   : 0x2131,
+    'scrH'                   : 0x210b,
+    'scrI'                   : 0x2110,
+    'scrL'                   : 0x2112,
+    'scrM'                   : 0x2133,
+    'scrR'                   : 0x211b,
+    'scre'                   : 0x212f,
+    'scrg'                   : 0x210a,
+    'scro'                   : 0x2134,
+    'scurel'                 : 0x22b1,
+    'searrow'                : 0x2198,
+    'setminus'               : 0x2216,
+    'sharp'                  : 0x266f,
+    'sigma'                  : 0x3c3,
+    'sim'                    : 0x223c,
+    'simeq'                  : 0x2243,
+    'simneqq'                : 0x2246,
+    'sinewave'               : 0x223f,
+    'slash'                  : 0x2215,
+    'smallin'                : 0x220a,
+    'smallintclockwise'      : 0x2231,
+    'smallointctrcclockwise' : 0x2233,
+    'smallowns'              : 0x220d,
+    'smallsetminus'          : 0x2216,
+    'smallvarointclockwise'  : 0x2232,
+    'smile'                  : 0x2323,
+    'solbar'                 : 0x233f,
+    'spadesuit'              : 0x2660,
+    'spadesuitopen'          : 0x2664,
+    'sphericalangle'         : 0x2222,
+    'sqcap'                  : 0x2293,
+    'sqcup'                  : 0x2294,
+    'sqsubset'               : 0x228f,
+    'sqsubseteq'             : 0x2291,
+    'sqsubsetneq'            : 0x22e4,
+    'sqsupset'               : 0x2290,
+    'sqsupseteq'             : 0x2292,
+    'sqsupsetneq'            : 0x22e5,
+    'ss'                     : 0xdf,
+    'star'                   : 0x22c6,
+    'stareq'                 : 0x225b,
+    'sterling'               : 0xa3,
+    'subset'                 : 0x2282,
+    'subseteq'               : 0x2286,
+    'subseteqq'              : 0x2ac5,
+    'subsetneq'              : 0x228a,
+    'subsetneqq'             : 0x2acb,
+    'succ'                   : 0x227b,
+    'succapprox'             : 0x2ab8,
+    'succcurlyeq'            : 0x227d,
+    'succeq'                 : 0x227d,
+    'succnapprox'            : 0x2aba,
+    'succnsim'               : 0x22e9,
+    'succsim'                : 0x227f,
+    'sum'                    : 0x2211,
+    'supset'                 : 0x2283,
+    'supseteq'               : 0x2287,
+    'supseteqq'              : 0x2ac6,
+    'supsetneq'              : 0x228b,
+    'supsetneqq'             : 0x2acc,
+    'swarrow'                : 0x2199,
+    't'                      : 0x361,
+    'tau'                    : 0x3c4,
+    'textasciiacute'         : 0xb4,
+    'textasciicircum'        : 0x5e,
+    'textasciigrave'         : 0x60,
+    'textasciitilde'         : 0x7e,
+    'textexclamdown'         : 0xa1,
+    'textquestiondown'       : 0xbf,
+    'textquotedblleft'       : 0x201c,
+    'textquotedblright'      : 0x201d,
+    'therefore'              : 0x2234,
+    'theta'                  : 0x3b8,
+    'thickspace'             : 0x2005,
+    'thorn'                  : 0xfe,
+    'tilde'                  : 0x303,
+    'times'                  : 0xd7,
+    'to'                     : 0x2192,
+    'top'                    : 0x22a4,
+    'triangle'               : 0x25b3,
+    'triangledown'           : 0x25bf,
+    'triangleeq'             : 0x225c,
+    'triangleleft'           : 0x25c1,
+    'trianglelefteq'         : 0x22b4,
+    'triangleq'              : 0x225c,
+    'triangleright'          : 0x25b7,
+    'trianglerighteq'        : 0x22b5,
+    'turnednot'              : 0x2319,
+    'twoheaddownarrow'       : 0x21a1,
+    'twoheadleftarrow'       : 0x219e,
+    'twoheadrightarrow'      : 0x21a0,
+    'twoheaduparrow'         : 0x219f,
+    'ulcorner'               : 0x231c,
+    'underbar'               : 0x331,
+    'unlhd'                  : 0x22b4,
+    'unrhd'                  : 0x22b5,
+    'uparrow'                : 0x2191,
+    'updownarrow'            : 0x2195,
+    'updownarrowbar'         : 0x21a8,
+    'updownarrows'           : 0x21c5,
+    'upharpoonleft'          : 0x21bf,
+    'upharpoonright'         : 0x21be,
+    'uplus'                  : 0x228e,
+    'upsilon'                : 0x3c5,
+    'upuparrows'             : 0x21c8,
+    'urcorner'               : 0x231d,
+    'vDash'                  : 0x22a8,
+    'varepsilon'             : 0x3b5,
+    'varisinobar'            : 0x22f6,
+    'varisins'               : 0x22f3,
+    'varkappa'               : 0x3f0,
+    'varlrtriangle'          : 0x22bf,
+    'varniobar'              : 0x22fd,
+    'varnis'                 : 0x22fb,
+    'varnothing'             : 0x2205,
+    'varphi'                 : 0x3c6,
+    'varpi'                  : 0x3d6,
+    'varpropto'              : 0x221d,
+    'varrho'                 : 0x3f1,
+    'varsigma'               : 0x3c2,
+    'vartheta'               : 0x3d1,
+    'vartriangle'            : 0x25b5,
+    'vartriangleleft'        : 0x22b2,
+    'vartriangleright'       : 0x22b3,
+    'vdash'                  : 0x22a2,
+    'vdots'                  : 0x22ee,
+    'vec'                    : 0x20d7,
+    'vee'                    : 0x2228,
+    'veebar'                 : 0x22bb,
+    'veeeq'                  : 0x225a,
+    'vert'                   : 0x7c,
+    'wedge'                  : 0x2227,
+    'wedgeq'                 : 0x2259,
+    'widebar'                : 0x305,
+    'widehat'                : 0x302,
+    'widetilde'              : 0x303,
+    'wp'                     : 0x2118,
+    'wr'                     : 0x2240,
+    'xi'                     : 0x3be,
+    'yen'                    : 0xa5,
+    'zeta'                   : 0x3b6,
+    '{'                      : 0x7b,
+    '|'                      : 0x2016,
+    '}'                      : 0x7d,
+}
+
+# Each element is a 4-tuple of the form:
+#   src_start, src_end, dst_font, dst_start
+
+_EntryTypeIn = tuple[str, str, str, str | int]
+_EntryTypeOut = tuple[int, int, str, int]
+
+_stix_virtual_fonts: dict[str, dict[str, list[_EntryTypeIn]] | list[_EntryTypeIn]] = {
+    'bb': {
+        "rm": [
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER B}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK CAPITAL A}"),
+            ("\N{LATIN CAPITAL LETTER C}",
+             "\N{LATIN CAPITAL LETTER C}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL C}"),
+            ("\N{LATIN CAPITAL LETTER D}",
+             "\N{LATIN CAPITAL LETTER G}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK CAPITAL D}"),
+            ("\N{LATIN CAPITAL LETTER H}",
+             "\N{LATIN CAPITAL LETTER H}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL H}"),
+            ("\N{LATIN CAPITAL LETTER I}",
+             "\N{LATIN CAPITAL LETTER M}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK CAPITAL I}"),
+            ("\N{LATIN CAPITAL LETTER N}",
+             "\N{LATIN CAPITAL LETTER N}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL N}"),
+            ("\N{LATIN CAPITAL LETTER O}",
+             "\N{LATIN CAPITAL LETTER O}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK CAPITAL O}"),
+            ("\N{LATIN CAPITAL LETTER P}",
+             "\N{LATIN CAPITAL LETTER Q}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL P}"),
+            ("\N{LATIN CAPITAL LETTER R}",
+             "\N{LATIN CAPITAL LETTER R}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL R}"),
+            ("\N{LATIN CAPITAL LETTER S}",
+             "\N{LATIN CAPITAL LETTER Y}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK CAPITAL S}"),
+            ("\N{LATIN CAPITAL LETTER Z}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL Z}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK SMALL A}"),
+            ("\N{GREEK CAPITAL LETTER GAMMA}",
+             "\N{GREEK CAPITAL LETTER GAMMA}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL GAMMA}"),
+            ("\N{GREEK CAPITAL LETTER PI}",
+             "\N{GREEK CAPITAL LETTER PI}",
+             "rm",
+             "\N{DOUBLE-STRUCK CAPITAL PI}"),
+            ("\N{GREEK CAPITAL LETTER SIGMA}",
+             "\N{GREEK CAPITAL LETTER SIGMA}",
+             "rm",
+             "\N{DOUBLE-STRUCK N-ARY SUMMATION}"),
+            ("\N{GREEK SMALL LETTER GAMMA}",
+             "\N{GREEK SMALL LETTER GAMMA}",
+             "rm",
+             "\N{DOUBLE-STRUCK SMALL GAMMA}"),
+            ("\N{GREEK SMALL LETTER PI}",
+             "\N{GREEK SMALL LETTER PI}",
+             "rm",
+             "\N{DOUBLE-STRUCK SMALL PI}"),
+        ],
+        "it": [
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER B}",
+             "it",
+             0xe154),
+            ("\N{LATIN CAPITAL LETTER C}",
+             "\N{LATIN CAPITAL LETTER C}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL C}"),
+            ("\N{LATIN CAPITAL LETTER D}",
+             "\N{LATIN CAPITAL LETTER D}",
+             "it",
+             "\N{DOUBLE-STRUCK ITALIC CAPITAL D}"),
+            ("\N{LATIN CAPITAL LETTER E}",
+             "\N{LATIN CAPITAL LETTER G}",
+             "it",
+             0xe156),
+            ("\N{LATIN CAPITAL LETTER H}",
+             "\N{LATIN CAPITAL LETTER H}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL H}"),
+            ("\N{LATIN CAPITAL LETTER I}",
+             "\N{LATIN CAPITAL LETTER M}",
+             "it",
+             0xe159),
+            ("\N{LATIN CAPITAL LETTER N}",
+             "\N{LATIN CAPITAL LETTER N}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL N}"),
+            ("\N{LATIN CAPITAL LETTER O}",
+             "\N{LATIN CAPITAL LETTER O}",
+             "it",
+             0xe15e),
+            ("\N{LATIN CAPITAL LETTER P}",
+             "\N{LATIN CAPITAL LETTER Q}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL P}"),
+            ("\N{LATIN CAPITAL LETTER R}",
+             "\N{LATIN CAPITAL LETTER R}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL R}"),
+            ("\N{LATIN CAPITAL LETTER S}",
+             "\N{LATIN CAPITAL LETTER Y}",
+             "it",
+             0xe15f),
+            ("\N{LATIN CAPITAL LETTER Z}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL Z}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER C}",
+             "it",
+             0xe166),
+            ("\N{LATIN SMALL LETTER D}",
+             "\N{LATIN SMALL LETTER E}",
+             "it",
+             "\N{DOUBLE-STRUCK ITALIC SMALL D}"),
+            ("\N{LATIN SMALL LETTER F}",
+             "\N{LATIN SMALL LETTER H}",
+             "it",
+             0xe169),
+            ("\N{LATIN SMALL LETTER I}",
+             "\N{LATIN SMALL LETTER J}",
+             "it",
+             "\N{DOUBLE-STRUCK ITALIC SMALL I}"),
+            ("\N{LATIN SMALL LETTER K}",
+             "\N{LATIN SMALL LETTER Z}",
+             "it",
+             0xe16c),
+            ("\N{GREEK CAPITAL LETTER GAMMA}",
+             "\N{GREEK CAPITAL LETTER GAMMA}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL GAMMA}"),  # \Gamma (not in beta STIX fonts)
+            ("\N{GREEK CAPITAL LETTER PI}",
+             "\N{GREEK CAPITAL LETTER PI}",
+             "it",
+             "\N{DOUBLE-STRUCK CAPITAL PI}"),
+            ("\N{GREEK CAPITAL LETTER SIGMA}",
+             "\N{GREEK CAPITAL LETTER SIGMA}",
+             "it",
+             "\N{DOUBLE-STRUCK N-ARY SUMMATION}"),  # \Sigma (not in beta STIX fonts)
+            ("\N{GREEK SMALL LETTER GAMMA}",
+             "\N{GREEK SMALL LETTER GAMMA}",
+             "it",
+             "\N{DOUBLE-STRUCK SMALL GAMMA}"),  # \gamma (not in beta STIX fonts)
+            ("\N{GREEK SMALL LETTER PI}",
+             "\N{GREEK SMALL LETTER PI}",
+             "it",
+             "\N{DOUBLE-STRUCK SMALL PI}"),
+        ],
+        "bf": [
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "rm",
+             "\N{MATHEMATICAL DOUBLE-STRUCK DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER B}",
+             "bf",
+             0xe38a),
+            ("\N{LATIN CAPITAL LETTER C}",
+             "\N{LATIN CAPITAL LETTER C}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL C}"),
+            ("\N{LATIN CAPITAL LETTER D}",
+             "\N{LATIN CAPITAL LETTER D}",
+             "bf",
+             "\N{DOUBLE-STRUCK ITALIC CAPITAL D}"),
+            ("\N{LATIN CAPITAL LETTER E}",
+             "\N{LATIN CAPITAL LETTER G}",
+             "bf",
+             0xe38d),
+            ("\N{LATIN CAPITAL LETTER H}",
+             "\N{LATIN CAPITAL LETTER H}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL H}"),
+            ("\N{LATIN CAPITAL LETTER I}",
+             "\N{LATIN CAPITAL LETTER M}",
+             "bf",
+             0xe390),
+            ("\N{LATIN CAPITAL LETTER N}",
+             "\N{LATIN CAPITAL LETTER N}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL N}"),
+            ("\N{LATIN CAPITAL LETTER O}",
+             "\N{LATIN CAPITAL LETTER O}",
+             "bf",
+             0xe395),
+            ("\N{LATIN CAPITAL LETTER P}",
+             "\N{LATIN CAPITAL LETTER Q}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL P}"),
+            ("\N{LATIN CAPITAL LETTER R}",
+             "\N{LATIN CAPITAL LETTER R}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL R}"),
+            ("\N{LATIN CAPITAL LETTER S}",
+             "\N{LATIN CAPITAL LETTER Y}",
+             "bf",
+             0xe396),
+            ("\N{LATIN CAPITAL LETTER Z}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL Z}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER C}",
+             "bf",
+             0xe39d),
+            ("\N{LATIN SMALL LETTER D}",
+             "\N{LATIN SMALL LETTER E}",
+             "bf",
+             "\N{DOUBLE-STRUCK ITALIC SMALL D}"),
+            ("\N{LATIN SMALL LETTER F}",
+             "\N{LATIN SMALL LETTER H}",
+             "bf",
+             0xe3a2),
+            ("\N{LATIN SMALL LETTER I}",
+             "\N{LATIN SMALL LETTER J}",
+             "bf",
+             "\N{DOUBLE-STRUCK ITALIC SMALL I}"),
+            ("\N{LATIN SMALL LETTER K}",
+             "\N{LATIN SMALL LETTER Z}",
+             "bf",
+             0xe3a7),
+            ("\N{GREEK CAPITAL LETTER GAMMA}",
+             "\N{GREEK CAPITAL LETTER GAMMA}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL GAMMA}"),
+            ("\N{GREEK CAPITAL LETTER PI}",
+             "\N{GREEK CAPITAL LETTER PI}",
+             "bf",
+             "\N{DOUBLE-STRUCK CAPITAL PI}"),
+            ("\N{GREEK CAPITAL LETTER SIGMA}",
+             "\N{GREEK CAPITAL LETTER SIGMA}",
+             "bf",
+             "\N{DOUBLE-STRUCK N-ARY SUMMATION}"),
+            ("\N{GREEK SMALL LETTER GAMMA}",
+             "\N{GREEK SMALL LETTER GAMMA}",
+             "bf",
+             "\N{DOUBLE-STRUCK SMALL GAMMA}"),
+            ("\N{GREEK SMALL LETTER PI}",
+             "\N{GREEK SMALL LETTER PI}",
+             "bf",
+             "\N{DOUBLE-STRUCK SMALL PI}"),
+        ],
+    },
+    'cal': [
+        ("\N{LATIN CAPITAL LETTER A}",
+         "\N{LATIN CAPITAL LETTER Z}",
+         "it",
+         0xe22d),
+    ],
+    'frak': {
+        "rm": [
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER B}",
+             "rm",
+             "\N{MATHEMATICAL FRAKTUR CAPITAL A}"),
+            ("\N{LATIN CAPITAL LETTER C}",
+             "\N{LATIN CAPITAL LETTER C}",
+             "rm",
+             "\N{BLACK-LETTER CAPITAL C}"),
+            ("\N{LATIN CAPITAL LETTER D}",
+             "\N{LATIN CAPITAL LETTER G}",
+             "rm",
+             "\N{MATHEMATICAL FRAKTUR CAPITAL D}"),
+            ("\N{LATIN CAPITAL LETTER H}",
+             "\N{LATIN CAPITAL LETTER H}",
+             "rm",
+             "\N{BLACK-LETTER CAPITAL H}"),
+            ("\N{LATIN CAPITAL LETTER I}",
+             "\N{LATIN CAPITAL LETTER I}",
+             "rm",
+             "\N{BLACK-LETTER CAPITAL I}"),
+            ("\N{LATIN CAPITAL LETTER J}",
+             "\N{LATIN CAPITAL LETTER Q}",
+             "rm",
+             "\N{MATHEMATICAL FRAKTUR CAPITAL J}"),
+            ("\N{LATIN CAPITAL LETTER R}",
+             "\N{LATIN CAPITAL LETTER R}",
+             "rm",
+             "\N{BLACK-LETTER CAPITAL R}"),
+            ("\N{LATIN CAPITAL LETTER S}",
+             "\N{LATIN CAPITAL LETTER Y}",
+             "rm",
+             "\N{MATHEMATICAL FRAKTUR CAPITAL S}"),
+            ("\N{LATIN CAPITAL LETTER Z}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "rm",
+             "\N{BLACK-LETTER CAPITAL Z}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "rm",
+             "\N{MATHEMATICAL FRAKTUR SMALL A}"),
+            ],
+        "bf": [
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "bf",
+             "\N{MATHEMATICAL BOLD FRAKTUR CAPITAL A}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "bf",
+             "\N{MATHEMATICAL BOLD FRAKTUR SMALL A}"),
+        ],
+    },
+    'scr': [
+        ("\N{LATIN CAPITAL LETTER A}",
+         "\N{LATIN CAPITAL LETTER A}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL A}"),
+        ("\N{LATIN CAPITAL LETTER B}",
+         "\N{LATIN CAPITAL LETTER B}",
+         "it",
+         "\N{SCRIPT CAPITAL B}"),
+        ("\N{LATIN CAPITAL LETTER C}",
+         "\N{LATIN CAPITAL LETTER D}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL C}"),
+        ("\N{LATIN CAPITAL LETTER E}",
+         "\N{LATIN CAPITAL LETTER F}",
+         "it",
+         "\N{SCRIPT CAPITAL E}"),
+        ("\N{LATIN CAPITAL LETTER G}",
+         "\N{LATIN CAPITAL LETTER G}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL G}"),
+        ("\N{LATIN CAPITAL LETTER H}",
+         "\N{LATIN CAPITAL LETTER H}",
+         "it",
+         "\N{SCRIPT CAPITAL H}"),
+        ("\N{LATIN CAPITAL LETTER I}",
+         "\N{LATIN CAPITAL LETTER I}",
+         "it",
+         "\N{SCRIPT CAPITAL I}"),
+        ("\N{LATIN CAPITAL LETTER J}",
+         "\N{LATIN CAPITAL LETTER K}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL J}"),
+        ("\N{LATIN CAPITAL LETTER L}",
+         "\N{LATIN CAPITAL LETTER L}",
+         "it",
+         "\N{SCRIPT CAPITAL L}"),
+        ("\N{LATIN CAPITAL LETTER M}",
+         "\N{LATIN CAPITAL LETTER M}",
+         "it",
+         "\N{SCRIPT CAPITAL M}"),
+        ("\N{LATIN CAPITAL LETTER N}",
+         "\N{LATIN CAPITAL LETTER Q}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL N}"),
+        ("\N{LATIN CAPITAL LETTER R}",
+         "\N{LATIN CAPITAL LETTER R}",
+         "it",
+         "\N{SCRIPT CAPITAL R}"),
+        ("\N{LATIN CAPITAL LETTER S}",
+         "\N{LATIN CAPITAL LETTER Z}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT CAPITAL S}"),
+        ("\N{LATIN SMALL LETTER A}",
+         "\N{LATIN SMALL LETTER D}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT SMALL A}"),
+        ("\N{LATIN SMALL LETTER E}",
+         "\N{LATIN SMALL LETTER E}",
+         "it",
+         "\N{SCRIPT SMALL E}"),
+        ("\N{LATIN SMALL LETTER F}",
+         "\N{LATIN SMALL LETTER F}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT SMALL F}"),
+        ("\N{LATIN SMALL LETTER G}",
+         "\N{LATIN SMALL LETTER G}",
+         "it",
+         "\N{SCRIPT SMALL G}"),
+        ("\N{LATIN SMALL LETTER H}",
+         "\N{LATIN SMALL LETTER N}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT SMALL H}"),
+        ("\N{LATIN SMALL LETTER O}",
+         "\N{LATIN SMALL LETTER O}",
+         "it",
+         "\N{SCRIPT SMALL O}"),
+        ("\N{LATIN SMALL LETTER P}",
+         "\N{LATIN SMALL LETTER Z}",
+         "it",
+         "\N{MATHEMATICAL SCRIPT SMALL P}"),
+    ],
+    'sf': {
+        "rm": [
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "rm",
+             "\N{MATHEMATICAL SANS-SERIF DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "rm",
+             "\N{MATHEMATICAL SANS-SERIF CAPITAL A}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "rm",
+             "\N{MATHEMATICAL SANS-SERIF SMALL A}"),
+            ("\N{GREEK CAPITAL LETTER ALPHA}",
+             "\N{GREEK CAPITAL LETTER OMEGA}",
+             "rm",
+             0xe17d),
+            ("\N{GREEK SMALL LETTER ALPHA}",
+             "\N{GREEK SMALL LETTER OMEGA}",
+             "rm",
+             0xe196),
+            ("\N{GREEK THETA SYMBOL}",
+             "\N{GREEK THETA SYMBOL}",
+             "rm",
+             0xe1b0),
+            ("\N{GREEK PHI SYMBOL}",
+             "\N{GREEK PHI SYMBOL}",
+             "rm",
+             0xe1b1),
+            ("\N{GREEK PI SYMBOL}",
+             "\N{GREEK PI SYMBOL}",
+             "rm",
+             0xe1b3),
+            ("\N{GREEK RHO SYMBOL}",
+             "\N{GREEK RHO SYMBOL}",
+             "rm",
+             0xe1b2),
+            ("\N{GREEK LUNATE EPSILON SYMBOL}",
+             "\N{GREEK LUNATE EPSILON SYMBOL}",
+             "rm",
+             0xe1af),
+            ("\N{PARTIAL DIFFERENTIAL}",
+             "\N{PARTIAL DIFFERENTIAL}",
+             "rm",
+             0xe17c),
+        ],
+        "it": [
+            # These numerals are actually upright.  We don't actually
+            # want italic numerals ever.
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "rm",
+             "\N{MATHEMATICAL SANS-SERIF DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "it",
+             "\N{MATHEMATICAL SANS-SERIF ITALIC CAPITAL A}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "it",
+             "\N{MATHEMATICAL SANS-SERIF ITALIC SMALL A}"),
+            ("\N{GREEK CAPITAL LETTER ALPHA}",
+             "\N{GREEK CAPITAL LETTER OMEGA}",
+             "rm",
+             0xe17d),
+            ("\N{GREEK SMALL LETTER ALPHA}",
+             "\N{GREEK SMALL LETTER OMEGA}",
+             "it",
+             0xe1d8),
+            ("\N{GREEK THETA SYMBOL}",
+             "\N{GREEK THETA SYMBOL}",
+             "it",
+             0xe1f2),
+            ("\N{GREEK PHI SYMBOL}",
+             "\N{GREEK PHI SYMBOL}",
+             "it",
+             0xe1f3),
+            ("\N{GREEK PI SYMBOL}",
+             "\N{GREEK PI SYMBOL}",
+             "it",
+             0xe1f5),
+            ("\N{GREEK RHO SYMBOL}",
+             "\N{GREEK RHO SYMBOL}",
+             "it",
+             0xe1f4),
+            ("\N{GREEK LUNATE EPSILON SYMBOL}",
+             "\N{GREEK LUNATE EPSILON SYMBOL}",
+             "it",
+             0xe1f1),
+        ],
+        "bf": [
+            ("\N{DIGIT ZERO}",
+             "\N{DIGIT NINE}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD DIGIT ZERO}"),
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD CAPITAL A}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD SMALL A}"),
+            ("\N{GREEK CAPITAL LETTER ALPHA}",
+             "\N{GREEK CAPITAL LETTER OMEGA}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD CAPITAL ALPHA}"),
+            ("\N{GREEK SMALL LETTER ALPHA}",
+             "\N{GREEK SMALL LETTER OMEGA}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD SMALL ALPHA}"),
+            ("\N{GREEK THETA SYMBOL}",
+             "\N{GREEK THETA SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD THETA SYMBOL}"),
+            ("\N{GREEK PHI SYMBOL}",
+             "\N{GREEK PHI SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD PHI SYMBOL}"),
+            ("\N{GREEK PI SYMBOL}",
+             "\N{GREEK PI SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD PI SYMBOL}"),
+            ("\N{GREEK KAPPA SYMBOL}",
+             "\N{GREEK KAPPA SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD KAPPA SYMBOL}"),
+            ("\N{GREEK RHO SYMBOL}",
+             "\N{GREEK RHO SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD RHO SYMBOL}"),
+            ("\N{GREEK LUNATE EPSILON SYMBOL}",
+             "\N{GREEK LUNATE EPSILON SYMBOL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD EPSILON SYMBOL}"),
+            ("\N{PARTIAL DIFFERENTIAL}",
+             "\N{PARTIAL DIFFERENTIAL}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD PARTIAL DIFFERENTIAL}"),
+            ("\N{NABLA}",
+             "\N{NABLA}",
+             "bf",
+             "\N{MATHEMATICAL SANS-SERIF BOLD NABLA}"),
+        ],
+        "bfit": [
+            ("\N{LATIN CAPITAL LETTER A}",
+             "\N{LATIN CAPITAL LETTER Z}",
+             "bfit",
+             "\N{MATHEMATICAL BOLD ITALIC CAPITAL A}"),
+            ("\N{LATIN SMALL LETTER A}",
+             "\N{LATIN SMALL LETTER Z}",
+             "bfit",
+             "\N{MATHEMATICAL BOLD ITALIC SMALL A}"),
+            ("\N{GREEK CAPITAL LETTER GAMMA}",
+             "\N{GREEK CAPITAL LETTER OMEGA}",
+             "bfit",
+             "\N{MATHEMATICAL BOLD ITALIC CAPITAL GAMMA}"),
+            ("\N{GREEK SMALL LETTER ALPHA}",
+             "\N{GREEK SMALL LETTER OMEGA}",
+             "bfit",
+             "\N{MATHEMATICAL BOLD ITALIC SMALL ALPHA}"),
+        ],
+    },
+    'tt': [
+        ("\N{DIGIT ZERO}",
+         "\N{DIGIT NINE}",
+         "rm",
+         "\N{MATHEMATICAL MONOSPACE DIGIT ZERO}"),
+        ("\N{LATIN CAPITAL LETTER A}",
+         "\N{LATIN CAPITAL LETTER Z}",
+         "rm",
+         "\N{MATHEMATICAL MONOSPACE CAPITAL A}"),
+        ("\N{LATIN SMALL LETTER A}",
+         "\N{LATIN SMALL LETTER Z}",
+         "rm",
+         "\N{MATHEMATICAL MONOSPACE SMALL A}")
+    ],
+}
+
+
+@overload
+def _normalize_stix_fontcodes(d: _EntryTypeIn) -> _EntryTypeOut: ...
+
+
+@overload
+def _normalize_stix_fontcodes(d: list[_EntryTypeIn]) -> list[_EntryTypeOut]: ...
+
+
+@overload
+def _normalize_stix_fontcodes(d: dict[str, list[_EntryTypeIn] |
+                                      dict[str, list[_EntryTypeIn]]]
+                              ) -> dict[str, list[_EntryTypeOut] |
+                                        dict[str, list[_EntryTypeOut]]]: ...
+
+
+def _normalize_stix_fontcodes(d):
+    if isinstance(d, tuple):
+        return tuple(ord(x) if isinstance(x, str) and len(x) == 1 else x for x in d)
+    elif isinstance(d, list):
+        return [_normalize_stix_fontcodes(x) for x in d]
+    elif isinstance(d, dict):
+        return {k: _normalize_stix_fontcodes(v) for k, v in d.items()}
+
+
+stix_virtual_fonts: dict[str, dict[str, list[_EntryTypeOut]] | list[_EntryTypeOut]]
+stix_virtual_fonts = _normalize_stix_fontcodes(_stix_virtual_fonts)
+
+# Free redundant list now that it has been normalized
+del _stix_virtual_fonts
+
+# Fix some incorrect glyphs.
+stix_glyph_fixes = {
+    # Cap and Cup glyphs are swapped.
+    0x22d2: 0x22d3,
+    0x22d3: 0x22d2,
+}
diff --git a/lib/python3.12/site-packages/matplotlib/_pylab_helpers.py b/lib/python3.12/site-packages/matplotlib/_pylab_helpers.py
new file mode 100644
index 0000000000000000000000000000000000000000..a3861aef592008a84ffddadb7a0c76c8833a30af
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_pylab_helpers.py
@@ -0,0 +1,134 @@
+"""
+Manage figures for the pyplot interface.
+"""
+
+import atexit
+from collections import OrderedDict
+
+
+class Gcf:
+    """
+    Singleton to maintain the relation between figures and their managers, and
+    keep track of and "active" figure and manager.
+
+    The canvas of a figure created through pyplot is associated with a figure
+    manager, which handles the interaction between the figure and the backend.
+    pyplot keeps track of figure managers using an identifier, the "figure
+    number" or "manager number" (which can actually be any hashable value);
+    this number is available as the :attr:`number` attribute of the manager.
+
+    This class is never instantiated; it consists of an `OrderedDict` mapping
+    figure/manager numbers to managers, and a set of class methods that
+    manipulate this `OrderedDict`.
+
+    Attributes
+    ----------
+    figs : OrderedDict
+        `OrderedDict` mapping numbers to managers; the active manager is at the
+        end.
+    """
+
+    figs = OrderedDict()
+
+    @classmethod
+    def get_fig_manager(cls, num):
+        """
+        If manager number *num* exists, make it the active one and return it;
+        otherwise return *None*.
+        """
+        manager = cls.figs.get(num, None)
+        if manager is not None:
+            cls.set_active(manager)
+        return manager
+
+    @classmethod
+    def destroy(cls, num):
+        """
+        Destroy manager *num* -- either a manager instance or a manager number.
+
+        In the interactive backends, this is bound to the window "destroy" and
+        "delete" events.
+
+        It is recommended to pass a manager instance, to avoid confusion when
+        two managers share the same number.
+        """
+        if all(hasattr(num, attr) for attr in ["num", "destroy"]):
+            manager = num
+            if cls.figs.get(manager.num) is manager:
+                cls.figs.pop(manager.num)
+        else:
+            try:
+                manager = cls.figs.pop(num)
+            except KeyError:
+                return
+        if hasattr(manager, "_cidgcf"):
+            manager.canvas.mpl_disconnect(manager._cidgcf)
+        manager.destroy()
+
+    @classmethod
+    def destroy_fig(cls, fig):
+        """Destroy figure *fig*."""
+        num = next((manager.num for manager in cls.figs.values()
+                    if manager.canvas.figure == fig), None)
+        if num is not None:
+            cls.destroy(num)
+
+    @classmethod
+    def destroy_all(cls):
+        """Destroy all figures."""
+        for manager in list(cls.figs.values()):
+            manager.canvas.mpl_disconnect(manager._cidgcf)
+            manager.destroy()
+        cls.figs.clear()
+
+    @classmethod
+    def has_fignum(cls, num):
+        """Return whether figure number *num* exists."""
+        return num in cls.figs
+
+    @classmethod
+    def get_all_fig_managers(cls):
+        """Return a list of figure managers."""
+        return list(cls.figs.values())
+
+    @classmethod
+    def get_num_fig_managers(cls):
+        """Return the number of figures being managed."""
+        return len(cls.figs)
+
+    @classmethod
+    def get_active(cls):
+        """Return the active manager, or *None* if there is no manager."""
+        return next(reversed(cls.figs.values())) if cls.figs else None
+
+    @classmethod
+    def _set_new_active_manager(cls, manager):
+        """Adopt *manager* into pyplot and make it the active manager."""
+        if not hasattr(manager, "_cidgcf"):
+            manager._cidgcf = manager.canvas.mpl_connect(
+                "button_press_event", lambda event: cls.set_active(manager))
+        fig = manager.canvas.figure
+        fig._number = manager.num
+        label = fig.get_label()
+        if label:
+            manager.set_window_title(label)
+        cls.set_active(manager)
+
+    @classmethod
+    def set_active(cls, manager):
+        """Make *manager* the active manager."""
+        cls.figs[manager.num] = manager
+        cls.figs.move_to_end(manager.num)
+
+    @classmethod
+    def draw_all(cls, force=False):
+        """
+        Redraw all stale managed figures, or, if *force* is True, all managed
+        figures.
+        """
+        for manager in cls.get_all_fig_managers():
+            if force or manager.canvas.figure.stale:
+                manager.canvas.draw_idle()
+
+
+atexit.register(Gcf.destroy_all)
diff --git a/lib/python3.12/site-packages/matplotlib/_pylab_helpers.pyi b/lib/python3.12/site-packages/matplotlib/_pylab_helpers.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bdd8cfba3173030b37b24af412970cbb62fee3ef
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_pylab_helpers.pyi
@@ -0,0 +1,29 @@
+from collections import OrderedDict
+
+from matplotlib.backend_bases import FigureManagerBase
+from matplotlib.figure import Figure
+
+class Gcf:
+    figs: OrderedDict[int, FigureManagerBase]
+    @classmethod
+    def get_fig_manager(cls, num: int) -> FigureManagerBase | None: ...
+    @classmethod
+    def destroy(cls, num: int | FigureManagerBase) -> None: ...
+    @classmethod
+    def destroy_fig(cls, fig: Figure) -> None: ...
+    @classmethod
+    def destroy_all(cls) -> None: ...
+    @classmethod
+    def has_fignum(cls, num: int) -> bool: ...
+    @classmethod
+    def get_all_fig_managers(cls) -> list[FigureManagerBase]: ...
+    @classmethod
+    def get_num_fig_managers(cls) -> int: ...
+    @classmethod
+    def get_active(cls) -> FigureManagerBase | None: ...
+    @classmethod
+    def _set_new_active_manager(cls, manager: FigureManagerBase) -> None: ...
+    @classmethod
+    def set_active(cls, manager: FigureManagerBase) -> None: ...
+    @classmethod
+    def draw_all(cls, force: bool = ...) -> None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/_text_helpers.py b/lib/python3.12/site-packages/matplotlib/_text_helpers.py
new file mode 100644
index 0000000000000000000000000000000000000000..b9603b114bc245ecf32da926573ddb4157210c7a
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_text_helpers.py
@@ -0,0 +1,82 @@
+"""
+Low-level text helper utilities.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from . import _api
+from .ft2font import FT2Font, Kerning, LoadFlags
+
+
+@dataclasses.dataclass(frozen=True)
+class LayoutItem:
+    ft_object: FT2Font
+    char: str
+    glyph_idx: int
+    x: float
+    prev_kern: float
+
+
+def warn_on_missing_glyph(codepoint, fontnames):
+    _api.warn_external(
+        f"Glyph {codepoint} "
+        f"({chr(codepoint).encode('ascii', 'namereplace').decode('ascii')}) "
+        f"missing from font(s) {fontnames}.")
+
+    block = ("Hebrew" if 0x0590 <= codepoint <= 0x05ff else
+             "Arabic" if 0x0600 <= codepoint <= 0x06ff else
+             "Devanagari" if 0x0900 <= codepoint <= 0x097f else
+             "Bengali" if 0x0980 <= codepoint <= 0x09ff else
+             "Gurmukhi" if 0x0a00 <= codepoint <= 0x0a7f else
+             "Gujarati" if 0x0a80 <= codepoint <= 0x0aff else
+             "Oriya" if 0x0b00 <= codepoint <= 0x0b7f else
+             "Tamil" if 0x0b80 <= codepoint <= 0x0bff else
+             "Telugu" if 0x0c00 <= codepoint <= 0x0c7f else
+             "Kannada" if 0x0c80 <= codepoint <= 0x0cff else
+             "Malayalam" if 0x0d00 <= codepoint <= 0x0d7f else
+             "Sinhala" if 0x0d80 <= codepoint <= 0x0dff else
+             None)
+    if block:
+        _api.warn_external(
+            f"Matplotlib currently does not support {block} natively.")
+
+
+def layout(string, font, *, kern_mode=Kerning.DEFAULT):
+    """
+    Render *string* with *font*.
+
+    For each character in *string*, yield a LayoutItem instance. When such an instance
+    is yielded, the font's glyph is set to the corresponding character.
+
+    Parameters
+    ----------
+    string : str
+        The string to be rendered.
+    font : FT2Font
+        The font.
+    kern_mode : Kerning
+        A FreeType kerning mode.
+
+    Yields
+    ------
+    LayoutItem
+    """
+    x = 0
+    prev_glyph_idx = None
+    char_to_font = font._get_fontmap(string)
+    base_font = font
+    for char in string:
+        # This has done the fallback logic
+        font = char_to_font.get(char, base_font)
+        glyph_idx = font.get_char_index(ord(char))
+        kern = (
+            base_font.get_kerning(prev_glyph_idx, glyph_idx, kern_mode) / 64
+            if prev_glyph_idx is not None else 0.
+        )
+        x += kern
+        glyph = font.load_glyph(glyph_idx, flags=LoadFlags.NO_HINTING)
+        yield LayoutItem(font, char, glyph_idx, x, kern)
+        x += glyph.linearHoriAdvance / 65536
+        prev_glyph_idx = glyph_idx
diff --git a/lib/python3.12/site-packages/matplotlib/_tight_bbox.py b/lib/python3.12/site-packages/matplotlib/_tight_bbox.py
new file mode 100644
index 0000000000000000000000000000000000000000..db72bbdff020680dfd833229cac41e9b33e428ee
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_tight_bbox.py
@@ -0,0 +1,84 @@
+"""
+Helper module for the *bbox_inches* parameter in `.Figure.savefig`.
+"""
+
+from matplotlib.transforms import Bbox, TransformedBbox, Affine2D
+
+
+def adjust_bbox(fig, bbox_inches, fixed_dpi=None):
+    """
+    Temporarily adjust the figure so that only the specified area
+    (bbox_inches) is saved.
+
+    It modifies fig.bbox, fig.bbox_inches,
+    fig.transFigure._boxout, and fig.patch.  While the figure size
+    changes, the scale of the original figure is conserved.  A
+    function which restores the original values are returned.
+    """
+    origBbox = fig.bbox
+    origBboxInches = fig.bbox_inches
+    _boxout = fig.transFigure._boxout
+
+    old_aspect = []
+    locator_list = []
+    sentinel = object()
+    for ax in fig.axes:
+        locator = ax.get_axes_locator()
+        if locator is not None:
+            ax.apply_aspect(locator(ax, None))
+        locator_list.append(locator)
+        current_pos = ax.get_position(original=False).frozen()
+        ax.set_axes_locator(lambda a, r, _pos=current_pos: _pos)
+        # override the method that enforces the aspect ratio on the Axes
+        if 'apply_aspect' in ax.__dict__:
+            old_aspect.append(ax.apply_aspect)
+        else:
+            old_aspect.append(sentinel)
+        ax.apply_aspect = lambda pos=None: None
+
+    def restore_bbox():
+        for ax, loc, aspect in zip(fig.axes, locator_list, old_aspect):
+            ax.set_axes_locator(loc)
+            if aspect is sentinel:
+                # delete our no-op function which un-hides the original method
+                del ax.apply_aspect
+            else:
+                ax.apply_aspect = aspect
+
+        fig.bbox = origBbox
+        fig.bbox_inches = origBboxInches
+        fig.transFigure._boxout = _boxout
+        fig.transFigure.invalidate()
+        fig.patch.set_bounds(0, 0, 1, 1)
+
+    if fixed_dpi is None:
+        fixed_dpi = fig.dpi
+    tr = Affine2D().scale(fixed_dpi)
+    dpi_scale = fixed_dpi / fig.dpi
+
+    fig.bbox_inches = Bbox.from_bounds(0, 0, *bbox_inches.size)
+    x0, y0 = tr.transform(bbox_inches.p0)
+    w1, h1 = fig.bbox.size * dpi_scale
+    fig.transFigure._boxout = Bbox.from_bounds(-x0, -y0, w1, h1)
+    fig.transFigure.invalidate()
+
+    fig.bbox = TransformedBbox(fig.bbox_inches, tr)
+
+    fig.patch.set_bounds(x0 / w1, y0 / h1,
+                         fig.bbox.width / w1, fig.bbox.height / h1)
+
+    return restore_bbox
+
+
+def process_figure_for_rasterizing(fig, bbox_inches_restore, fixed_dpi=None):
+    """
+    A function that needs to be called when figure dpi changes during the
+    drawing (e.g., rasterizing).  It recovers the bbox and re-adjust it with
+    the new dpi.
+    """
+
+    bbox_inches, restore_bbox = bbox_inches_restore
+    restore_bbox()
+    r = adjust_bbox(fig, bbox_inches, fixed_dpi)
+
+    return bbox_inches, r
diff --git a/lib/python3.12/site-packages/matplotlib/_tri.pyi b/lib/python3.12/site-packages/matplotlib/_tri.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..a0c710fc2309fbfac3f37297eda919d86de32c76
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_tri.pyi
@@ -0,0 +1,36 @@
+# This is a private module implemented in C++
+from typing import final
+
+import numpy as np
+import numpy.typing as npt
+
+@final
+class TrapezoidMapTriFinder:
+    def __init__(self, triangulation: Triangulation): ...
+    def find_many(self, x: npt.NDArray[np.float64], y: npt.NDArray[np.float64]) -> npt.NDArray[np.int_]: ...
+    def get_tree_stats(self) -> list[int | float]: ...
+    def initialize(self) -> None: ...
+    def print_tree(self) -> None: ...
+
+@final
+class TriContourGenerator:
+    def __init__(self, triangulation: Triangulation, z: npt.NDArray[np.float64]): ...
+    def create_contour(self, level: float) -> tuple[list[float], list[int]]: ...
+    def create_filled_contour(self, lower_level: float, upper_level: float) -> tuple[list[float], list[int]]: ...
+
+@final
+class Triangulation:
+    def __init__(
+        self,
+        x: npt.NDArray[np.float64],
+        y: npt.NDArray[np.float64],
+        triangles: npt.NDArray[np.int_],
+        mask: npt.NDArray[np.bool_] | tuple[()],
+        edges: npt.NDArray[np.int_] | tuple[()],
+        neighbors: npt.NDArray[np.int_] | tuple[()],
+        correct_triangle_orientation: bool,
+    ): ...
+    def calculate_plane_coefficients(self, z: npt.ArrayLike) -> npt.NDArray[np.float64]: ...
+    def get_edges(self) -> npt.NDArray[np.int_]: ...
+    def get_neighbors(self) -> npt.NDArray[np.int_]: ...
+    def set_mask(self, mask: npt.NDArray[np.bool_] | tuple[()]) -> None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/_version.py b/lib/python3.12/site-packages/matplotlib/_version.py
new file mode 100644
index 0000000000000000000000000000000000000000..90807445c956c6ca454fbac2a45b1112f59030be
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/_version.py
@@ -0,0 +1 @@
+version = "3.10.3"
diff --git a/lib/python3.12/site-packages/matplotlib/animation.py b/lib/python3.12/site-packages/matplotlib/animation.py
new file mode 100644
index 0000000000000000000000000000000000000000..a87f002011249f353bd740363e55a0d32c62bc38
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/animation.py
@@ -0,0 +1,1823 @@
+import abc
+import base64
+import contextlib
+from io import BytesIO, TextIOWrapper
+import itertools
+import logging
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from tempfile import TemporaryDirectory
+import uuid
+import warnings
+
+import numpy as np
+from PIL import Image
+
+import matplotlib as mpl
+from matplotlib._animation_data import (
+    DISPLAY_TEMPLATE, INCLUDED_FRAMES, JS_INCLUDE, STYLE_INCLUDE)
+from matplotlib import _api, cbook
+import matplotlib.colors as mcolors
+
+_log = logging.getLogger(__name__)
+
+# Process creation flag for subprocess to prevent it raising a terminal
+# window. See for example https://stackoverflow.com/q/24130623/
+subprocess_creation_flags = (
+    subprocess.CREATE_NO_WINDOW if sys.platform == 'win32' else 0)
+
+
+def adjusted_figsize(w, h, dpi, n):
+    """
+    Compute figure size so that pixels are a multiple of n.
+
+    Parameters
+    ----------
+    w, h : float
+        Size in inches.
+
+    dpi : float
+        The dpi.
+
+    n : int
+        The target multiple.
+
+    Returns
+    -------
+    wnew, hnew : float
+        The new figure size in inches.
+    """
+
+    # this maybe simplified if / when we adopt consistent rounding for
+    # pixel size across the whole library
+    def correct_roundoff(x, dpi, n):
+        if int(x*dpi) % n != 0:
+            if int(np.nextafter(x, np.inf)*dpi) % n == 0:
+                x = np.nextafter(x, np.inf)
+            elif int(np.nextafter(x, -np.inf)*dpi) % n == 0:
+                x = np.nextafter(x, -np.inf)
+        return x
+
+    wnew = int(w * dpi / n) * n / dpi
+    hnew = int(h * dpi / n) * n / dpi
+    return correct_roundoff(wnew, dpi, n), correct_roundoff(hnew, dpi, n)
+
+
+class MovieWriterRegistry:
+    """Registry of available writer classes by human readable name."""
+
+    def __init__(self):
+        self._registered = dict()
+
+    def register(self, name):
+        """
+        Decorator for registering a class under a name.
+
+        Example use::
+
+            @registry.register(name)
+            class Foo:
+                pass
+        """
+        def wrapper(writer_cls):
+            self._registered[name] = writer_cls
+            return writer_cls
+        return wrapper
+
+    def is_available(self, name):
+        """
+        Check if given writer is available by name.
+
+        Parameters
+        ----------
+        name : str
+
+        Returns
+        -------
+        bool
+        """
+        try:
+            cls = self._registered[name]
+        except KeyError:
+            return False
+        return cls.isAvailable()
+
+    def __iter__(self):
+        """Iterate over names of available writer class."""
+        for name in self._registered:
+            if self.is_available(name):
+                yield name
+
+    def list(self):
+        """Get a list of available MovieWriters."""
+        return [*self]
+
+    def __getitem__(self, name):
+        """Get an available writer class from its name."""
+        if self.is_available(name):
+            return self._registered[name]
+        raise RuntimeError(f"Requested MovieWriter ({name}) not available")
+
+
+writers = MovieWriterRegistry()
+
+
+class AbstractMovieWriter(abc.ABC):
+    """
+    Abstract base class for writing movies, providing a way to grab frames by
+    calling `~AbstractMovieWriter.grab_frame`.
+
+    `setup` is called to start the process and `finish` is called afterwards.
+    `saving` is provided as a context manager to facilitate this process as ::
+
+        with moviewriter.saving(fig, outfile='myfile.mp4', dpi=100):
+            # Iterate over frames
+            moviewriter.grab_frame(**savefig_kwargs)
+
+    The use of the context manager ensures that `setup` and `finish` are
+    performed as necessary.
+
+    An instance of a concrete subclass of this class can be given as the
+    ``writer`` argument of `Animation.save()`.
+    """
+
+    def __init__(self, fps=5, metadata=None, codec=None, bitrate=None):
+        self.fps = fps
+        self.metadata = metadata if metadata is not None else {}
+        self.codec = mpl._val_or_rc(codec, 'animation.codec')
+        self.bitrate = mpl._val_or_rc(bitrate, 'animation.bitrate')
+
+    @abc.abstractmethod
+    def setup(self, fig, outfile, dpi=None):
+        """
+        Setup for writing the movie file.
+
+        Parameters
+        ----------
+        fig : `~matplotlib.figure.Figure`
+            The figure object that contains the information for frames.
+        outfile : str
+            The filename of the resulting movie file.
+        dpi : float, default: ``fig.dpi``
+            The DPI (or resolution) for the file.  This controls the size
+            in pixels of the resulting movie file.
+        """
+        # Check that path is valid
+        Path(outfile).parent.resolve(strict=True)
+        self.outfile = outfile
+        self.fig = fig
+        if dpi is None:
+            dpi = self.fig.dpi
+        self.dpi = dpi
+
+    @property
+    def frame_size(self):
+        """A tuple ``(width, height)`` in pixels of a movie frame."""
+        w, h = self.fig.get_size_inches()
+        return int(w * self.dpi), int(h * self.dpi)
+
+    def _supports_transparency(self):
+        """
+        Whether this writer supports transparency.
+
+        Writers may consult output file type and codec to determine this at runtime.
+        """
+        return False
+
+    @abc.abstractmethod
+    def grab_frame(self, **savefig_kwargs):
+        """
+        Grab the image information from the figure and save as a movie frame.
+
+        All keyword arguments in *savefig_kwargs* are passed on to the
+        `~.Figure.savefig` call that saves the figure.  However, several
+        keyword arguments that are supported by `~.Figure.savefig` may not be
+        passed as they are controlled by the MovieWriter:
+
+        - *dpi*, *bbox_inches*:  These may not be passed because each frame of the
+           animation much be exactly the same size in pixels.
+        - *format*: This is controlled by the MovieWriter.
+        """
+
+    @abc.abstractmethod
+    def finish(self):
+        """Finish any processing for writing the movie."""
+
+    @contextlib.contextmanager
+    def saving(self, fig, outfile, dpi, *args, **kwargs):
+        """
+        Context manager to facilitate writing the movie file.
+
+        ``*args, **kw`` are any parameters that should be passed to `setup`.
+        """
+        if mpl.rcParams['savefig.bbox'] == 'tight':
+            _log.info("Disabling savefig.bbox = 'tight', as it may cause "
+                      "frame size to vary, which is inappropriate for "
+                      "animation.")
+
+        # This particular sequence is what contextlib.contextmanager wants
+        self.setup(fig, outfile, dpi, *args, **kwargs)
+        with mpl.rc_context({'savefig.bbox': None}):
+            try:
+                yield self
+            finally:
+                self.finish()
+
+
+class MovieWriter(AbstractMovieWriter):
+    """
+    Base class for writing movies.
+
+    This is a base class for MovieWriter subclasses that write a movie frame
+    data to a pipe. You cannot instantiate this class directly.
+    See examples for how to use its subclasses.
+
+    Attributes
+    ----------
+    frame_format : str
+        The format used in writing frame data, defaults to 'rgba'.
+    fig : `~matplotlib.figure.Figure`
+        The figure to capture data from.
+        This must be provided by the subclasses.
+    """
+
+    # Builtin writer subclasses additionally define the _exec_key and _args_key
+    # attributes, which indicate the rcParams entries where the path to the
+    # executable and additional command-line arguments to the executable are
+    # stored.  Third-party writers cannot meaningfully set these as they cannot
+    # extend rcParams with new keys.
+
+    # Pipe-based writers only support RGBA, but file-based ones support more
+    # formats.
+    supported_formats = ["rgba"]
+
+    def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
+                 metadata=None):
+        """
+        Parameters
+        ----------
+        fps : int, default: 5
+            Movie frame rate (per second).
+        codec : str or None, default: :rc:`animation.codec`
+            The codec to use.
+        bitrate : int, default: :rc:`animation.bitrate`
+            The bitrate of the movie, in kilobits per second.  Higher values
+            means higher quality movies, but increase the file size.  A value
+            of -1 lets the underlying movie encoder select the bitrate.
+        extra_args : list of str or None, optional
+            Extra command-line arguments passed to the underlying movie encoder. These
+            arguments are passed last to the encoder, just before the filename. The
+            default, None, means to use :rc:`animation.[name-of-encoder]_args` for the
+            builtin writers.
+        metadata : dict[str, str], default: {}
+            A dictionary of keys and values for metadata to include in the
+            output file. Some keys that may be of use include:
+            title, artist, genre, subject, copyright, srcform, comment.
+        """
+        if type(self) is MovieWriter:
+            # TODO MovieWriter is still an abstract class and needs to be
+            #      extended with a mixin. This should be clearer in naming
+            #      and description. For now, just give a reasonable error
+            #      message to users.
+            raise TypeError(
+                'MovieWriter cannot be instantiated directly. Please use one '
+                'of its subclasses.')
+
+        super().__init__(fps=fps, metadata=metadata, codec=codec,
+                         bitrate=bitrate)
+        self.frame_format = self.supported_formats[0]
+        self.extra_args = extra_args
+
+    def _adjust_frame_size(self):
+        if self.codec == 'h264':
+            wo, ho = self.fig.get_size_inches()
+            w, h = adjusted_figsize(wo, ho, self.dpi, 2)
+            if (wo, ho) != (w, h):
+                self.fig.set_size_inches(w, h, forward=True)
+                _log.info('figure size in inches has been adjusted '
+                          'from %s x %s to %s x %s', wo, ho, w, h)
+        else:
+            w, h = self.fig.get_size_inches()
+        _log.debug('frame size in pixels is %s x %s', *self.frame_size)
+        return w, h
+
+    def setup(self, fig, outfile, dpi=None):
+        # docstring inherited
+        super().setup(fig, outfile, dpi=dpi)
+        self._w, self._h = self._adjust_frame_size()
+        # Run here so that grab_frame() can write the data to a pipe. This
+        # eliminates the need for temp files.
+        self._run()
+
+    def _run(self):
+        # Uses subprocess to call the program for assembling frames into a
+        # movie file.  *args* returns the sequence of command line arguments
+        # from a few configuration options.
+        command = self._args()
+        _log.info('MovieWriter._run: running command: %s',
+                  cbook._pformat_subprocess(command))
+        PIPE = subprocess.PIPE
+        self._proc = subprocess.Popen(
+            command, stdin=PIPE, stdout=PIPE, stderr=PIPE,
+            creationflags=subprocess_creation_flags)
+
+    def finish(self):
+        """Finish any processing for writing the movie."""
+        out, err = self._proc.communicate()
+        # Use the encoding/errors that universal_newlines would use.
+        out = TextIOWrapper(BytesIO(out)).read()
+        err = TextIOWrapper(BytesIO(err)).read()
+        if out:
+            _log.log(
+                logging.WARNING if self._proc.returncode else logging.DEBUG,
+                "MovieWriter stdout:\n%s", out)
+        if err:
+            _log.log(
+                logging.WARNING if self._proc.returncode else logging.DEBUG,
+                "MovieWriter stderr:\n%s", err)
+        if self._proc.returncode:
+            raise subprocess.CalledProcessError(
+                self._proc.returncode, self._proc.args, out, err)
+
+    def grab_frame(self, **savefig_kwargs):
+        # docstring inherited
+        _validate_grabframe_kwargs(savefig_kwargs)
+        _log.debug('MovieWriter.grab_frame: Grabbing frame.')
+        # Readjust the figure size in case it has been changed by the user.
+        # All frames must have the same size to save the movie correctly.
+        self.fig.set_size_inches(self._w, self._h)
+        # Save the figure data to the sink, using the frame format and dpi.
+        self.fig.savefig(self._proc.stdin, format=self.frame_format,
+                         dpi=self.dpi, **savefig_kwargs)
+
+    def _args(self):
+        """Assemble list of encoder-specific command-line arguments."""
+        return NotImplementedError("args needs to be implemented by subclass.")
+
+    @classmethod
+    def bin_path(cls):
+        """
+        Return the binary path to the commandline tool used by a specific
+        subclass. This is a class method so that the tool can be looked for
+        before making a particular MovieWriter subclass available.
+        """
+        return str(mpl.rcParams[cls._exec_key])
+
+    @classmethod
+    def isAvailable(cls):
+        """Return whether a MovieWriter subclass is actually available."""
+        return shutil.which(cls.bin_path()) is not None
+
+
+class FileMovieWriter(MovieWriter):
+    """
+    `MovieWriter` for writing to individual files and stitching at the end.
+
+    This must be sub-classed to be useful.
+    """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.frame_format = mpl.rcParams['animation.frame_format']
+
+    def setup(self, fig, outfile, dpi=None, frame_prefix=None):
+        """
+        Setup for writing the movie file.
+
+        Parameters
+        ----------
+        fig : `~matplotlib.figure.Figure`
+            The figure to grab the rendered frames from.
+        outfile : str
+            The filename of the resulting movie file.
+        dpi : float, default: ``fig.dpi``
+            The dpi of the output file. This, with the figure size,
+            controls the size in pixels of the resulting movie file.
+        frame_prefix : str, optional
+            The filename prefix to use for temporary files.  If *None* (the
+            default), files are written to a temporary directory which is
+            deleted by `finish`; if not *None*, no temporary files are
+            deleted.
+        """
+        # Check that path is valid
+        Path(outfile).parent.resolve(strict=True)
+        self.fig = fig
+        self.outfile = outfile
+        if dpi is None:
+            dpi = self.fig.dpi
+        self.dpi = dpi
+        self._adjust_frame_size()
+
+        if frame_prefix is None:
+            self._tmpdir = TemporaryDirectory()
+            self.temp_prefix = str(Path(self._tmpdir.name, 'tmp'))
+        else:
+            self._tmpdir = None
+            self.temp_prefix = frame_prefix
+        self._frame_counter = 0  # used for generating sequential file names
+        self._temp_paths = list()
+        self.fname_format_str = '%s%%07d.%s'
+
+    def __del__(self):
+        if hasattr(self, '_tmpdir') and self._tmpdir:
+            self._tmpdir.cleanup()
+
+    @property
+    def frame_format(self):
+        """
+        Format (png, jpeg, etc.) to use for saving the frames, which can be
+        decided by the individual subclasses.
+        """
+        return self._frame_format
+
+    @frame_format.setter
+    def frame_format(self, frame_format):
+        if frame_format in self.supported_formats:
+            self._frame_format = frame_format
+        else:
+            _api.warn_external(
+                f"Ignoring file format {frame_format!r} which is not "
+                f"supported by {type(self).__name__}; using "
+                f"{self.supported_formats[0]} instead.")
+            self._frame_format = self.supported_formats[0]
+
+    def _base_temp_name(self):
+        # Generates a template name (without number) given the frame format
+        # for extension and the prefix.
+        return self.fname_format_str % (self.temp_prefix, self.frame_format)
+
+    def grab_frame(self, **savefig_kwargs):
+        # docstring inherited
+        # Creates a filename for saving using basename and counter.
+        _validate_grabframe_kwargs(savefig_kwargs)
+        path = Path(self._base_temp_name() % self._frame_counter)
+        self._temp_paths.append(path)  # Record the filename for later use.
+        self._frame_counter += 1  # Ensures each created name is unique.
+        _log.debug('FileMovieWriter.grab_frame: Grabbing frame %d to path=%s',
+                   self._frame_counter, path)
+        with open(path, 'wb') as sink:  # Save figure to the sink.
+            self.fig.savefig(sink, format=self.frame_format, dpi=self.dpi,
+                             **savefig_kwargs)
+
+    def finish(self):
+        # Call run here now that all frame grabbing is done. All temp files
+        # are available to be assembled.
+        try:
+            self._run()
+            super().finish()
+        finally:
+            if self._tmpdir:
+                _log.debug(
+                    'MovieWriter: clearing temporary path=%s', self._tmpdir
+                )
+                self._tmpdir.cleanup()
+
+
+@writers.register('pillow')
+class PillowWriter(AbstractMovieWriter):
+    def _supports_transparency(self):
+        return True
+
+    @classmethod
+    def isAvailable(cls):
+        return True
+
+    def setup(self, fig, outfile, dpi=None):
+        super().setup(fig, outfile, dpi=dpi)
+        self._frames = []
+
+    def grab_frame(self, **savefig_kwargs):
+        _validate_grabframe_kwargs(savefig_kwargs)
+        buf = BytesIO()
+        self.fig.savefig(
+            buf, **{**savefig_kwargs, "format": "rgba", "dpi": self.dpi})
+        im = Image.frombuffer(
+            "RGBA", self.frame_size, buf.getbuffer(), "raw", "RGBA", 0, 1)
+        if im.getextrema()[3][0] < 255:
+            # This frame has transparency, so we'll just add it as is.
+            self._frames.append(im)
+        else:
+            # Without transparency, we switch to RGB mode, which converts to P mode a
+            # little better if needed (specifically, this helps with GIF output.)
+            self._frames.append(im.convert("RGB"))
+
+    def finish(self):
+        self._frames[0].save(
+            self.outfile, save_all=True, append_images=self._frames[1:],
+            duration=int(1000 / self.fps), loop=0)
+
+
+# Base class of ffmpeg information. Has the config keys and the common set
+# of arguments that controls the *output* side of things.
+class FFMpegBase:
+    """
+    Mixin class for FFMpeg output.
+
+    This is a base class for the concrete `FFMpegWriter` and `FFMpegFileWriter`
+    classes.
+    """
+
+    _exec_key = 'animation.ffmpeg_path'
+    _args_key = 'animation.ffmpeg_args'
+
+    def _supports_transparency(self):
+        suffix = Path(self.outfile).suffix
+        if suffix in {'.apng', '.avif', '.gif', '.webm', '.webp'}:
+            return True
+        # This list was found by going through `ffmpeg -codecs` for video encoders,
+        # running them with _support_transparency() forced to True, and checking that
+        # the "Pixel format" in Kdenlive included alpha. Note this is not a guarantee
+        # that transparency will work; you may also need to pass `-pix_fmt`, but we
+        # trust the user has done so if they are asking for these formats.
+        return self.codec in {
+            'apng', 'avrp', 'bmp', 'cfhd', 'dpx', 'ffv1', 'ffvhuff', 'gif', 'huffyuv',
+            'jpeg2000', 'ljpeg', 'png', 'prores', 'prores_aw', 'prores_ks', 'qtrle',
+            'rawvideo', 'targa', 'tiff', 'utvideo', 'v408', }
+
+    @property
+    def output_args(self):
+        args = []
+        suffix = Path(self.outfile).suffix
+        if suffix in {'.apng', '.avif', '.gif', '.webm', '.webp'}:
+            self.codec = suffix[1:]
+        else:
+            args.extend(['-vcodec', self.codec])
+        extra_args = (self.extra_args if self.extra_args is not None
+                      else mpl.rcParams[self._args_key])
+        # For h264, the default format is yuv444p, which is not compatible
+        # with quicktime (and others). Specifying yuv420p fixes playback on
+        # iOS, as well as HTML5 video in firefox and safari (on both Windows and
+        # macOS). Also fixes internet explorer. This is as of 2015/10/29.
+        if self.codec == 'h264' and '-pix_fmt' not in extra_args:
+            args.extend(['-pix_fmt', 'yuv420p'])
+        # For GIF, we're telling FFmpeg to split the video stream, to generate
+        # a palette, and then use it for encoding.
+        elif self.codec == 'gif' and '-filter_complex' not in extra_args:
+            args.extend(['-filter_complex',
+                         'split [a][b];[a] palettegen [p];[b][p] paletteuse'])
+        # For AVIF, we're telling FFmpeg to split the video stream, extract the alpha,
+        # in order to place it in a secondary stream, as needed by AVIF-in-FFmpeg.
+        elif self.codec == 'avif' and '-filter_complex' not in extra_args:
+            args.extend(['-filter_complex',
+                         'split [rgb][rgba]; [rgba] alphaextract [alpha]',
+                         '-map', '[rgb]', '-map', '[alpha]'])
+        if self.bitrate > 0:
+            args.extend(['-b', '%dk' % self.bitrate])  # %dk: bitrate in kbps.
+        for k, v in self.metadata.items():
+            args.extend(['-metadata', f'{k}={v}'])
+        args.extend(extra_args)
+
+        return args + ['-y', self.outfile]
+
+
+# Combine FFMpeg options with pipe-based writing
+@writers.register('ffmpeg')
+class FFMpegWriter(FFMpegBase, MovieWriter):
+    """
+    Pipe-based ffmpeg writer.
+
+    Frames are streamed directly to ffmpeg via a pipe and written in a single pass.
+
+    This effectively works as a slideshow input to ffmpeg with the fps passed as
+    ``-framerate``, so see also `their notes on frame rates`_ for further details.
+
+    .. _their notes on frame rates: https://trac.ffmpeg.org/wiki/Slideshow#Framerates
+    """
+    def _args(self):
+        # Returns the command line parameters for subprocess to use
+        # ffmpeg to create a movie using a pipe.
+        args = [self.bin_path(), '-f', 'rawvideo', '-vcodec', 'rawvideo',
+                '-s', '%dx%d' % self.frame_size, '-pix_fmt', self.frame_format,
+                '-framerate', str(self.fps)]
+        # Logging is quieted because subprocess.PIPE has limited buffer size.
+        # If you have a lot of frames in your animation and set logging to
+        # DEBUG, you will have a buffer overrun.
+        if _log.getEffectiveLevel() > logging.DEBUG:
+            args += ['-loglevel', 'error']
+        args += ['-i', 'pipe:'] + self.output_args
+        return args
+
+
+# Combine FFMpeg options with temp file-based writing
+@writers.register('ffmpeg_file')
+class FFMpegFileWriter(FFMpegBase, FileMovieWriter):
+    """
+    File-based ffmpeg writer.
+
+    Frames are written to temporary files on disk and then stitched together at the end.
+
+    This effectively works as a slideshow input to ffmpeg with the fps passed as
+    ``-framerate``, so see also `their notes on frame rates`_ for further details.
+
+    .. _their notes on frame rates: https://trac.ffmpeg.org/wiki/Slideshow#Framerates
+    """
+    supported_formats = ['png', 'jpeg', 'tiff', 'raw', 'rgba']
+
+    def _args(self):
+        # Returns the command line parameters for subprocess to use
+        # ffmpeg to create a movie using a collection of temp images
+        args = []
+        # For raw frames, we need to explicitly tell ffmpeg the metadata.
+        if self.frame_format in {'raw', 'rgba'}:
+            args += [
+                '-f', 'image2', '-vcodec', 'rawvideo',
+                '-video_size', '%dx%d' % self.frame_size,
+                '-pixel_format', 'rgba',
+            ]
+        args += ['-framerate', str(self.fps), '-i', self._base_temp_name()]
+        if not self._tmpdir:
+            args += ['-frames:v', str(self._frame_counter)]
+        # Logging is quieted because subprocess.PIPE has limited buffer size.
+        # If you have a lot of frames in your animation and set logging to
+        # DEBUG, you will have a buffer overrun.
+        if _log.getEffectiveLevel() > logging.DEBUG:
+            args += ['-loglevel', 'error']
+        return [self.bin_path(), *args, *self.output_args]
+
+
+# Base class for animated GIFs with ImageMagick
+class ImageMagickBase:
+    """
+    Mixin class for ImageMagick output.
+
+    This is a base class for the concrete `ImageMagickWriter` and
+    `ImageMagickFileWriter` classes, which define an ``input_names`` attribute
+    (or property) specifying the input names passed to ImageMagick.
+    """
+
+    _exec_key = 'animation.convert_path'
+    _args_key = 'animation.convert_args'
+
+    def _supports_transparency(self):
+        suffix = Path(self.outfile).suffix
+        return suffix in {'.apng', '.avif', '.gif', '.webm', '.webp'}
+
+    def _args(self):
+        # ImageMagick does not recognize "raw".
+        fmt = "rgba" if self.frame_format == "raw" else self.frame_format
+        extra_args = (self.extra_args if self.extra_args is not None
+                      else mpl.rcParams[self._args_key])
+        return [
+            self.bin_path(),
+            "-size", "%ix%i" % self.frame_size,
+            "-depth", "8",
+            "-delay", str(100 / self.fps),
+            "-loop", "0",
+            f"{fmt}:{self.input_names}",
+            *extra_args,
+            self.outfile,
+        ]
+
+    @classmethod
+    def bin_path(cls):
+        binpath = super().bin_path()
+        if binpath == 'convert':
+            binpath = mpl._get_executable_info('magick').executable
+        return binpath
+
+    @classmethod
+    def isAvailable(cls):
+        try:
+            return super().isAvailable()
+        except mpl.ExecutableNotFoundError as _enf:
+            # May be raised by get_executable_info.
+            _log.debug('ImageMagick unavailable due to: %s', _enf)
+            return False
+
+
+# Combine ImageMagick options with pipe-based writing
+@writers.register('imagemagick')
+class ImageMagickWriter(ImageMagickBase, MovieWriter):
+    """
+    Pipe-based animated gif writer.
+
+    Frames are streamed directly to ImageMagick via a pipe and written
+    in a single pass.
+    """
+
+    input_names = "-"  # stdin
+
+
+# Combine ImageMagick options with temp file-based writing
+@writers.register('imagemagick_file')
+class ImageMagickFileWriter(ImageMagickBase, FileMovieWriter):
+    """
+    File-based animated gif writer.
+
+    Frames are written to temporary files on disk and then stitched
+    together at the end.
+    """
+
+    supported_formats = ['png', 'jpeg', 'tiff', 'raw', 'rgba']
+    input_names = property(
+        lambda self: f'{self.temp_prefix}*.{self.frame_format}')
+
+
+# Taken directly from jakevdp's JSAnimation package at
+# http://github.com/jakevdp/JSAnimation
+def _included_frames(frame_count, frame_format, frame_dir):
+    return INCLUDED_FRAMES.format(Nframes=frame_count,
+                                  frame_dir=frame_dir,
+                                  frame_format=frame_format)
+
+
+def _embedded_frames(frame_list, frame_format):
+    """frame_list should be a list of base64-encoded png files"""
+    if frame_format == 'svg':
+        # Fix MIME type for svg
+        frame_format = 'svg+xml'
+    template = '  frames[{0}] = "data:image/{1};base64,{2}"\n'
+    return "\n" + "".join(
+        template.format(i, frame_format, frame_data.replace('\n', '\\\n'))
+        for i, frame_data in enumerate(frame_list))
+
+
+@writers.register('html')
+class HTMLWriter(FileMovieWriter):
+    """Writer for JavaScript-based HTML movies."""
+
+    supported_formats = ['png', 'jpeg', 'tiff', 'svg']
+
+    @classmethod
+    def isAvailable(cls):
+        return True
+
+    def __init__(self, fps=30, codec=None, bitrate=None, extra_args=None,
+                 metadata=None, embed_frames=False, default_mode='loop',
+                 embed_limit=None):
+
+        if extra_args:
+            _log.warning("HTMLWriter ignores 'extra_args'")
+        extra_args = ()  # Don't lookup nonexistent rcParam[args_key].
+        self.embed_frames = embed_frames
+        self.default_mode = default_mode.lower()
+        _api.check_in_list(['loop', 'once', 'reflect'],
+                           default_mode=self.default_mode)
+
+        # Save embed limit, which is given in MB
+        self._bytes_limit = mpl._val_or_rc(embed_limit, 'animation.embed_limit')
+        # Convert from MB to bytes
+        self._bytes_limit *= 1024 * 1024
+
+        super().__init__(fps, codec, bitrate, extra_args, metadata)
+
+    def setup(self, fig, outfile, dpi=None, frame_dir=None):
+        outfile = Path(outfile)
+        _api.check_in_list(['.html', '.htm'], outfile_extension=outfile.suffix)
+
+        self._saved_frames = []
+        self._total_bytes = 0
+        self._hit_limit = False
+
+        if not self.embed_frames:
+            if frame_dir is None:
+                frame_dir = outfile.with_name(outfile.stem + '_frames')
+            frame_dir.mkdir(parents=True, exist_ok=True)
+            frame_prefix = frame_dir / 'frame'
+        else:
+            frame_prefix = None
+
+        super().setup(fig, outfile, dpi, frame_prefix)
+        self._clear_temp = False
+
+    def grab_frame(self, **savefig_kwargs):
+        _validate_grabframe_kwargs(savefig_kwargs)
+        if self.embed_frames:
+            # Just stop processing if we hit the limit
+            if self._hit_limit:
+                return
+            f = BytesIO()
+            self.fig.savefig(f, format=self.frame_format,
+                             dpi=self.dpi, **savefig_kwargs)
+            imgdata64 = base64.encodebytes(f.getvalue()).decode('ascii')
+            self._total_bytes += len(imgdata64)
+            if self._total_bytes >= self._bytes_limit:
+                _log.warning(
+                    "Animation size has reached %s bytes, exceeding the limit "
+                    "of %s. If you're sure you want a larger animation "
+                    "embedded, set the animation.embed_limit rc parameter to "
+                    "a larger value (in MB). This and further frames will be "
+                    "dropped.", self._total_bytes, self._bytes_limit)
+                self._hit_limit = True
+            else:
+                self._saved_frames.append(imgdata64)
+        else:
+            return super().grab_frame(**savefig_kwargs)
+
+    def finish(self):
+        # save the frames to an html file
+        if self.embed_frames:
+            fill_frames = _embedded_frames(self._saved_frames,
+                                           self.frame_format)
+            frame_count = len(self._saved_frames)
+        else:
+            # temp names is filled by FileMovieWriter
+            frame_count = len(self._temp_paths)
+            fill_frames = _included_frames(
+                frame_count, self.frame_format,
+                self._temp_paths[0].parent.relative_to(self.outfile.parent))
+        mode_dict = dict(once_checked='',
+                         loop_checked='',
+                         reflect_checked='')
+        mode_dict[self.default_mode + '_checked'] = 'checked'
+
+        interval = 1000 // self.fps
+
+        with open(self.outfile, 'w') as of:
+            of.write(JS_INCLUDE + STYLE_INCLUDE)
+            of.write(DISPLAY_TEMPLATE.format(id=uuid.uuid4().hex,
+                                             Nframes=frame_count,
+                                             fill_frames=fill_frames,
+                                             interval=interval,
+                                             **mode_dict))
+
+        # Duplicate the temporary file clean up logic from
+        # FileMovieWriter.finish.  We cannot call the inherited version of
+        # finish because it assumes that there is a subprocess that we either
+        # need to call to merge many frames together or that there is a
+        # subprocess call that we need to clean up.
+        if self._tmpdir:
+            _log.debug('MovieWriter: clearing temporary path=%s', self._tmpdir)
+            self._tmpdir.cleanup()
+
+
+class Animation:
+    """
+    A base class for Animations.
+
+    This class is not usable as is, and should be subclassed to provide needed
+    behavior.
+
+    .. note::
+
+        You must store the created Animation in a variable that lives as long
+        as the animation should run. Otherwise, the Animation object will be
+        garbage-collected and the animation stops.
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        The figure object used to get needed events, such as draw or resize.
+
+    event_source : object, optional
+        A class that can run a callback when desired events
+        are generated, as well as be stopped and started.
+
+        Examples include timers (see `TimedAnimation`) and file
+        system notifications.
+
+    blit : bool, default: False
+        Whether blitting is used to optimize drawing.  If the backend does not
+        support blitting, then this parameter has no effect.
+
+    See Also
+    --------
+    FuncAnimation,  ArtistAnimation
+    """
+
+    def __init__(self, fig, event_source=None, blit=False):
+        self._draw_was_started = False
+
+        self._fig = fig
+        # Disables blitting for backends that don't support it.  This
+        # allows users to request it if available, but still have a
+        # fallback that works if it is not.
+        self._blit = blit and fig.canvas.supports_blit
+
+        # These are the basics of the animation.  The frame sequence represents
+        # information for each frame of the animation and depends on how the
+        # drawing is handled by the subclasses. The event source fires events
+        # that cause the frame sequence to be iterated.
+        self.frame_seq = self.new_frame_seq()
+        self.event_source = event_source
+
+        # Instead of starting the event source now, we connect to the figure's
+        # draw_event, so that we only start once the figure has been drawn.
+        self._first_draw_id = fig.canvas.mpl_connect('draw_event', self._start)
+
+        # Connect to the figure's close_event so that we don't continue to
+        # fire events and try to draw to a deleted figure.
+        self._close_id = self._fig.canvas.mpl_connect('close_event',
+                                                      self._stop)
+        if self._blit:
+            self._setup_blit()
+
+    def __del__(self):
+        if not getattr(self, '_draw_was_started', True):
+            warnings.warn(
+                'Animation was deleted without rendering anything. This is '
+                'most likely not intended. To prevent deletion, assign the '
+                'Animation to a variable, e.g. `anim`, that exists until you '
+                'output the Animation using `plt.show()` or '
+                '`anim.save()`.'
+            )
+
+    def _start(self, *args):
+        """
+        Starts interactive animation. Adds the draw frame command to the GUI
+        handler, calls show to start the event loop.
+        """
+        # Do not start the event source if saving() it.
+        if self._fig.canvas.is_saving():
+            return
+        # First disconnect our draw event handler
+        self._fig.canvas.mpl_disconnect(self._first_draw_id)
+
+        # Now do any initial draw
+        self._init_draw()
+
+        # Add our callback for stepping the animation and
+        # actually start the event_source.
+        self.event_source.add_callback(self._step)
+        self.event_source.start()
+
+    def _stop(self, *args):
+        # On stop we disconnect all of our events.
+        if self._blit:
+            self._fig.canvas.mpl_disconnect(self._resize_id)
+        self._fig.canvas.mpl_disconnect(self._close_id)
+        self.event_source.remove_callback(self._step)
+        self.event_source = None
+
+    def save(self, filename, writer=None, fps=None, dpi=None, codec=None,
+             bitrate=None, extra_args=None, metadata=None, extra_anim=None,
+             savefig_kwargs=None, *, progress_callback=None):
+        """
+        Save the animation as a movie file by drawing every frame.
+
+        Parameters
+        ----------
+        filename : str
+            The output filename, e.g., :file:`mymovie.mp4`.
+
+        writer : `MovieWriter` or str, default: :rc:`animation.writer`
+            A `MovieWriter` instance to use or a key that identifies a
+            class to use, such as 'ffmpeg'.
+
+        fps : int, optional
+            Movie frame rate (per second).  If not set, the frame rate from the
+            animation's frame interval.
+
+        dpi : float, default: :rc:`savefig.dpi`
+            Controls the dots per inch for the movie frames.  Together with
+            the figure's size in inches, this controls the size of the movie.
+
+        codec : str, default: :rc:`animation.codec`.
+            The video codec to use.  Not all codecs are supported by a given
+            `MovieWriter`.
+
+        bitrate : int, default: :rc:`animation.bitrate`
+            The bitrate of the movie, in kilobits per second.  Higher values
+            means higher quality movies, but increase the file size.  A value
+            of -1 lets the underlying movie encoder select the bitrate.
+
+        extra_args : list of str or None, optional
+            Extra command-line arguments passed to the underlying movie encoder. These
+            arguments are passed last to the encoder, just before the output filename.
+            The default, None, means to use :rc:`animation.[name-of-encoder]_args` for
+            the builtin writers.
+
+        metadata : dict[str, str], default: {}
+            Dictionary of keys and values for metadata to include in
+            the output file. Some keys that may be of use include:
+            title, artist, genre, subject, copyright, srcform, comment.
+
+        extra_anim : list, default: []
+            Additional `Animation` objects that should be included
+            in the saved movie file. These need to be from the same
+            `.Figure` instance. Also, animation frames will
+            just be simply combined, so there should be a 1:1 correspondence
+            between the frames from the different animations.
+
+        savefig_kwargs : dict, default: {}
+            Keyword arguments passed to each `~.Figure.savefig` call used to
+            save the individual frames.
+
+        progress_callback : function, optional
+            A callback function that will be called for every frame to notify
+            the saving progress. It must have the signature ::
+
+                def func(current_frame: int, total_frames: int) -> Any
+
+            where *current_frame* is the current frame number and *total_frames* is the
+            total number of frames to be saved. *total_frames* is set to None, if the
+            total number of frames cannot be determined. Return values may exist but are
+            ignored.
+
+            Example code to write the progress to stdout::
+
+                progress_callback = lambda i, n: print(f'Saving frame {i}/{n}')
+
+        Notes
+        -----
+        *fps*, *codec*, *bitrate*, *extra_args* and *metadata* are used to
+        construct a `.MovieWriter` instance and can only be passed if
+        *writer* is a string.  If they are passed as non-*None* and *writer*
+        is a `.MovieWriter`, a `RuntimeError` will be raised.
+        """
+
+        all_anim = [self]
+        if extra_anim is not None:
+            all_anim.extend(anim for anim in extra_anim
+                            if anim._fig is self._fig)
+
+        # Disable "Animation was deleted without rendering" warning.
+        for anim in all_anim:
+            anim._draw_was_started = True
+
+        if writer is None:
+            writer = mpl.rcParams['animation.writer']
+        elif (not isinstance(writer, str) and
+              any(arg is not None
+                  for arg in (fps, codec, bitrate, extra_args, metadata))):
+            raise RuntimeError('Passing in values for arguments '
+                               'fps, codec, bitrate, extra_args, or metadata '
+                               'is not supported when writer is an existing '
+                               'MovieWriter instance. These should instead be '
+                               'passed as arguments when creating the '
+                               'MovieWriter instance.')
+
+        if savefig_kwargs is None:
+            savefig_kwargs = {}
+        else:
+            # we are going to mutate this below
+            savefig_kwargs = dict(savefig_kwargs)
+
+        if fps is None and hasattr(self, '_interval'):
+            # Convert interval in ms to frames per second
+            fps = 1000. / self._interval
+
+        # Reuse the savefig DPI for ours if none is given.
+        dpi = mpl._val_or_rc(dpi, 'savefig.dpi')
+        if dpi == 'figure':
+            dpi = self._fig.dpi
+
+        writer_kwargs = {}
+        if codec is not None:
+            writer_kwargs['codec'] = codec
+        if bitrate is not None:
+            writer_kwargs['bitrate'] = bitrate
+        if extra_args is not None:
+            writer_kwargs['extra_args'] = extra_args
+        if metadata is not None:
+            writer_kwargs['metadata'] = metadata
+
+        # If we have the name of a writer, instantiate an instance of the
+        # registered class.
+        if isinstance(writer, str):
+            try:
+                writer_cls = writers[writer]
+            except RuntimeError:  # Raised if not available.
+                writer_cls = PillowWriter  # Always available.
+                _log.warning("MovieWriter %s unavailable; using Pillow "
+                             "instead.", writer)
+            writer = writer_cls(fps, **writer_kwargs)
+        _log.info('Animation.save using %s', type(writer))
+
+        if 'bbox_inches' in savefig_kwargs:
+            _log.warning("Warning: discarding the 'bbox_inches' argument in "
+                         "'savefig_kwargs' as it may cause frame size "
+                         "to vary, which is inappropriate for animation.")
+            savefig_kwargs.pop('bbox_inches')
+
+        # Create a new sequence of frames for saved data. This is different
+        # from new_frame_seq() to give the ability to save 'live' generated
+        # frame information to be saved later.
+        # TODO: Right now, after closing the figure, saving a movie won't work
+        # since GUI widgets are gone. Either need to remove extra code to
+        # allow for this non-existent use case or find a way to make it work.
+
+        def _pre_composite_to_white(color):
+            r, g, b, a = mcolors.to_rgba(color)
+            return a * np.array([r, g, b]) + 1 - a
+
+        # canvas._is_saving = True makes the draw_event animation-starting
+        # callback a no-op; canvas.manager = None prevents resizing the GUI
+        # widget (both are likewise done in savefig()).
+        with (writer.saving(self._fig, filename, dpi),
+              cbook._setattr_cm(self._fig.canvas, _is_saving=True, manager=None)):
+            if not writer._supports_transparency():
+                facecolor = savefig_kwargs.get('facecolor',
+                                               mpl.rcParams['savefig.facecolor'])
+                if facecolor == 'auto':
+                    facecolor = self._fig.get_facecolor()
+                savefig_kwargs['facecolor'] = _pre_composite_to_white(facecolor)
+                savefig_kwargs['transparent'] = False   # just to be safe!
+
+            for anim in all_anim:
+                anim._init_draw()  # Clear the initial frame
+            frame_number = 0
+            # TODO: Currently only FuncAnimation has a save_count
+            #       attribute. Can we generalize this to all Animations?
+            save_count_list = [getattr(a, '_save_count', None)
+                               for a in all_anim]
+            if None in save_count_list:
+                total_frames = None
+            else:
+                total_frames = sum(save_count_list)
+            for data in zip(*[a.new_saved_frame_seq() for a in all_anim]):
+                for anim, d in zip(all_anim, data):
+                    # TODO: See if turning off blit is really necessary
+                    anim._draw_next_frame(d, blit=False)
+                    if progress_callback is not None:
+                        progress_callback(frame_number, total_frames)
+                        frame_number += 1
+                writer.grab_frame(**savefig_kwargs)
+
+    def _step(self, *args):
+        """
+        Handler for getting events. By default, gets the next frame in the
+        sequence and hands the data off to be drawn.
+        """
+        # Returns True to indicate that the event source should continue to
+        # call _step, until the frame sequence reaches the end of iteration,
+        # at which point False will be returned.
+        try:
+            framedata = next(self.frame_seq)
+            self._draw_next_frame(framedata, self._blit)
+            return True
+        except StopIteration:
+            return False
+
+    def new_frame_seq(self):
+        """Return a new sequence of frame information."""
+        # Default implementation is just an iterator over self._framedata
+        return iter(self._framedata)
+
+    def new_saved_frame_seq(self):
+        """Return a new sequence of saved/cached frame information."""
+        # Default is the same as the regular frame sequence
+        return self.new_frame_seq()
+
+    def _draw_next_frame(self, framedata, blit):
+        # Breaks down the drawing of the next frame into steps of pre- and
+        # post- draw, as well as the drawing of the frame itself.
+        self._pre_draw(framedata, blit)
+        self._draw_frame(framedata)
+        self._post_draw(framedata, blit)
+
+    def _init_draw(self):
+        # Initial draw to clear the frame. Also used by the blitting code
+        # when a clean base is required.
+        self._draw_was_started = True
+
+    def _pre_draw(self, framedata, blit):
+        # Perform any cleaning or whatnot before the drawing of the frame.
+        # This default implementation allows blit to clear the frame.
+        if blit:
+            self._blit_clear(self._drawn_artists)
+
+    def _draw_frame(self, framedata):
+        # Performs actual drawing of the frame.
+        raise NotImplementedError('Needs to be implemented by subclasses to'
+                                  ' actually make an animation.')
+
+    def _post_draw(self, framedata, blit):
+        # After the frame is rendered, this handles the actual flushing of
+        # the draw, which can be a direct draw_idle() or make use of the
+        # blitting.
+        if blit and self._drawn_artists:
+            self._blit_draw(self._drawn_artists)
+        else:
+            self._fig.canvas.draw_idle()
+
+    # The rest of the code in this class is to facilitate easy blitting
+    def _blit_draw(self, artists):
+        # Handles blitted drawing, which renders only the artists given instead
+        # of the entire figure.
+        updated_ax = {a.axes for a in artists}
+        # Enumerate artists to cache Axes backgrounds. We do not draw
+        # artists yet to not cache foreground from plots with shared Axes
+        for ax in updated_ax:
+            # If we haven't cached the background for the current view of this
+            # Axes object, do so now. This might not always be reliable, but
+            # it's an attempt to automate the process.
+            cur_view = ax._get_view()
+            view, bg = self._blit_cache.get(ax, (object(), None))
+            if cur_view != view:
+                self._blit_cache[ax] = (
+                    cur_view, ax.figure.canvas.copy_from_bbox(ax.bbox))
+        # Make a separate pass to draw foreground.
+        for a in artists:
+            a.axes.draw_artist(a)
+        # After rendering all the needed artists, blit each Axes individually.
+        for ax in updated_ax:
+            ax.figure.canvas.blit(ax.bbox)
+
+    def _blit_clear(self, artists):
+        # Get a list of the Axes that need clearing from the artists that
+        # have been drawn. Grab the appropriate saved background from the
+        # cache and restore.
+        axes = {a.axes for a in artists}
+        for ax in axes:
+            try:
+                view, bg = self._blit_cache[ax]
+            except KeyError:
+                continue
+            if ax._get_view() == view:
+                ax.figure.canvas.restore_region(bg)
+            else:
+                self._blit_cache.pop(ax)
+
+    def _setup_blit(self):
+        # Setting up the blit requires: a cache of the background for the Axes
+        self._blit_cache = dict()
+        self._drawn_artists = []
+        # _post_draw needs to be called first to initialize the renderer
+        self._post_draw(None, self._blit)
+        # Then we need to clear the Frame for the initial draw
+        # This is typically handled in _on_resize because QT and Tk
+        # emit a resize event on launch, but the macosx backend does not,
+        # thus we force it here for everyone for consistency
+        self._init_draw()
+        # Connect to future resize events
+        self._resize_id = self._fig.canvas.mpl_connect('resize_event',
+                                                       self._on_resize)
+
+    def _on_resize(self, event):
+        # On resize, we need to disable the resize event handling so we don't
+        # get too many events. Also stop the animation events, so that
+        # we're paused. Reset the cache and re-init. Set up an event handler
+        # to catch once the draw has actually taken place.
+        self._fig.canvas.mpl_disconnect(self._resize_id)
+        self.event_source.stop()
+        self._blit_cache.clear()
+        self._init_draw()
+        self._resize_id = self._fig.canvas.mpl_connect('draw_event',
+                                                       self._end_redraw)
+
+    def _end_redraw(self, event):
+        # Now that the redraw has happened, do the post draw flushing and
+        # blit handling. Then re-enable all of the original events.
+        self._post_draw(None, False)
+        self.event_source.start()
+        self._fig.canvas.mpl_disconnect(self._resize_id)
+        self._resize_id = self._fig.canvas.mpl_connect('resize_event',
+                                                       self._on_resize)
+
+    def to_html5_video(self, embed_limit=None):
+        """
+        Convert the animation to an HTML5 ``<video>`` tag.
+
+        This saves the animation as an h264 video, encoded in base64
+        directly into the HTML5 video tag. This respects :rc:`animation.writer`
+        and :rc:`animation.bitrate`. This also makes use of the
+        *interval* to control the speed, and uses the *repeat*
+        parameter to decide whether to loop.
+
+        Parameters
+        ----------
+        embed_limit : float, optional
+            Limit, in MB, of the returned animation. No animation is created
+            if the limit is exceeded.
+            Defaults to :rc:`animation.embed_limit` = 20.0.
+
+        Returns
+        -------
+        str
+            An HTML5 video tag with the animation embedded as base64 encoded
+            h264 video.
+            If the *embed_limit* is exceeded, this returns the string
+            "Video too large to embed."
+        """
+        VIDEO_TAG = r'''<video {size} {options}>
+  <source type="video/mp4" src="data:video/mp4;base64,{video}">
+  Your browser does not support the video tag.
+</video>'''
+        # Cache the rendering of the video as HTML
+        if not hasattr(self, '_base64_video'):
+            # Save embed limit, which is given in MB
+            embed_limit = mpl._val_or_rc(embed_limit, 'animation.embed_limit')
+
+            # Convert from MB to bytes
+            embed_limit *= 1024 * 1024
+
+            # Can't open a NamedTemporaryFile twice on Windows, so use a
+            # TemporaryDirectory instead.
+            with TemporaryDirectory() as tmpdir:
+                path = Path(tmpdir, "temp.m4v")
+                # We create a writer manually so that we can get the
+                # appropriate size for the tag
+                Writer = writers[mpl.rcParams['animation.writer']]
+                writer = Writer(codec='h264',
+                                bitrate=mpl.rcParams['animation.bitrate'],
+                                fps=1000. / self._interval)
+                self.save(str(path), writer=writer)
+                # Now open and base64 encode.
+                vid64 = base64.encodebytes(path.read_bytes())
+
+            vid_len = len(vid64)
+            if vid_len >= embed_limit:
+                _log.warning(
+                    "Animation movie is %s bytes, exceeding the limit of %s. "
+                    "If you're sure you want a large animation embedded, set "
+                    "the animation.embed_limit rc parameter to a larger value "
+                    "(in MB).", vid_len, embed_limit)
+            else:
+                self._base64_video = vid64.decode('ascii')
+                self._video_size = 'width="{}" height="{}"'.format(
+                        *writer.frame_size)
+
+        # If we exceeded the size, this attribute won't exist
+        if hasattr(self, '_base64_video'):
+            # Default HTML5 options are to autoplay and display video controls
+            options = ['controls', 'autoplay']
+
+            # If we're set to repeat, make it loop
+            if getattr(self, '_repeat', False):
+                options.append('loop')
+
+            return VIDEO_TAG.format(video=self._base64_video,
+                                    size=self._video_size,
+                                    options=' '.join(options))
+        else:
+            return 'Video too large to embed.'
+
+    def to_jshtml(self, fps=None, embed_frames=True, default_mode=None):
+        """
+        Generate HTML representation of the animation.
+
+        Parameters
+        ----------
+        fps : int, optional
+            Movie frame rate (per second). If not set, the frame rate from
+            the animation's frame interval.
+        embed_frames : bool, optional
+        default_mode : str, optional
+            What to do when the animation ends. Must be one of ``{'loop',
+            'once', 'reflect'}``. Defaults to ``'loop'`` if the *repeat*
+            parameter is True, otherwise ``'once'``.
+
+        Returns
+        -------
+        str
+            An HTML representation of the animation embedded as a js object as
+            produced with the `.HTMLWriter`.
+        """
+        if fps is None and hasattr(self, '_interval'):
+            # Convert interval in ms to frames per second
+            fps = 1000 / self._interval
+
+        # If we're not given a default mode, choose one base on the value of
+        # the _repeat attribute
+        if default_mode is None:
+            default_mode = 'loop' if getattr(self, '_repeat',
+                                             False) else 'once'
+
+        if not hasattr(self, "_html_representation"):
+            # Can't open a NamedTemporaryFile twice on Windows, so use a
+            # TemporaryDirectory instead.
+            with TemporaryDirectory() as tmpdir:
+                path = Path(tmpdir, "temp.html")
+                writer = HTMLWriter(fps=fps,
+                                    embed_frames=embed_frames,
+                                    default_mode=default_mode)
+                self.save(str(path), writer=writer)
+                self._html_representation = path.read_text()
+
+        return self._html_representation
+
+    def _repr_html_(self):
+        """IPython display hook for rendering."""
+        fmt = mpl.rcParams['animation.html']
+        if fmt == 'html5':
+            return self.to_html5_video()
+        elif fmt == 'jshtml':
+            return self.to_jshtml()
+
+    def pause(self):
+        """Pause the animation."""
+        self.event_source.stop()
+        if self._blit:
+            for artist in self._drawn_artists:
+                artist.set_animated(False)
+
+    def resume(self):
+        """Resume the animation."""
+        self.event_source.start()
+        if self._blit:
+            for artist in self._drawn_artists:
+                artist.set_animated(True)
+
+
+class TimedAnimation(Animation):
+    """
+    `Animation` subclass for time-based animation.
+
+    A new frame is drawn every *interval* milliseconds.
+
+    .. note::
+
+        You must store the created Animation in a variable that lives as long
+        as the animation should run. Otherwise, the Animation object will be
+        garbage-collected and the animation stops.
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        The figure object used to get needed events, such as draw or resize.
+    interval : int, default: 200
+        Delay between frames in milliseconds.
+    repeat_delay : int, default: 0
+        The delay in milliseconds between consecutive animation runs, if
+        *repeat* is True.
+    repeat : bool, default: True
+        Whether the animation repeats when the sequence of frames is completed.
+    blit : bool, default: False
+        Whether blitting is used to optimize drawing.
+    """
+    def __init__(self, fig, interval=200, repeat_delay=0, repeat=True,
+                 event_source=None, *args, **kwargs):
+        self._interval = interval
+        # Undocumented support for repeat_delay = None as backcompat.
+        self._repeat_delay = repeat_delay if repeat_delay is not None else 0
+        self._repeat = repeat
+        # If we're not given an event source, create a new timer. This permits
+        # sharing timers between animation objects for syncing animations.
+        if event_source is None:
+            event_source = fig.canvas.new_timer(interval=self._interval)
+        super().__init__(fig, event_source=event_source, *args, **kwargs)
+
+    def _step(self, *args):
+        """Handler for getting events."""
+        # Extends the _step() method for the Animation class.  If
+        # Animation._step signals that it reached the end and we want to
+        # repeat, we refresh the frame sequence and return True. If
+        # _repeat_delay is set, change the event_source's interval to our loop
+        # delay and set the callback to one which will then set the interval
+        # back.
+        still_going = super()._step(*args)
+        if not still_going:
+            if self._repeat:
+                # Restart the draw loop
+                self._init_draw()
+                self.frame_seq = self.new_frame_seq()
+                self.event_source.interval = self._repeat_delay
+                return True
+            else:
+                # We are done with the animation. Call pause to remove
+                # animated flags from artists that were using blitting
+                self.pause()
+                if self._blit:
+                    # Remove the resize callback if we were blitting
+                    self._fig.canvas.mpl_disconnect(self._resize_id)
+                self._fig.canvas.mpl_disconnect(self._close_id)
+                self.event_source = None
+                return False
+
+        self.event_source.interval = self._interval
+        return True
+
+
+class ArtistAnimation(TimedAnimation):
+    """
+    `TimedAnimation` subclass that creates an animation by using a fixed
+    set of `.Artist` objects.
+
+    Before creating an instance, all plotting should have taken place
+    and the relevant artists saved.
+
+    .. note::
+
+        You must store the created Animation in a variable that lives as long
+        as the animation should run. Otherwise, the Animation object will be
+        garbage-collected and the animation stops.
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        The figure object used to get needed events, such as draw or resize.
+    artists : list
+        Each list entry is a collection of `.Artist` objects that are made
+        visible on the corresponding frame.  Other artists are made invisible.
+    interval : int, default: 200
+        Delay between frames in milliseconds.
+    repeat_delay : int, default: 0
+        The delay in milliseconds between consecutive animation runs, if
+        *repeat* is True.
+    repeat : bool, default: True
+        Whether the animation repeats when the sequence of frames is completed.
+    blit : bool, default: False
+        Whether blitting is used to optimize drawing.
+    """
+
+    def __init__(self, fig, artists, *args, **kwargs):
+        # Internal list of artists drawn in the most recent frame.
+        self._drawn_artists = []
+
+        # Use the list of artists as the framedata, which will be iterated
+        # over by the machinery.
+        self._framedata = artists
+        super().__init__(fig, *args, **kwargs)
+
+    def _init_draw(self):
+        super()._init_draw()
+        # Make all the artists involved in *any* frame invisible
+        figs = set()
+        for f in self.new_frame_seq():
+            for artist in f:
+                artist.set_visible(False)
+                artist.set_animated(self._blit)
+                # Assemble a list of unique figures that need flushing
+                if artist.get_figure() not in figs:
+                    figs.add(artist.get_figure())
+
+        # Flush the needed figures
+        for fig in figs:
+            fig.canvas.draw_idle()
+
+    def _pre_draw(self, framedata, blit):
+        """Clears artists from the last frame."""
+        if blit:
+            # Let blit handle clearing
+            self._blit_clear(self._drawn_artists)
+        else:
+            # Otherwise, make all the artists from the previous frame invisible
+            for artist in self._drawn_artists:
+                artist.set_visible(False)
+
+    def _draw_frame(self, artists):
+        # Save the artists that were passed in as framedata for the other
+        # steps (esp. blitting) to use.
+        self._drawn_artists = artists
+
+        # Make all the artists from the current frame visible
+        for artist in artists:
+            artist.set_visible(True)
+
+
+class FuncAnimation(TimedAnimation):
+    """
+    `TimedAnimation` subclass that makes an animation by repeatedly calling
+    a function *func*.
+
+    .. note::
+
+        You must store the created Animation in a variable that lives as long
+        as the animation should run. Otherwise, the Animation object will be
+        garbage-collected and the animation stops.
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        The figure object used to get needed events, such as draw or resize.
+
+    func : callable
+        The function to call at each frame.  The first argument will
+        be the next value in *frames*.   Any additional positional
+        arguments can be supplied using `functools.partial` or via the *fargs*
+        parameter.
+
+        The required signature is::
+
+            def func(frame, *fargs) -> iterable_of_artists
+
+        It is often more convenient to provide the arguments using
+        `functools.partial`. In this way it is also possible to pass keyword
+        arguments. To pass a function with both positional and keyword
+        arguments, set all arguments as keyword arguments, just leaving the
+        *frame* argument unset::
+
+            def func(frame, art, *, y=None):
+                ...
+
+            ani = FuncAnimation(fig, partial(func, art=ln, y='foo'))
+
+        If ``blit == True``, *func* must return an iterable of all artists
+        that were modified or created. This information is used by the blitting
+        algorithm to determine which parts of the figure have to be updated.
+        The return value is unused if ``blit == False`` and may be omitted in
+        that case.
+
+    frames : iterable, int, generator function, or None, optional
+        Source of data to pass *func* and each frame of the animation
+
+        - If an iterable, then simply use the values provided.  If the
+          iterable has a length, it will override the *save_count* kwarg.
+
+        - If an integer, then equivalent to passing ``range(frames)``
+
+        - If a generator function, then must have the signature::
+
+             def gen_function() -> obj
+
+        - If *None*, then equivalent to passing ``itertools.count``.
+
+        In all of these cases, the values in *frames* is simply passed through
+        to the user-supplied *func* and thus can be of any type.
+
+    init_func : callable, optional
+        A function used to draw a clear frame. If not given, the results of
+        drawing from the first item in the frames sequence will be used. This
+        function will be called once before the first frame.
+
+        The required signature is::
+
+            def init_func() -> iterable_of_artists
+
+        If ``blit == True``, *init_func* must return an iterable of artists
+        to be re-drawn. This information is used by the blitting algorithm to
+        determine which parts of the figure have to be updated.  The return
+        value is unused if ``blit == False`` and may be omitted in that case.
+
+    fargs : tuple or None, optional
+        Additional arguments to pass to each call to *func*. Note: the use of
+        `functools.partial` is preferred over *fargs*. See *func* for details.
+
+    save_count : int, optional
+        Fallback for the number of values from *frames* to cache. This is
+        only used if the number of frames cannot be inferred from *frames*,
+        i.e. when it's an iterator without length or a generator.
+
+    interval : int, default: 200
+        Delay between frames in milliseconds.
+
+    repeat_delay : int, default: 0
+        The delay in milliseconds between consecutive animation runs, if
+        *repeat* is True.
+
+    repeat : bool, default: True
+        Whether the animation repeats when the sequence of frames is completed.
+
+    blit : bool, default: False
+        Whether blitting is used to optimize drawing.  Note: when using
+        blitting, any animated artists will be drawn according to their zorder;
+        however, they will be drawn on top of any previous artists, regardless
+        of their zorder.
+
+    cache_frame_data : bool, default: True
+        Whether frame data is cached.  Disabling cache might be helpful when
+        frames contain large objects.
+    """
+    def __init__(self, fig, func, frames=None, init_func=None, fargs=None,
+                 save_count=None, *, cache_frame_data=True, **kwargs):
+        if fargs:
+            self._args = fargs
+        else:
+            self._args = ()
+        self._func = func
+        self._init_func = init_func
+
+        # Amount of framedata to keep around for saving movies. This is only
+        # used if we don't know how many frames there will be: in the case
+        # of no generator or in the case of a callable.
+        self._save_count = save_count
+        # Set up a function that creates a new iterable when needed. If nothing
+        # is passed in for frames, just use itertools.count, which will just
+        # keep counting from 0. A callable passed in for frames is assumed to
+        # be a generator. An iterable will be used as is, and anything else
+        # will be treated as a number of frames.
+        if frames is None:
+            self._iter_gen = itertools.count
+        elif callable(frames):
+            self._iter_gen = frames
+        elif np.iterable(frames):
+            if kwargs.get('repeat', True):
+                self._tee_from = frames
+                def iter_frames(frames=frames):
+                    this, self._tee_from = itertools.tee(self._tee_from, 2)
+                    yield from this
+                self._iter_gen = iter_frames
+            else:
+                self._iter_gen = lambda: iter(frames)
+            if hasattr(frames, '__len__'):
+                self._save_count = len(frames)
+                if save_count is not None:
+                    _api.warn_external(
+                        f"You passed in an explicit {save_count=} "
+                        "which is being ignored in favor of "
+                        f"{len(frames)=}."
+                    )
+        else:
+            self._iter_gen = lambda: iter(range(frames))
+            self._save_count = frames
+            if save_count is not None:
+                _api.warn_external(
+                    f"You passed in an explicit {save_count=} which is being "
+                    f"ignored in favor of {frames=}."
+                )
+        if self._save_count is None and cache_frame_data:
+            _api.warn_external(
+                f"{frames=!r} which we can infer the length of, "
+                "did not pass an explicit *save_count* "
+                f"and passed {cache_frame_data=}.  To avoid a possibly "
+                "unbounded cache, frame data caching has been disabled. "
+                "To suppress this warning either pass "
+                "`cache_frame_data=False` or `save_count=MAX_FRAMES`."
+            )
+            cache_frame_data = False
+
+        self._cache_frame_data = cache_frame_data
+
+        # Needs to be initialized so the draw functions work without checking
+        self._save_seq = []
+
+        super().__init__(fig, **kwargs)
+
+        # Need to reset the saved seq, since right now it will contain data
+        # for a single frame from init, which is not what we want.
+        self._save_seq = []
+
+    def new_frame_seq(self):
+        # Use the generating function to generate a new frame sequence
+        return self._iter_gen()
+
+    def new_saved_frame_seq(self):
+        # Generate an iterator for the sequence of saved data. If there are
+        # no saved frames, generate a new frame sequence and take the first
+        # save_count entries in it.
+        if self._save_seq:
+            # While iterating we are going to update _save_seq
+            # so make a copy to safely iterate over
+            self._old_saved_seq = list(self._save_seq)
+            return iter(self._old_saved_seq)
+        else:
+            if self._save_count is None:
+                frame_seq = self.new_frame_seq()
+
+                def gen():
+                    try:
+                        while True:
+                            yield next(frame_seq)
+                    except StopIteration:
+                        pass
+                return gen()
+            else:
+                return itertools.islice(self.new_frame_seq(), self._save_count)
+
+    def _init_draw(self):
+        super()._init_draw()
+        # Initialize the drawing either using the given init_func or by
+        # calling the draw function with the first item of the frame sequence.
+        # For blitting, the init_func should return a sequence of modified
+        # artists.
+        if self._init_func is None:
+            try:
+                frame_data = next(self.new_frame_seq())
+            except StopIteration:
+                # we can't start the iteration, it may have already been
+                # exhausted by a previous save or just be 0 length.
+                # warn and bail.
+                warnings.warn(
+                    "Can not start iterating the frames for the initial draw. "
+                    "This can be caused by passing in a 0 length sequence "
+                    "for *frames*.\n\n"
+                    "If you passed *frames* as a generator "
+                    "it may be exhausted due to a previous display or save."
+                )
+                return
+            self._draw_frame(frame_data)
+        else:
+            self._drawn_artists = self._init_func()
+            if self._blit:
+                if self._drawn_artists is None:
+                    raise RuntimeError('The init_func must return a '
+                                       'sequence of Artist objects.')
+                for a in self._drawn_artists:
+                    a.set_animated(self._blit)
+        self._save_seq = []
+
+    def _draw_frame(self, framedata):
+        if self._cache_frame_data:
+            # Save the data for potential saving of movies.
+            self._save_seq.append(framedata)
+            self._save_seq = self._save_seq[-self._save_count:]
+
+        # Call the func with framedata and args. If blitting is desired,
+        # func needs to return a sequence of any artists that were modified.
+        self._drawn_artists = self._func(framedata, *self._args)
+
+        if self._blit:
+
+            err = RuntimeError('The animation function must return a sequence '
+                               'of Artist objects.')
+            try:
+                # check if a sequence
+                iter(self._drawn_artists)
+            except TypeError:
+                raise err from None
+
+            # check each item if it's artist
+            for i in self._drawn_artists:
+                if not isinstance(i, mpl.artist.Artist):
+                    raise err
+
+            self._drawn_artists = sorted(self._drawn_artists,
+                                         key=lambda x: x.get_zorder())
+
+            for a in self._drawn_artists:
+                a.set_animated(self._blit)
+
+
+def _validate_grabframe_kwargs(savefig_kwargs):
+    if mpl.rcParams['savefig.bbox'] == 'tight':
+        raise ValueError(
+            f"{mpl.rcParams['savefig.bbox']=} must not be 'tight' as it "
+            "may cause frame size to vary, which is inappropriate for animation."
+        )
+    for k in ('dpi', 'bbox_inches', 'format'):
+        if k in savefig_kwargs:
+            raise TypeError(
+                f"grab_frame got an unexpected keyword argument {k!r}"
+            )
diff --git a/lib/python3.12/site-packages/matplotlib/axis.py b/lib/python3.12/site-packages/matplotlib/axis.py
new file mode 100644
index 0000000000000000000000000000000000000000..714fb08f55be9a2a7967073960031785b50e0df1
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/axis.py
@@ -0,0 +1,2819 @@
+"""
+Classes for the ticks and x- and y-axis.
+"""
+
+import datetime
+import functools
+import logging
+from numbers import Real
+import warnings
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib import _api, cbook
+import matplotlib.artist as martist
+import matplotlib.colors as mcolors
+import matplotlib.lines as mlines
+import matplotlib.scale as mscale
+import matplotlib.text as mtext
+import matplotlib.ticker as mticker
+import matplotlib.transforms as mtransforms
+import matplotlib.units as munits
+
+_log = logging.getLogger(__name__)
+
+GRIDLINE_INTERPOLATION_STEPS = 180
+
+# This list is being used for compatibility with Axes.grid, which
+# allows all Line2D kwargs.
+_line_inspector = martist.ArtistInspector(mlines.Line2D)
+_line_param_names = _line_inspector.get_setters()
+_line_param_aliases = [next(iter(d)) for d in _line_inspector.aliasd.values()]
+_gridline_param_names = ['grid_' + name
+                         for name in _line_param_names + _line_param_aliases]
+
+
+class Tick(martist.Artist):
+    """
+    Abstract base class for the axis ticks, grid lines and labels.
+
+    Ticks mark a position on an Axis. They contain two lines as markers and
+    two labels; one each for the bottom and top positions (in case of an
+    `.XAxis`) or for the left and right positions (in case of a `.YAxis`).
+
+    Attributes
+    ----------
+    tick1line : `~matplotlib.lines.Line2D`
+        The left/bottom tick marker.
+    tick2line : `~matplotlib.lines.Line2D`
+        The right/top tick marker.
+    gridline : `~matplotlib.lines.Line2D`
+        The grid line associated with the label position.
+    label1 : `~matplotlib.text.Text`
+        The left/bottom tick label.
+    label2 : `~matplotlib.text.Text`
+        The right/top tick label.
+
+    """
+    def __init__(
+        self, axes, loc, *,
+        size=None,  # points
+        width=None,
+        color=None,
+        tickdir=None,
+        pad=None,
+        labelsize=None,
+        labelcolor=None,
+        labelfontfamily=None,
+        zorder=None,
+        gridOn=None,  # defaults to axes.grid depending on axes.grid.which
+        tick1On=True,
+        tick2On=True,
+        label1On=True,
+        label2On=False,
+        major=True,
+        labelrotation=0,
+        grid_color=None,
+        grid_linestyle=None,
+        grid_linewidth=None,
+        grid_alpha=None,
+        **kwargs,  # Other Line2D kwargs applied to gridlines.
+    ):
+        """
+        bbox is the Bound2D bounding box in display coords of the Axes
+        loc is the tick location in data coords
+        size is the tick size in points
+        """
+        super().__init__()
+
+        if gridOn is None:
+            which = mpl.rcParams['axes.grid.which']
+            if major and (which in ('both', 'major')):
+                gridOn = mpl.rcParams['axes.grid']
+            elif (not major) and (which in ('both', 'minor')):
+                gridOn = mpl.rcParams['axes.grid']
+            else:
+                gridOn = False
+
+        self.set_figure(axes.get_figure(root=False))
+        self.axes = axes
+
+        self._loc = loc
+        self._major = major
+
+        name = self.__name__
+        major_minor = "major" if major else "minor"
+
+        if size is None:
+            size = mpl.rcParams[f"{name}.{major_minor}.size"]
+        self._size = size
+
+        if width is None:
+            width = mpl.rcParams[f"{name}.{major_minor}.width"]
+        self._width = width
+
+        if color is None:
+            color = mpl.rcParams[f"{name}.color"]
+
+        if pad is None:
+            pad = mpl.rcParams[f"{name}.{major_minor}.pad"]
+        self._base_pad = pad
+
+        if labelcolor is None:
+            labelcolor = mpl.rcParams[f"{name}.labelcolor"]
+
+        if cbook._str_equal(labelcolor, 'inherit'):
+            # inherit from tick color
+            labelcolor = mpl.rcParams[f"{name}.color"]
+
+        if labelsize is None:
+            labelsize = mpl.rcParams[f"{name}.labelsize"]
+
+        self._set_labelrotation(labelrotation)
+
+        if zorder is None:
+            if major:
+                zorder = mlines.Line2D.zorder + 0.01
+            else:
+                zorder = mlines.Line2D.zorder
+        self._zorder = zorder
+
+        grid_color = mpl._val_or_rc(grid_color, "grid.color")
+        grid_linestyle = mpl._val_or_rc(grid_linestyle, "grid.linestyle")
+        grid_linewidth = mpl._val_or_rc(grid_linewidth, "grid.linewidth")
+        if grid_alpha is None and not mcolors._has_alpha_channel(grid_color):
+            # alpha precedence: kwarg > color alpha > rcParams['grid.alpha']
+            # Note: only resolve to rcParams if the color does not have alpha
+            # otherwise `grid(color=(1, 1, 1, 0.5))` would work like
+            #   grid(color=(1, 1, 1, 0.5), alpha=rcParams['grid.alpha'])
+            # so the that the rcParams default would override color alpha.
+            grid_alpha = mpl.rcParams["grid.alpha"]
+        grid_kw = {k[5:]: v for k, v in kwargs.items()}
+
+        self.tick1line = mlines.Line2D(
+            [], [],
+            color=color, linestyle="none", zorder=zorder, visible=tick1On,
+            markeredgecolor=color, markersize=size, markeredgewidth=width,
+        )
+        self.tick2line = mlines.Line2D(
+            [], [],
+            color=color, linestyle="none", zorder=zorder, visible=tick2On,
+            markeredgecolor=color, markersize=size, markeredgewidth=width,
+        )
+        self.gridline = mlines.Line2D(
+            [], [],
+            color=grid_color, alpha=grid_alpha, visible=gridOn,
+            linestyle=grid_linestyle, linewidth=grid_linewidth, marker="",
+            **grid_kw,
+        )
+        self.gridline.get_path()._interpolation_steps = \
+            GRIDLINE_INTERPOLATION_STEPS
+        self.label1 = mtext.Text(
+            np.nan, np.nan,
+            fontsize=labelsize, color=labelcolor, visible=label1On,
+            fontfamily=labelfontfamily, rotation=self._labelrotation[1])
+        self.label2 = mtext.Text(
+            np.nan, np.nan,
+            fontsize=labelsize, color=labelcolor, visible=label2On,
+            fontfamily=labelfontfamily, rotation=self._labelrotation[1])
+
+        self._apply_tickdir(tickdir)
+
+        for artist in [self.tick1line, self.tick2line, self.gridline,
+                       self.label1, self.label2]:
+            self._set_artist_props(artist)
+
+        self.update_position(loc)
+
+    def _set_labelrotation(self, labelrotation):
+        if isinstance(labelrotation, str):
+            mode = labelrotation
+            angle = 0
+        elif isinstance(labelrotation, (tuple, list)):
+            mode, angle = labelrotation
+        else:
+            mode = 'default'
+            angle = labelrotation
+        _api.check_in_list(['auto', 'default'], labelrotation=mode)
+        self._labelrotation = (mode, angle)
+
+    @property
+    def _pad(self):
+        return self._base_pad + self.get_tick_padding()
+
+    def _apply_tickdir(self, tickdir):
+        """Set tick direction.  Valid values are 'out', 'in', 'inout'."""
+        # This method is responsible for verifying input and, in subclasses, for setting
+        # the tick{1,2}line markers.  From the user perspective this should always be
+        # called through _apply_params, which further updates ticklabel positions using
+        # the new pads.
+        if tickdir is None:
+            tickdir = mpl.rcParams[f'{self.__name__}.direction']
+        else:
+            _api.check_in_list(['in', 'out', 'inout'], tickdir=tickdir)
+        self._tickdir = tickdir
+
+    def get_tickdir(self):
+        return self._tickdir
+
+    def get_tick_padding(self):
+        """Get the length of the tick outside of the Axes."""
+        padding = {
+            'in': 0.0,
+            'inout': 0.5,
+            'out': 1.0
+        }
+        return self._size * padding[self._tickdir]
+
+    def get_children(self):
+        children = [self.tick1line, self.tick2line,
+                    self.gridline, self.label1, self.label2]
+        return children
+
+    def set_clip_path(self, path, transform=None):
+        # docstring inherited
+        super().set_clip_path(path, transform)
+        self.gridline.set_clip_path(path, transform)
+        self.stale = True
+
+    def contains(self, mouseevent):
+        """
+        Test whether the mouse event occurred in the Tick marks.
+
+        This function always returns false.  It is more useful to test if the
+        axis as a whole contains the mouse rather than the set of tick marks.
+        """
+        return False, {}
+
+    def set_pad(self, val):
+        """
+        Set the tick label pad in points
+
+        Parameters
+        ----------
+        val : float
+        """
+        self._apply_params(pad=val)
+        self.stale = True
+
+    def get_pad(self):
+        """Get the value of the tick label pad in points."""
+        return self._base_pad
+
+    def get_loc(self):
+        """Return the tick location (data coords) as a scalar."""
+        return self._loc
+
+    @martist.allow_rasterization
+    def draw(self, renderer):
+        if not self.get_visible():
+            self.stale = False
+            return
+        renderer.open_group(self.__name__, gid=self.get_gid())
+        for artist in [self.gridline, self.tick1line, self.tick2line,
+                       self.label1, self.label2]:
+            artist.draw(renderer)
+        renderer.close_group(self.__name__)
+        self.stale = False
+
+    def set_url(self, url):
+        """
+        Set the url of label1 and label2.
+
+        Parameters
+        ----------
+        url : str
+        """
+        super().set_url(url)
+        self.label1.set_url(url)
+        self.label2.set_url(url)
+        self.stale = True
+
+    def _set_artist_props(self, a):
+        a.set_figure(self.get_figure(root=False))
+
+    def get_view_interval(self):
+        """
+        Return the view limits ``(min, max)`` of the axis the tick belongs to.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def _apply_params(self, **kwargs):
+        for name, target in [("gridOn", self.gridline),
+                             ("tick1On", self.tick1line),
+                             ("tick2On", self.tick2line),
+                             ("label1On", self.label1),
+                             ("label2On", self.label2)]:
+            if name in kwargs:
+                target.set_visible(kwargs.pop(name))
+        if any(k in kwargs for k in ['size', 'width', 'pad', 'tickdir']):
+            self._size = kwargs.pop('size', self._size)
+            # Width could be handled outside this block, but it is
+            # convenient to leave it here.
+            self._width = kwargs.pop('width', self._width)
+            self._base_pad = kwargs.pop('pad', self._base_pad)
+            # _apply_tickdir uses _size and _base_pad to make _pad, and also
+            # sets the ticklines markers.
+            self._apply_tickdir(kwargs.pop('tickdir', self._tickdir))
+            for line in (self.tick1line, self.tick2line):
+                line.set_markersize(self._size)
+                line.set_markeredgewidth(self._width)
+            # _get_text1_transform uses _pad from _apply_tickdir.
+            trans = self._get_text1_transform()[0]
+            self.label1.set_transform(trans)
+            trans = self._get_text2_transform()[0]
+            self.label2.set_transform(trans)
+        tick_kw = {k: v for k, v in kwargs.items() if k in ['color', 'zorder']}
+        if 'color' in kwargs:
+            tick_kw['markeredgecolor'] = kwargs['color']
+        self.tick1line.set(**tick_kw)
+        self.tick2line.set(**tick_kw)
+        for k, v in tick_kw.items():
+            setattr(self, '_' + k, v)
+
+        if 'labelrotation' in kwargs:
+            self._set_labelrotation(kwargs.pop('labelrotation'))
+            self.label1.set(rotation=self._labelrotation[1])
+            self.label2.set(rotation=self._labelrotation[1])
+
+        label_kw = {k[5:]: v for k, v in kwargs.items()
+                    if k in ['labelsize', 'labelcolor', 'labelfontfamily']}
+        self.label1.set(**label_kw)
+        self.label2.set(**label_kw)
+
+        grid_kw = {k[5:]: v for k, v in kwargs.items()
+                   if k in _gridline_param_names}
+        self.gridline.set(**grid_kw)
+
+    def update_position(self, loc):
+        """Set the location of tick in data coords with scalar *loc*."""
+        raise NotImplementedError('Derived must override')
+
+    def _get_text1_transform(self):
+        raise NotImplementedError('Derived must override')
+
+    def _get_text2_transform(self):
+        raise NotImplementedError('Derived must override')
+
+
+class XTick(Tick):
+    """
+    Contains all the Artists needed to make an x tick - the tick line,
+    the label text and the grid line
+    """
+    __name__ = 'xtick'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # x in data coords, y in axes coords
+        ax = self.axes
+        self.tick1line.set(
+            data=([0], [0]), transform=ax.get_xaxis_transform("tick1"))
+        self.tick2line.set(
+            data=([0], [1]), transform=ax.get_xaxis_transform("tick2"))
+        self.gridline.set(
+            data=([0, 0], [0, 1]), transform=ax.get_xaxis_transform("grid"))
+        # the y loc is 3 points below the min of y axis
+        trans, va, ha = self._get_text1_transform()
+        self.label1.set(
+            x=0, y=0,
+            verticalalignment=va, horizontalalignment=ha, transform=trans,
+        )
+        trans, va, ha = self._get_text2_transform()
+        self.label2.set(
+            x=0, y=1,
+            verticalalignment=va, horizontalalignment=ha, transform=trans,
+        )
+
+    def _get_text1_transform(self):
+        return self.axes.get_xaxis_text1_transform(self._pad)
+
+    def _get_text2_transform(self):
+        return self.axes.get_xaxis_text2_transform(self._pad)
+
+    def _apply_tickdir(self, tickdir):
+        # docstring inherited
+        super()._apply_tickdir(tickdir)
+        mark1, mark2 = {
+            'out': (mlines.TICKDOWN, mlines.TICKUP),
+            'in': (mlines.TICKUP, mlines.TICKDOWN),
+            'inout': ('|', '|'),
+        }[self._tickdir]
+        self.tick1line.set_marker(mark1)
+        self.tick2line.set_marker(mark2)
+
+    def update_position(self, loc):
+        """Set the location of tick in data coords with scalar *loc*."""
+        self.tick1line.set_xdata((loc,))
+        self.tick2line.set_xdata((loc,))
+        self.gridline.set_xdata((loc,))
+        self.label1.set_x(loc)
+        self.label2.set_x(loc)
+        self._loc = loc
+        self.stale = True
+
+    def get_view_interval(self):
+        # docstring inherited
+        return self.axes.viewLim.intervalx
+
+
+class YTick(Tick):
+    """
+    Contains all the Artists needed to make a Y tick - the tick line,
+    the label text and the grid line
+    """
+    __name__ = 'ytick'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # x in axes coords, y in data coords
+        ax = self.axes
+        self.tick1line.set(
+            data=([0], [0]), transform=ax.get_yaxis_transform("tick1"))
+        self.tick2line.set(
+            data=([1], [0]), transform=ax.get_yaxis_transform("tick2"))
+        self.gridline.set(
+            data=([0, 1], [0, 0]), transform=ax.get_yaxis_transform("grid"))
+        # the y loc is 3 points below the min of y axis
+        trans, va, ha = self._get_text1_transform()
+        self.label1.set(
+            x=0, y=0,
+            verticalalignment=va, horizontalalignment=ha, transform=trans,
+        )
+        trans, va, ha = self._get_text2_transform()
+        self.label2.set(
+            x=1, y=0,
+            verticalalignment=va, horizontalalignment=ha, transform=trans,
+        )
+
+    def _get_text1_transform(self):
+        return self.axes.get_yaxis_text1_transform(self._pad)
+
+    def _get_text2_transform(self):
+        return self.axes.get_yaxis_text2_transform(self._pad)
+
+    def _apply_tickdir(self, tickdir):
+        # docstring inherited
+        super()._apply_tickdir(tickdir)
+        mark1, mark2 = {
+            'out': (mlines.TICKLEFT, mlines.TICKRIGHT),
+            'in': (mlines.TICKRIGHT, mlines.TICKLEFT),
+            'inout': ('_', '_'),
+        }[self._tickdir]
+        self.tick1line.set_marker(mark1)
+        self.tick2line.set_marker(mark2)
+
+    def update_position(self, loc):
+        """Set the location of tick in data coords with scalar *loc*."""
+        self.tick1line.set_ydata((loc,))
+        self.tick2line.set_ydata((loc,))
+        self.gridline.set_ydata((loc,))
+        self.label1.set_y(loc)
+        self.label2.set_y(loc)
+        self._loc = loc
+        self.stale = True
+
+    def get_view_interval(self):
+        # docstring inherited
+        return self.axes.viewLim.intervaly
+
+
+class Ticker:
+    """
+    A container for the objects defining tick position and format.
+
+    Attributes
+    ----------
+    locator : `~matplotlib.ticker.Locator` subclass
+        Determines the positions of the ticks.
+    formatter : `~matplotlib.ticker.Formatter` subclass
+        Determines the format of the tick labels.
+    """
+
+    def __init__(self):
+        self._locator = None
+        self._formatter = None
+        self._locator_is_default = True
+        self._formatter_is_default = True
+
+    @property
+    def locator(self):
+        return self._locator
+
+    @locator.setter
+    def locator(self, locator):
+        if not isinstance(locator, mticker.Locator):
+            raise TypeError('locator must be a subclass of '
+                            'matplotlib.ticker.Locator')
+        self._locator = locator
+
+    @property
+    def formatter(self):
+        return self._formatter
+
+    @formatter.setter
+    def formatter(self, formatter):
+        if not isinstance(formatter, mticker.Formatter):
+            raise TypeError('formatter must be a subclass of '
+                            'matplotlib.ticker.Formatter')
+        self._formatter = formatter
+
+
+class _LazyTickList:
+    """
+    A descriptor for lazy instantiation of tick lists.
+
+    See comment above definition of the ``majorTicks`` and ``minorTicks``
+    attributes.
+    """
+
+    def __init__(self, major):
+        self._major = major
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        else:
+            # instance._get_tick() can itself try to access the majorTicks
+            # attribute (e.g. in certain projection classes which override
+            # e.g. get_xaxis_text1_transform).  In order to avoid infinite
+            # recursion, first set the majorTicks on the instance temporarily
+            # to an empty lis. Then create the tick; note that _get_tick()
+            # may call reset_ticks(). Therefore, the final tick list is
+            # created and assigned afterwards.
+            if self._major:
+                instance.majorTicks = []
+                tick = instance._get_tick(major=True)
+                instance.majorTicks = [tick]
+                return instance.majorTicks
+            else:
+                instance.minorTicks = []
+                tick = instance._get_tick(major=False)
+                instance.minorTicks = [tick]
+                return instance.minorTicks
+
+
+class Axis(martist.Artist):
+    """
+    Base class for `.XAxis` and `.YAxis`.
+
+    Attributes
+    ----------
+    isDefault_label : bool
+
+    axes : `~matplotlib.axes.Axes`
+        The `~.axes.Axes` to which the Axis belongs.
+    major : `~matplotlib.axis.Ticker`
+        Determines the major tick positions and their label format.
+    minor : `~matplotlib.axis.Ticker`
+        Determines the minor tick positions and their label format.
+    callbacks : `~matplotlib.cbook.CallbackRegistry`
+
+    label : `~matplotlib.text.Text`
+        The axis label.
+    labelpad : float
+        The distance between the axis label and the tick labels.
+        Defaults to :rc:`axes.labelpad`.
+    offsetText : `~matplotlib.text.Text`
+        A `.Text` object containing the data offset of the ticks (if any).
+    pickradius : float
+        The acceptance radius for containment tests. See also `.Axis.contains`.
+    majorTicks : list of `.Tick`
+        The major ticks.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+
+    minorTicks : list of `.Tick`
+        The minor ticks.
+    """
+    OFFSETTEXTPAD = 3
+    # The class used in _get_tick() to create tick instances. Must either be
+    # overwritten in subclasses, or subclasses must reimplement _get_tick().
+    _tick_class = None
+    converter = _api.deprecate_privatize_attribute(
+                    "3.10",
+                    alternative="get_converter and set_converter methods"
+                )
+
+    def __str__(self):
+        return "{}({},{})".format(
+            type(self).__name__, *self.axes.transAxes.transform((0, 0)))
+
+    def __init__(self, axes, *, pickradius=15, clear=True):
+        """
+        Parameters
+        ----------
+        axes : `~matplotlib.axes.Axes`
+            The `~.axes.Axes` to which the created Axis belongs.
+        pickradius : float
+            The acceptance radius for containment tests. See also
+            `.Axis.contains`.
+        clear : bool, default: True
+            Whether to clear the Axis on creation. This is not required, e.g.,  when
+            creating an Axis as part of an Axes, as ``Axes.clear`` will call
+            ``Axis.clear``.
+            .. versionadded:: 3.8
+        """
+        super().__init__()
+        self._remove_overlapping_locs = True
+
+        self.set_figure(axes.get_figure(root=False))
+
+        self.isDefault_label = True
+
+        self.axes = axes
+        self.major = Ticker()
+        self.minor = Ticker()
+        self.callbacks = cbook.CallbackRegistry(signals=["units"])
+
+        self._autolabelpos = True
+
+        self.label = mtext.Text(
+            np.nan, np.nan,
+            fontsize=mpl.rcParams['axes.labelsize'],
+            fontweight=mpl.rcParams['axes.labelweight'],
+            color=mpl.rcParams['axes.labelcolor'],
+        )  #: The `.Text` object of the axis label.
+
+        self._set_artist_props(self.label)
+        self.offsetText = mtext.Text(np.nan, np.nan)
+        self._set_artist_props(self.offsetText)
+
+        self.labelpad = mpl.rcParams['axes.labelpad']
+
+        self.pickradius = pickradius
+
+        # Initialize here for testing; later add API
+        self._major_tick_kw = dict()
+        self._minor_tick_kw = dict()
+
+        if clear:
+            self.clear()
+        else:
+            self._converter = None
+            self._converter_is_explicit = False
+            self.units = None
+
+        self._autoscale_on = True
+
+    @property
+    def isDefault_majloc(self):
+        return self.major._locator_is_default
+
+    @isDefault_majloc.setter
+    def isDefault_majloc(self, value):
+        self.major._locator_is_default = value
+
+    @property
+    def isDefault_majfmt(self):
+        return self.major._formatter_is_default
+
+    @isDefault_majfmt.setter
+    def isDefault_majfmt(self, value):
+        self.major._formatter_is_default = value
+
+    @property
+    def isDefault_minloc(self):
+        return self.minor._locator_is_default
+
+    @isDefault_minloc.setter
+    def isDefault_minloc(self, value):
+        self.minor._locator_is_default = value
+
+    @property
+    def isDefault_minfmt(self):
+        return self.minor._formatter_is_default
+
+    @isDefault_minfmt.setter
+    def isDefault_minfmt(self, value):
+        self.minor._formatter_is_default = value
+
+    def _get_shared_axes(self):
+        """Return Grouper of shared Axes for current axis."""
+        return self.axes._shared_axes[
+            self._get_axis_name()].get_siblings(self.axes)
+
+    def _get_shared_axis(self):
+        """Return list of shared axis for current axis."""
+        name = self._get_axis_name()
+        return [ax._axis_map[name] for ax in self._get_shared_axes()]
+
+    def _get_axis_name(self):
+        """Return the axis name."""
+        return next(name for name, axis in self.axes._axis_map.items()
+                    if axis is self)
+
+    # During initialization, Axis objects often create ticks that are later
+    # unused; this turns out to be a very slow step.  Instead, use a custom
+    # descriptor to make the tick lists lazy and instantiate them as needed.
+    majorTicks = _LazyTickList(major=True)
+    minorTicks = _LazyTickList(major=False)
+
+    def get_remove_overlapping_locs(self):
+        return self._remove_overlapping_locs
+
+    def set_remove_overlapping_locs(self, val):
+        self._remove_overlapping_locs = bool(val)
+
+    remove_overlapping_locs = property(
+        get_remove_overlapping_locs, set_remove_overlapping_locs,
+        doc=('If minor ticker locations that overlap with major '
+             'ticker locations should be trimmed.'))
+
+    def set_label_coords(self, x, y, transform=None):
+        """
+        Set the coordinates of the label.
+
+        By default, the x coordinate of the y label and the y coordinate of the
+        x label are determined by the tick label bounding boxes, but this can
+        lead to poor alignment of multiple labels if there are multiple Axes.
+
+        You can also specify the coordinate system of the label with the
+        transform.  If None, the default coordinate system will be the axes
+        coordinate system: (0, 0) is bottom left, (0.5, 0.5) is center, etc.
+        """
+        self._autolabelpos = False
+        if transform is None:
+            transform = self.axes.transAxes
+
+        self.label.set_transform(transform)
+        self.label.set_position((x, y))
+        self.stale = True
+
+    def get_transform(self):
+        """Return the transform used in the Axis' scale"""
+        return self._scale.get_transform()
+
+    def get_scale(self):
+        """Return this Axis' scale (as a str)."""
+        return self._scale.name
+
+    def _set_scale(self, value, **kwargs):
+        if not isinstance(value, mscale.ScaleBase):
+            self._scale = mscale.scale_factory(value, self, **kwargs)
+        else:
+            self._scale = value
+        self._scale.set_default_locators_and_formatters(self)
+
+        self.isDefault_majloc = True
+        self.isDefault_minloc = True
+        self.isDefault_majfmt = True
+        self.isDefault_minfmt = True
+
+    # This method is directly wrapped by Axes.set_{x,y}scale.
+    def _set_axes_scale(self, value, **kwargs):
+        """
+        Set this Axis' scale.
+
+        Parameters
+        ----------
+        value : str or `.ScaleBase`
+            The axis scale type to apply.  Valid string values are the names of scale
+            classes ("linear", "log", "function",...).  These may be the names of any
+            of the :ref:`built-in scales<builtin_scales>` or of any custom scales
+            registered using `matplotlib.scale.register_scale`.
+
+        **kwargs
+            If *value* is a string, keywords are passed to the instantiation method of
+            the respective class.
+        """
+        name = self._get_axis_name()
+        old_default_lims = (self.get_major_locator()
+                            .nonsingular(-np.inf, np.inf))
+        for ax in self._get_shared_axes():
+            ax._axis_map[name]._set_scale(value, **kwargs)
+            ax._update_transScale()
+            ax.stale = True
+        new_default_lims = (self.get_major_locator()
+                            .nonsingular(-np.inf, np.inf))
+        if old_default_lims != new_default_lims:
+            # Force autoscaling now, to take advantage of the scale locator's
+            # nonsingular() before it possibly gets swapped out by the user.
+            self.axes.autoscale_view(
+                **{f"scale{k}": k == name for k in self.axes._axis_names})
+
+    def limit_range_for_scale(self, vmin, vmax):
+        """
+        Return the range *vmin*, *vmax*, restricted to the domain supported by the
+        current scale.
+        """
+        return self._scale.limit_range_for_scale(vmin, vmax, self.get_minpos())
+
+    def _get_autoscale_on(self):
+        """Return whether this Axis is autoscaled."""
+        return self._autoscale_on
+
+    def _set_autoscale_on(self, b):
+        """
+        Set whether this Axis is autoscaled when drawing or by `.Axes.autoscale_view`.
+
+        If b is None, then the value is not changed.
+
+        Parameters
+        ----------
+        b : bool
+        """
+        if b is not None:
+            self._autoscale_on = b
+
+    def get_children(self):
+        return [self.label, self.offsetText,
+                *self.get_major_ticks(), *self.get_minor_ticks()]
+
+    def _reset_major_tick_kw(self):
+        self._major_tick_kw.clear()
+        self._major_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'major'))
+
+    def _reset_minor_tick_kw(self):
+        self._minor_tick_kw.clear()
+        self._minor_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'minor'))
+
+    def clear(self):
+        """
+        Clear the axis.
+
+        This resets axis properties to their default values:
+
+        - the label
+        - the scale
+        - locators, formatters and ticks
+        - major and minor grid
+        - units
+        - registered callbacks
+        """
+        self.label._reset_visual_defaults()
+        # The above resets the label formatting using text rcParams,
+        # so we then update the formatting using axes rcParams
+        self.label.set_color(mpl.rcParams['axes.labelcolor'])
+        self.label.set_fontsize(mpl.rcParams['axes.labelsize'])
+        self.label.set_fontweight(mpl.rcParams['axes.labelweight'])
+        self.offsetText._reset_visual_defaults()
+        self.labelpad = mpl.rcParams['axes.labelpad']
+
+        self._init()
+
+        self._set_scale('linear')
+
+        # Clear the callback registry for this axis, or it may "leak"
+        self.callbacks = cbook.CallbackRegistry(signals=["units"])
+
+        # whether the grids are on
+        self._major_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'major'))
+        self._minor_tick_kw['gridOn'] = (
+                mpl.rcParams['axes.grid'] and
+                mpl.rcParams['axes.grid.which'] in ('both', 'minor'))
+        self.reset_ticks()
+
+        self._converter = None
+        self._converter_is_explicit = False
+        self.units = None
+        self.stale = True
+
+    def reset_ticks(self):
+        """
+        Re-initialize the major and minor Tick lists.
+
+        Each list starts with a single fresh Tick.
+        """
+        # Restore the lazy tick lists.
+        try:
+            del self.majorTicks
+        except AttributeError:
+            pass
+        try:
+            del self.minorTicks
+        except AttributeError:
+            pass
+        try:
+            self.set_clip_path(self.axes.patch)
+        except AttributeError:
+            pass
+
+    def minorticks_on(self):
+        """
+        Display default minor ticks on the Axis, depending on the scale
+        (`~.axis.Axis.get_scale`).
+
+        Scales use specific minor locators:
+
+        - log: `~.LogLocator`
+        - symlog: `~.SymmetricalLogLocator`
+        - asinh: `~.AsinhLocator`
+        - logit: `~.LogitLocator`
+        - default: `~.AutoMinorLocator`
+
+        Displaying minor ticks may reduce performance; you may turn them off
+        using `minorticks_off()` if drawing speed is a problem.
+        """
+        scale = self.get_scale()
+        if scale == 'log':
+            s = self._scale
+            self.set_minor_locator(mticker.LogLocator(s.base, s.subs))
+        elif scale == 'symlog':
+            s = self._scale
+            self.set_minor_locator(
+                mticker.SymmetricalLogLocator(s._transform, s.subs))
+        elif scale == 'asinh':
+            s = self._scale
+            self.set_minor_locator(
+                    mticker.AsinhLocator(s.linear_width, base=s._base,
+                                         subs=s._subs))
+        elif scale == 'logit':
+            self.set_minor_locator(mticker.LogitLocator(minor=True))
+        else:
+            self.set_minor_locator(mticker.AutoMinorLocator())
+
+    def minorticks_off(self):
+        """Remove minor ticks from the Axis."""
+        self.set_minor_locator(mticker.NullLocator())
+
+    def set_tick_params(self, which='major', reset=False, **kwargs):
+        """
+        Set appearance parameters for ticks, ticklabels, and gridlines.
+
+        For documentation of keyword arguments, see
+        :meth:`matplotlib.axes.Axes.tick_params`.
+
+        See Also
+        --------
+        .Axis.get_tick_params
+            View the current style settings for ticks, ticklabels, and
+            gridlines.
+        """
+        _api.check_in_list(['major', 'minor', 'both'], which=which)
+        kwtrans = self._translate_tick_params(kwargs)
+
+        # the kwargs are stored in self._major/minor_tick_kw so that any
+        # future new ticks will automatically get them
+        if reset:
+            if which in ['major', 'both']:
+                self._reset_major_tick_kw()
+                self._major_tick_kw.update(kwtrans)
+            if which in ['minor', 'both']:
+                self._reset_minor_tick_kw()
+                self._minor_tick_kw.update(kwtrans)
+            self.reset_ticks()
+        else:
+            if which in ['major', 'both']:
+                self._major_tick_kw.update(kwtrans)
+                for tick in self.majorTicks:
+                    tick._apply_params(**kwtrans)
+            if which in ['minor', 'both']:
+                self._minor_tick_kw.update(kwtrans)
+                for tick in self.minorTicks:
+                    tick._apply_params(**kwtrans)
+            # labelOn and labelcolor also apply to the offset text.
+            if 'label1On' in kwtrans or 'label2On' in kwtrans:
+                self.offsetText.set_visible(
+                    self._major_tick_kw.get('label1On', False)
+                    or self._major_tick_kw.get('label2On', False))
+            if 'labelcolor' in kwtrans:
+                self.offsetText.set_color(kwtrans['labelcolor'])
+
+        self.stale = True
+
+    def get_tick_params(self, which='major'):
+        """
+        Get appearance parameters for ticks, ticklabels, and gridlines.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        which : {'major', 'minor'}, default: 'major'
+            The group of ticks for which the parameters are retrieved.
+
+        Returns
+        -------
+        dict
+            Properties for styling tick elements added to the axis.
+
+        Notes
+        -----
+        This method returns the appearance parameters for styling *new*
+        elements added to this axis and may be different from the values
+        on current elements if they were modified directly by the user
+        (e.g., via ``set_*`` methods on individual tick objects).
+
+        Examples
+        --------
+        ::
+
+            >>> ax.yaxis.set_tick_params(labelsize=30, labelcolor='red',
+            ...                          direction='out', which='major')
+            >>> ax.yaxis.get_tick_params(which='major')
+            {'direction': 'out',
+            'left': True,
+            'right': False,
+            'labelleft': True,
+            'labelright': False,
+            'gridOn': False,
+            'labelsize': 30,
+            'labelcolor': 'red'}
+            >>> ax.yaxis.get_tick_params(which='minor')
+            {'left': True,
+            'right': False,
+            'labelleft': True,
+            'labelright': False,
+            'gridOn': False}
+
+
+        """
+        _api.check_in_list(['major', 'minor'], which=which)
+        if which == 'major':
+            return self._translate_tick_params(
+                self._major_tick_kw, reverse=True
+            )
+        return self._translate_tick_params(self._minor_tick_kw, reverse=True)
+
+    @classmethod
+    def _translate_tick_params(cls, kw, reverse=False):
+        """
+        Translate the kwargs supported by `.Axis.set_tick_params` to kwargs
+        supported by `.Tick._apply_params`.
+
+        In particular, this maps axis specific names like 'top', 'left'
+        to the generic tick1, tick2 logic of the axis. Additionally, there
+        are some other name translations.
+
+        Returns a new dict of translated kwargs.
+
+        Note: Use reverse=True to translate from those supported by
+        `.Tick._apply_params` back to those supported by
+        `.Axis.set_tick_params`.
+        """
+        kw_ = {**kw}
+
+        # The following lists may be moved to a more accessible location.
+        allowed_keys = [
+            'size', 'width', 'color', 'tickdir', 'pad',
+            'labelsize', 'labelcolor', 'labelfontfamily', 'zorder', 'gridOn',
+            'tick1On', 'tick2On', 'label1On', 'label2On',
+            'length', 'direction', 'left', 'bottom', 'right', 'top',
+            'labelleft', 'labelbottom', 'labelright', 'labeltop',
+            'labelrotation',
+            *_gridline_param_names]
+
+        keymap = {
+            # tick_params key -> axis key
+            'length': 'size',
+            'direction': 'tickdir',
+            'rotation': 'labelrotation',
+            'left': 'tick1On',
+            'bottom': 'tick1On',
+            'right': 'tick2On',
+            'top': 'tick2On',
+            'labelleft': 'label1On',
+            'labelbottom': 'label1On',
+            'labelright': 'label2On',
+            'labeltop': 'label2On',
+        }
+        if reverse:
+            kwtrans = {}
+            is_x_axis = cls.axis_name == 'x'
+            y_axis_keys = ['left', 'right', 'labelleft', 'labelright']
+            for oldkey, newkey in keymap.items():
+                if newkey in kw_:
+                    if is_x_axis and oldkey in y_axis_keys:
+                        continue
+                    else:
+                        kwtrans[oldkey] = kw_.pop(newkey)
+        else:
+            kwtrans = {
+                newkey: kw_.pop(oldkey)
+                for oldkey, newkey in keymap.items() if oldkey in kw_
+            }
+        if 'colors' in kw_:
+            c = kw_.pop('colors')
+            kwtrans['color'] = c
+            kwtrans['labelcolor'] = c
+        # Maybe move the checking up to the caller of this method.
+        for key in kw_:
+            if key not in allowed_keys:
+                raise ValueError(
+                    "keyword %s is not recognized; valid keywords are %s"
+                    % (key, allowed_keys))
+        kwtrans.update(kw_)
+        return kwtrans
+
+    def set_clip_path(self, path, transform=None):
+        super().set_clip_path(path, transform)
+        for child in self.majorTicks + self.minorTicks:
+            child.set_clip_path(path, transform)
+        self.stale = True
+
+    def get_view_interval(self):
+        """Return the ``(min, max)`` view limits of this axis."""
+        raise NotImplementedError('Derived must override')
+
+    def set_view_interval(self, vmin, vmax, ignore=False):
+        """
+        Set the axis view limits.  This method is for internal use; Matplotlib
+        users should typically use e.g. `~.Axes.set_xlim` or `~.Axes.set_ylim`.
+
+        If *ignore* is False (the default), this method will never reduce the
+        preexisting view limits, only expand them if *vmin* or *vmax* are not
+        within them.  Moreover, the order of *vmin* and *vmax* does not matter;
+        the orientation of the axis will not change.
+
+        If *ignore* is True, the view limits will be set exactly to ``(vmin,
+        vmax)`` in that order.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def get_data_interval(self):
+        """Return the ``(min, max)`` data limits of this axis."""
+        raise NotImplementedError('Derived must override')
+
+    def set_data_interval(self, vmin, vmax, ignore=False):
+        """
+        Set the axis data limits.  This method is for internal use.
+
+        If *ignore* is False (the default), this method will never reduce the
+        preexisting data limits, only expand them if *vmin* or *vmax* are not
+        within them.  Moreover, the order of *vmin* and *vmax* does not matter;
+        the orientation of the axis will not change.
+
+        If *ignore* is True, the data limits will be set exactly to ``(vmin,
+        vmax)`` in that order.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def get_inverted(self):
+        """
+        Return whether this Axis is oriented in the "inverse" direction.
+
+        The "normal" direction is increasing to the right for the x-axis and to
+        the top for the y-axis; the "inverse" direction is increasing to the
+        left for the x-axis and to the bottom for the y-axis.
+        """
+        low, high = self.get_view_interval()
+        return high < low
+
+    def set_inverted(self, inverted):
+        """
+        Set whether this Axis is oriented in the "inverse" direction.
+
+        The "normal" direction is increasing to the right for the x-axis and to
+        the top for the y-axis; the "inverse" direction is increasing to the
+        left for the x-axis and to the bottom for the y-axis.
+        """
+        a, b = self.get_view_interval()
+        # cast to bool to avoid bad interaction between python 3.8 and np.bool_
+        self._set_lim(*sorted((a, b), reverse=bool(inverted)), auto=None)
+
+    def set_default_intervals(self):
+        """
+        Set the default limits for the axis data and view interval if they
+        have not been not mutated yet.
+        """
+        # this is mainly in support of custom object plotting.  For
+        # example, if someone passes in a datetime object, we do not
+        # know automagically how to set the default min/max of the
+        # data and view limits.  The unit conversion AxisInfo
+        # interface provides a hook for custom types to register
+        # default limits through the AxisInfo.default_limits
+        # attribute, and the derived code below will check for that
+        # and use it if it's available (else just use 0..1)
+
+    def _set_lim(self, v0, v1, *, emit=True, auto):
+        """
+        Set view limits.
+
+        This method is a helper for the Axes ``set_xlim``, ``set_ylim``, and
+        ``set_zlim`` methods.
+
+        Parameters
+        ----------
+        v0, v1 : float
+            The view limits.  (Passing *v0* as a (low, high) pair is not
+            supported; normalization must occur in the Axes setters.)
+        emit : bool, default: True
+            Whether to notify observers of limit change.
+        auto : bool or None, default: False
+            Whether to turn on autoscaling of the x-axis. True turns on, False
+            turns off, None leaves unchanged.
+        """
+        name = self._get_axis_name()
+
+        self.axes._process_unit_info([(name, (v0, v1))], convert=False)
+        v0 = self.axes._validate_converted_limits(v0, self.convert_units)
+        v1 = self.axes._validate_converted_limits(v1, self.convert_units)
+
+        if v0 is None or v1 is None:
+            # Axes init calls set_xlim(0, 1) before get_xlim() can be called,
+            # so only grab the limits if we really need them.
+            old0, old1 = self.get_view_interval()
+            if v0 is None:
+                v0 = old0
+            if v1 is None:
+                v1 = old1
+
+        if self.get_scale() == 'log' and (v0 <= 0 or v1 <= 0):
+            # Axes init calls set_xlim(0, 1) before get_xlim() can be called,
+            # so only grab the limits if we really need them.
+            old0, old1 = self.get_view_interval()
+            if v0 <= 0:
+                _api.warn_external(f"Attempt to set non-positive {name}lim on "
+                                   f"a log-scaled axis will be ignored.")
+                v0 = old0
+            if v1 <= 0:
+                _api.warn_external(f"Attempt to set non-positive {name}lim on "
+                                   f"a log-scaled axis will be ignored.")
+                v1 = old1
+        if v0 == v1:
+            _api.warn_external(
+                f"Attempting to set identical low and high {name}lims "
+                f"makes transformation singular; automatically expanding.")
+        reverse = bool(v0 > v1)  # explicit cast needed for python3.8+np.bool_.
+        v0, v1 = self.get_major_locator().nonsingular(v0, v1)
+        v0, v1 = self.limit_range_for_scale(v0, v1)
+        v0, v1 = sorted([v0, v1], reverse=bool(reverse))
+
+        self.set_view_interval(v0, v1, ignore=True)
+        # Mark viewlims as no longer stale without triggering an autoscale.
+        for ax in self._get_shared_axes():
+            ax._stale_viewlims[name] = False
+        self._set_autoscale_on(auto)
+
+        if emit:
+            self.axes.callbacks.process(f"{name}lim_changed", self.axes)
+            # Call all of the other Axes that are shared with this one
+            for other in self._get_shared_axes():
+                if other is self.axes:
+                    continue
+                other._axis_map[name]._set_lim(v0, v1, emit=False, auto=auto)
+                if emit:
+                    other.callbacks.process(f"{name}lim_changed", other)
+                if ((other_fig := other.get_figure(root=False)) !=
+                        self.get_figure(root=False)):
+                    other_fig.canvas.draw_idle()
+
+        self.stale = True
+        return v0, v1
+
+    def _set_artist_props(self, a):
+        if a is None:
+            return
+        a.set_figure(self.get_figure(root=False))
+
+    def _update_ticks(self):
+        """
+        Update ticks (position and labels) using the current data interval of
+        the axes.  Return the list of ticks that will be drawn.
+        """
+        major_locs = self.get_majorticklocs()
+        major_labels = self.major.formatter.format_ticks(major_locs)
+        major_ticks = self.get_major_ticks(len(major_locs))
+        for tick, loc, label in zip(major_ticks, major_locs, major_labels):
+            tick.update_position(loc)
+            tick.label1.set_text(label)
+            tick.label2.set_text(label)
+        minor_locs = self.get_minorticklocs()
+        minor_labels = self.minor.formatter.format_ticks(minor_locs)
+        minor_ticks = self.get_minor_ticks(len(minor_locs))
+        for tick, loc, label in zip(minor_ticks, minor_locs, minor_labels):
+            tick.update_position(loc)
+            tick.label1.set_text(label)
+            tick.label2.set_text(label)
+        ticks = [*major_ticks, *minor_ticks]
+
+        view_low, view_high = self.get_view_interval()
+        if view_low > view_high:
+            view_low, view_high = view_high, view_low
+
+        if (hasattr(self, "axes") and self.axes.name == '3d'
+                and mpl.rcParams['axes3d.automargin']):
+            # In mpl3.8, the margin was 1/48. Due to the change in automargin
+            # behavior in mpl3.9, we need to adjust this to compensate for a
+            # zoom factor of 2/48, giving us a 23/24 modifier. So the new
+            # margin is 0.019965277777777776 = 1/48*23/24.
+            margin = 0.019965277777777776
+            delta = view_high - view_low
+            view_high = view_high - delta * margin
+            view_low = view_low + delta * margin
+
+        interval_t = self.get_transform().transform([view_low, view_high])
+
+        ticks_to_draw = []
+        for tick in ticks:
+            try:
+                loc_t = self.get_transform().transform(tick.get_loc())
+            except AssertionError:
+                # transforms.transform doesn't allow masked values but
+                # some scales might make them, so we need this try/except.
+                pass
+            else:
+                if mtransforms._interval_contains_close(interval_t, loc_t):
+                    ticks_to_draw.append(tick)
+
+        return ticks_to_draw
+
+    def _get_ticklabel_bboxes(self, ticks, renderer=None):
+        """Return lists of bboxes for ticks' label1's and label2's."""
+        if renderer is None:
+            renderer = self.get_figure(root=True)._get_renderer()
+        return ([tick.label1.get_window_extent(renderer)
+                 for tick in ticks if tick.label1.get_visible()],
+                [tick.label2.get_window_extent(renderer)
+                 for tick in ticks if tick.label2.get_visible()])
+
+    def get_tightbbox(self, renderer=None, *, for_layout_only=False):
+        """
+        Return a bounding box that encloses the axis. It only accounts
+        tick labels, axis label, and offsetText.
+
+        If *for_layout_only* is True, then the width of the label (if this
+        is an x-axis) or the height of the label (if this is a y-axis) is
+        collapsed to near zero.  This allows tight/constrained_layout to ignore
+        too-long labels when doing their layout.
+        """
+        if not self.get_visible() or for_layout_only and not self.get_in_layout():
+            return
+        if renderer is None:
+            renderer = self.get_figure(root=True)._get_renderer()
+        ticks_to_draw = self._update_ticks()
+
+        self._update_label_position(renderer)
+
+        # go back to just this axis's tick labels
+        tlb1, tlb2 = self._get_ticklabel_bboxes(ticks_to_draw, renderer)
+
+        self._update_offset_text_position(tlb1, tlb2)
+        self.offsetText.set_text(self.major.formatter.get_offset())
+
+        bboxes = [
+            *(a.get_window_extent(renderer)
+              for a in [self.offsetText]
+              if a.get_visible()),
+            *tlb1, *tlb2,
+        ]
+        # take care of label
+        if self.label.get_visible():
+            bb = self.label.get_window_extent(renderer)
+            # for constrained/tight_layout, we want to ignore the label's
+            # width/height because the adjustments they make can't be improved.
+            # this code collapses the relevant direction
+            if for_layout_only:
+                if self.axis_name == "x" and bb.width > 0:
+                    bb.x0 = (bb.x0 + bb.x1) / 2 - 0.5
+                    bb.x1 = bb.x0 + 1.0
+                if self.axis_name == "y" and bb.height > 0:
+                    bb.y0 = (bb.y0 + bb.y1) / 2 - 0.5
+                    bb.y1 = bb.y0 + 1.0
+            bboxes.append(bb)
+        bboxes = [b for b in bboxes
+                  if 0 < b.width < np.inf and 0 < b.height < np.inf]
+        if bboxes:
+            return mtransforms.Bbox.union(bboxes)
+        else:
+            return None
+
+    def get_tick_padding(self):
+        values = []
+        if len(self.majorTicks):
+            values.append(self.majorTicks[0].get_tick_padding())
+        if len(self.minorTicks):
+            values.append(self.minorTicks[0].get_tick_padding())
+        return max(values, default=0)
+
+    @martist.allow_rasterization
+    def draw(self, renderer):
+        # docstring inherited
+
+        if not self.get_visible():
+            return
+        renderer.open_group(__name__, gid=self.get_gid())
+
+        ticks_to_draw = self._update_ticks()
+        tlb1, tlb2 = self._get_ticklabel_bboxes(ticks_to_draw, renderer)
+
+        for tick in ticks_to_draw:
+            tick.draw(renderer)
+
+        # Shift label away from axes to avoid overlapping ticklabels.
+        self._update_label_position(renderer)
+        self.label.draw(renderer)
+
+        self._update_offset_text_position(tlb1, tlb2)
+        self.offsetText.set_text(self.major.formatter.get_offset())
+        self.offsetText.draw(renderer)
+
+        renderer.close_group(__name__)
+        self.stale = False
+
+    def get_gridlines(self):
+        r"""Return this Axis' grid lines as a list of `.Line2D`\s."""
+        ticks = self.get_major_ticks()
+        return cbook.silent_list('Line2D gridline',
+                                 [tick.gridline for tick in ticks])
+
+    def set_label(self, s):
+        """Assigning legend labels is not supported. Raises RuntimeError."""
+        raise RuntimeError(
+            "A legend label cannot be assigned to an Axis. Did you mean to "
+            "set the axis label via set_label_text()?")
+
+    def get_label(self):
+        """
+        Return the axis label as a Text instance.
+
+        .. admonition:: Discouraged
+
+           This overrides `.Artist.get_label`, which is for legend labels, with a new
+           semantic. It is recommended to use the attribute ``Axis.label`` instead.
+        """
+        return self.label
+
+    def get_offset_text(self):
+        """Return the axis offsetText as a Text instance."""
+        return self.offsetText
+
+    def get_pickradius(self):
+        """Return the depth of the axis used by the picker."""
+        return self._pickradius
+
+    def get_majorticklabels(self):
+        """Return this Axis' major tick labels, as a list of `~.text.Text`."""
+        self._update_ticks()
+        ticks = self.get_major_ticks()
+        labels1 = [tick.label1 for tick in ticks if tick.label1.get_visible()]
+        labels2 = [tick.label2 for tick in ticks if tick.label2.get_visible()]
+        return labels1 + labels2
+
+    def get_minorticklabels(self):
+        """Return this Axis' minor tick labels, as a list of `~.text.Text`."""
+        self._update_ticks()
+        ticks = self.get_minor_ticks()
+        labels1 = [tick.label1 for tick in ticks if tick.label1.get_visible()]
+        labels2 = [tick.label2 for tick in ticks if tick.label2.get_visible()]
+        return labels1 + labels2
+
+    def get_ticklabels(self, minor=False, which=None):
+        """
+        Get this Axis' tick labels.
+
+        Parameters
+        ----------
+        minor : bool
+           Whether to return the minor or the major ticklabels.
+
+        which : None, ('minor', 'major', 'both')
+           Overrides *minor*.
+
+           Selects which ticklabels to return
+
+        Returns
+        -------
+        list of `~matplotlib.text.Text`
+        """
+        if which is not None:
+            if which == 'minor':
+                return self.get_minorticklabels()
+            elif which == 'major':
+                return self.get_majorticklabels()
+            elif which == 'both':
+                return self.get_majorticklabels() + self.get_minorticklabels()
+            else:
+                _api.check_in_list(['major', 'minor', 'both'], which=which)
+        if minor:
+            return self.get_minorticklabels()
+        return self.get_majorticklabels()
+
+    def get_majorticklines(self):
+        r"""Return this Axis' major tick lines as a list of `.Line2D`\s."""
+        lines = []
+        ticks = self.get_major_ticks()
+        for tick in ticks:
+            lines.append(tick.tick1line)
+            lines.append(tick.tick2line)
+        return cbook.silent_list('Line2D ticklines', lines)
+
+    def get_minorticklines(self):
+        r"""Return this Axis' minor tick lines as a list of `.Line2D`\s."""
+        lines = []
+        ticks = self.get_minor_ticks()
+        for tick in ticks:
+            lines.append(tick.tick1line)
+            lines.append(tick.tick2line)
+        return cbook.silent_list('Line2D ticklines', lines)
+
+    def get_ticklines(self, minor=False):
+        r"""Return this Axis' tick lines as a list of `.Line2D`\s."""
+        if minor:
+            return self.get_minorticklines()
+        return self.get_majorticklines()
+
+    def get_majorticklocs(self):
+        """Return this Axis' major tick locations in data coordinates."""
+        return self.major.locator()
+
+    def get_minorticklocs(self):
+        """Return this Axis' minor tick locations in data coordinates."""
+        # Remove minor ticks duplicating major ticks.
+        minor_locs = np.asarray(self.minor.locator())
+        if self.remove_overlapping_locs:
+            major_locs = self.major.locator()
+            transform = self._scale.get_transform()
+            tr_minor_locs = transform.transform(minor_locs)
+            tr_major_locs = transform.transform(major_locs)
+            lo, hi = sorted(transform.transform(self.get_view_interval()))
+            # Use the transformed view limits as scale.  1e-5 is the default
+            # rtol for np.isclose.
+            tol = (hi - lo) * 1e-5
+            mask = np.isclose(tr_minor_locs[:, None], tr_major_locs[None, :],
+                              atol=tol, rtol=0).any(axis=1)
+            minor_locs = minor_locs[~mask]
+        return minor_locs
+
+    def get_ticklocs(self, *, minor=False):
+        """
+        Return this Axis' tick locations in data coordinates.
+
+        The locations are not clipped to the current axis limits and hence
+        may contain locations that are not visible in the output.
+
+        Parameters
+        ----------
+        minor : bool, default: False
+            True to return the minor tick directions,
+            False to return the major tick directions.
+
+        Returns
+        -------
+        array of tick locations
+        """
+        return self.get_minorticklocs() if minor else self.get_majorticklocs()
+
+    def get_ticks_direction(self, minor=False):
+        """
+        Return an array of this Axis' tick directions.
+
+        Parameters
+        ----------
+        minor : bool, default: False
+            True to return the minor tick directions,
+            False to return the major tick directions.
+
+        Returns
+        -------
+        array of tick directions
+        """
+        if minor:
+            return np.array(
+                [tick._tickdir for tick in self.get_minor_ticks()])
+        else:
+            return np.array(
+                [tick._tickdir for tick in self.get_major_ticks()])
+
+    def _get_tick(self, major):
+        """Return the default tick instance."""
+        if self._tick_class is None:
+            raise NotImplementedError(
+                f"The Axis subclass {self.__class__.__name__} must define "
+                "_tick_class or reimplement _get_tick()")
+        tick_kw = self._major_tick_kw if major else self._minor_tick_kw
+        return self._tick_class(self.axes, 0, major=major, **tick_kw)
+
+    def _get_tick_label_size(self, axis_name):
+        """
+        Return the text size of tick labels for this Axis.
+
+        This is a convenience function to avoid having to create a `Tick` in
+        `.get_tick_space`, since it is expensive.
+        """
+        tick_kw = self._major_tick_kw
+        size = tick_kw.get('labelsize',
+                           mpl.rcParams[f'{axis_name}tick.labelsize'])
+        return mtext.FontProperties(size=size).get_size_in_points()
+
+    def _copy_tick_props(self, src, dest):
+        """Copy the properties from *src* tick to *dest* tick."""
+        if src is None or dest is None:
+            return
+        dest.label1.update_from(src.label1)
+        dest.label2.update_from(src.label2)
+        dest.tick1line.update_from(src.tick1line)
+        dest.tick2line.update_from(src.tick2line)
+        dest.gridline.update_from(src.gridline)
+        dest.update_from(src)
+        dest._loc = src._loc
+        dest._size = src._size
+        dest._width = src._width
+        dest._base_pad = src._base_pad
+        dest._labelrotation = src._labelrotation
+        dest._zorder = src._zorder
+        dest._tickdir = src._tickdir
+
+    def get_label_text(self):
+        """Get the text of the label."""
+        return self.label.get_text()
+
+    def get_major_locator(self):
+        """Get the locator of the major ticker."""
+        return self.major.locator
+
+    def get_minor_locator(self):
+        """Get the locator of the minor ticker."""
+        return self.minor.locator
+
+    def get_major_formatter(self):
+        """Get the formatter of the major ticker."""
+        return self.major.formatter
+
+    def get_minor_formatter(self):
+        """Get the formatter of the minor ticker."""
+        return self.minor.formatter
+
+    def get_major_ticks(self, numticks=None):
+        r"""
+        Return the list of major `.Tick`\s.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+        """
+        if numticks is None:
+            numticks = len(self.get_majorticklocs())
+
+        while len(self.majorTicks) < numticks:
+            # Update the new tick label properties from the old.
+            tick = self._get_tick(major=True)
+            self.majorTicks.append(tick)
+            self._copy_tick_props(self.majorTicks[0], tick)
+
+        return self.majorTicks[:numticks]
+
+    def get_minor_ticks(self, numticks=None):
+        r"""
+        Return the list of minor `.Tick`\s.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+        """
+        if numticks is None:
+            numticks = len(self.get_minorticklocs())
+
+        while len(self.minorTicks) < numticks:
+            # Update the new tick label properties from the old.
+            tick = self._get_tick(major=False)
+            self.minorTicks.append(tick)
+            self._copy_tick_props(self.minorTicks[0], tick)
+
+        return self.minorTicks[:numticks]
+
+    def grid(self, visible=None, which='major', **kwargs):
+        """
+        Configure the grid lines.
+
+        Parameters
+        ----------
+        visible : bool or None
+            Whether to show the grid lines.  If any *kwargs* are supplied, it
+            is assumed you want the grid on and *visible* will be set to True.
+
+            If *visible* is *None* and there are no *kwargs*, this toggles the
+            visibility of the lines.
+
+        which : {'major', 'minor', 'both'}
+            The grid lines to apply the changes on.
+
+        **kwargs : `~matplotlib.lines.Line2D` properties
+            Define the line properties of the grid, e.g.::
+
+                grid(color='r', linestyle='-', linewidth=2)
+        """
+        if kwargs:
+            if visible is None:
+                visible = True
+            elif not visible:  # something false-like but not None
+                _api.warn_external('First parameter to grid() is false, '
+                                   'but line properties are supplied. The '
+                                   'grid will be enabled.')
+                visible = True
+        which = which.lower()
+        _api.check_in_list(['major', 'minor', 'both'], which=which)
+        gridkw = {f'grid_{name}': value for name, value in kwargs.items()}
+        if which in ['minor', 'both']:
+            gridkw['gridOn'] = (not self._minor_tick_kw['gridOn']
+                                if visible is None else visible)
+            self.set_tick_params(which='minor', **gridkw)
+        if which in ['major', 'both']:
+            gridkw['gridOn'] = (not self._major_tick_kw['gridOn']
+                                if visible is None else visible)
+            self.set_tick_params(which='major', **gridkw)
+        self.stale = True
+
+    def update_units(self, data):
+        """
+        Introspect *data* for units converter and update the
+        ``axis.get_converter`` instance if necessary. Return *True*
+        if *data* is registered for unit conversion.
+        """
+        if not self._converter_is_explicit:
+            converter = munits.registry.get_converter(data)
+        else:
+            converter = self._converter
+
+        if converter is None:
+            return False
+
+        neednew = self._converter != converter
+        self._set_converter(converter)
+        default = self._converter.default_units(data, self)
+        if default is not None and self.units is None:
+            self.set_units(default)
+
+        elif neednew:
+            self._update_axisinfo()
+        self.stale = True
+        return True
+
+    def _update_axisinfo(self):
+        """
+        Check the axis converter for the stored units to see if the
+        axis info needs to be updated.
+        """
+        if self._converter is None:
+            return
+
+        info = self._converter.axisinfo(self.units, self)
+
+        if info is None:
+            return
+        if info.majloc is not None and \
+           self.major.locator != info.majloc and self.isDefault_majloc:
+            self.set_major_locator(info.majloc)
+            self.isDefault_majloc = True
+        if info.minloc is not None and \
+           self.minor.locator != info.minloc and self.isDefault_minloc:
+            self.set_minor_locator(info.minloc)
+            self.isDefault_minloc = True
+        if info.majfmt is not None and \
+           self.major.formatter != info.majfmt and self.isDefault_majfmt:
+            self.set_major_formatter(info.majfmt)
+            self.isDefault_majfmt = True
+        if info.minfmt is not None and \
+           self.minor.formatter != info.minfmt and self.isDefault_minfmt:
+            self.set_minor_formatter(info.minfmt)
+            self.isDefault_minfmt = True
+        if info.label is not None and self.isDefault_label:
+            self.set_label_text(info.label)
+            self.isDefault_label = True
+
+        self.set_default_intervals()
+
+    def have_units(self):
+        return self._converter is not None or self.units is not None
+
+    def convert_units(self, x):
+        # If x is natively supported by Matplotlib, doesn't need converting
+        if munits._is_natively_supported(x):
+            return x
+
+        if self._converter is None:
+            self._set_converter(munits.registry.get_converter(x))
+
+        if self._converter is None:
+            return x
+        try:
+            ret = self._converter.convert(x, self.units, self)
+        except Exception as e:
+            raise munits.ConversionError('Failed to convert value(s) to axis '
+                                         f'units: {x!r}') from e
+        return ret
+
+    def get_converter(self):
+        """
+        Get the unit converter for axis.
+
+        Returns
+        -------
+        `~matplotlib.units.ConversionInterface` or None
+        """
+        return self._converter
+
+    def set_converter(self, converter):
+        """
+        Set the unit converter for axis.
+
+        Parameters
+        ----------
+        converter : `~matplotlib.units.ConversionInterface`
+        """
+        self._set_converter(converter)
+        self._converter_is_explicit = True
+
+    def _set_converter(self, converter):
+        if self._converter is converter or self._converter == converter:
+            return
+        if self._converter_is_explicit:
+            raise RuntimeError("Axis already has an explicit converter set")
+        elif (
+            self._converter is not None and
+            not isinstance(converter, type(self._converter)) and
+            not isinstance(self._converter, type(converter))
+        ):
+            _api.warn_external(
+                "This axis already has a converter set and "
+                "is updating to a potentially incompatible converter"
+            )
+        self._converter = converter
+
+    def set_units(self, u):
+        """
+        Set the units for axis.
+
+        Parameters
+        ----------
+        u : units tag
+
+        Notes
+        -----
+        The units of any shared axis will also be updated.
+        """
+        if u == self.units:
+            return
+        for axis in self._get_shared_axis():
+            axis.units = u
+            axis._update_axisinfo()
+            axis.callbacks.process('units')
+            axis.stale = True
+
+    def get_units(self):
+        """Return the units for axis."""
+        return self.units
+
+    def set_label_text(self, label, fontdict=None, **kwargs):
+        """
+        Set the text value of the axis label.
+
+        Parameters
+        ----------
+        label : str
+            Text string.
+        fontdict : dict
+            Text properties.
+
+            .. admonition:: Discouraged
+
+               The use of *fontdict* is discouraged. Parameters should be passed as
+               individual keyword arguments or using dictionary-unpacking
+               ``set_label_text(..., **fontdict)``.
+
+        **kwargs
+            Merged into fontdict.
+        """
+        self.isDefault_label = False
+        self.label.set_text(label)
+        if fontdict is not None:
+            self.label.update(fontdict)
+        self.label.update(kwargs)
+        self.stale = True
+        return self.label
+
+    def set_major_formatter(self, formatter):
+        """
+        Set the formatter of the major ticker.
+
+        In addition to a `~matplotlib.ticker.Formatter` instance,
+        this also accepts a ``str`` or function.
+
+        For a ``str`` a `~matplotlib.ticker.StrMethodFormatter` is used.
+        The field used for the value must be labeled ``'x'`` and the field used
+        for the position must be labeled ``'pos'``.
+        See the  `~matplotlib.ticker.StrMethodFormatter` documentation for
+        more information.
+
+        For a function, a `~matplotlib.ticker.FuncFormatter` is used.
+        The function must take two inputs (a tick value ``x`` and a
+        position ``pos``), and return a string containing the corresponding
+        tick label.
+        See the  `~matplotlib.ticker.FuncFormatter` documentation for
+        more information.
+
+        Parameters
+        ----------
+        formatter : `~matplotlib.ticker.Formatter`, ``str``, or function
+        """
+        self._set_formatter(formatter, self.major)
+
+    def set_minor_formatter(self, formatter):
+        """
+        Set the formatter of the minor ticker.
+
+        In addition to a `~matplotlib.ticker.Formatter` instance,
+        this also accepts a ``str`` or function.
+        See `.Axis.set_major_formatter` for more information.
+
+        Parameters
+        ----------
+        formatter : `~matplotlib.ticker.Formatter`, ``str``, or function
+        """
+        self._set_formatter(formatter, self.minor)
+
+    def _set_formatter(self, formatter, level):
+        if isinstance(formatter, str):
+            formatter = mticker.StrMethodFormatter(formatter)
+        # Don't allow any other TickHelper to avoid easy-to-make errors,
+        # like using a Locator instead of a Formatter.
+        elif (callable(formatter) and
+              not isinstance(formatter, mticker.TickHelper)):
+            formatter = mticker.FuncFormatter(formatter)
+        else:
+            _api.check_isinstance(mticker.Formatter, formatter=formatter)
+
+        if (isinstance(formatter, mticker.FixedFormatter)
+                and len(formatter.seq) > 0
+                and not isinstance(level.locator, mticker.FixedLocator)):
+            _api.warn_external('FixedFormatter should only be used together '
+                               'with FixedLocator')
+
+        if level == self.major:
+            self.isDefault_majfmt = False
+        else:
+            self.isDefault_minfmt = False
+
+        level.formatter = formatter
+        formatter.set_axis(self)
+        self.stale = True
+
+    def set_major_locator(self, locator):
+        """
+        Set the locator of the major ticker.
+
+        Parameters
+        ----------
+        locator : `~matplotlib.ticker.Locator`
+        """
+        _api.check_isinstance(mticker.Locator, locator=locator)
+        self.isDefault_majloc = False
+        self.major.locator = locator
+        if self.major.formatter:
+            self.major.formatter._set_locator(locator)
+        locator.set_axis(self)
+        self.stale = True
+
+    def set_minor_locator(self, locator):
+        """
+        Set the locator of the minor ticker.
+
+        Parameters
+        ----------
+        locator : `~matplotlib.ticker.Locator`
+        """
+        _api.check_isinstance(mticker.Locator, locator=locator)
+        self.isDefault_minloc = False
+        self.minor.locator = locator
+        if self.minor.formatter:
+            self.minor.formatter._set_locator(locator)
+        locator.set_axis(self)
+        self.stale = True
+
+    def set_pickradius(self, pickradius):
+        """
+        Set the depth of the axis used by the picker.
+
+        Parameters
+        ----------
+        pickradius : float
+            The acceptance radius for containment tests.
+            See also `.Axis.contains`.
+        """
+        if not isinstance(pickradius, Real) or pickradius < 0:
+            raise ValueError("pick radius should be a distance")
+        self._pickradius = pickradius
+
+    pickradius = property(
+        get_pickradius, set_pickradius, doc="The acceptance radius for "
+        "containment tests. See also `.Axis.contains`.")
+
+    # Helper for set_ticklabels. Defining it here makes it picklable.
+    @staticmethod
+    def _format_with_dict(tickd, x, pos):
+        return tickd.get(x, "")
+
+    def set_ticklabels(self, labels, *, minor=False, fontdict=None, **kwargs):
+        r"""
+        [*Discouraged*] Set this Axis' tick labels with list of string labels.
+
+        .. admonition:: Discouraged
+
+            The use of this method is discouraged, because of the dependency on
+            tick positions. In most cases, you'll want to use
+            ``Axes.set_[x/y/z]ticks(positions, labels)`` or ``Axis.set_ticks``
+            instead.
+
+            If you are using this method, you should always fix the tick
+            positions before, e.g. by using `.Axis.set_ticks` or by explicitly
+            setting a `~.ticker.FixedLocator`. Otherwise, ticks are free to
+            move and the labels may end up in unexpected positions.
+
+        Parameters
+        ----------
+        labels : sequence of str or of `.Text`\s
+            Texts for labeling each tick location in the sequence set by
+            `.Axis.set_ticks`; the number of labels must match the number of locations.
+            The labels are used as is, via a `.FixedFormatter` (without further
+            formatting).
+
+        minor : bool
+            If True, set minor ticks instead of major ticks.
+
+        fontdict : dict, optional
+
+            .. admonition:: Discouraged
+
+               The use of *fontdict* is discouraged. Parameters should be passed as
+               individual keyword arguments or using dictionary-unpacking
+               ``set_ticklabels(..., **fontdict)``.
+
+            A dictionary controlling the appearance of the ticklabels.
+            The default *fontdict* is::
+
+               {'fontsize': rcParams['axes.titlesize'],
+                'fontweight': rcParams['axes.titleweight'],
+                'verticalalignment': 'baseline',
+                'horizontalalignment': loc}
+
+        **kwargs
+            Text properties.
+
+            .. warning::
+
+                This only sets the properties of the current ticks, which is
+                only sufficient for static plots.
+
+                Ticks are not guaranteed to be persistent. Various operations
+                can create, delete and modify the Tick instances. There is an
+                imminent risk that these settings can get lost if you work on
+                the figure further (including also panning/zooming on a
+                displayed figure).
+
+                Use `.set_tick_params` instead if possible.
+
+        Returns
+        -------
+        list of `.Text`\s
+            For each tick, includes ``tick.label1`` if it is visible, then
+            ``tick.label2`` if it is visible, in that order.
+        """
+        try:
+            labels = [t.get_text() if hasattr(t, 'get_text') else t
+                      for t in labels]
+        except TypeError:
+            raise TypeError(f"{labels:=} must be a sequence") from None
+        locator = (self.get_minor_locator() if minor
+                   else self.get_major_locator())
+        if not labels:
+            # eg labels=[]:
+            formatter = mticker.NullFormatter()
+        elif isinstance(locator, mticker.FixedLocator):
+            # Passing [] as a list of labels is often used as a way to
+            # remove all tick labels, so only error for > 0 labels
+            if len(locator.locs) != len(labels) and len(labels) != 0:
+                raise ValueError(
+                    "The number of FixedLocator locations"
+                    f" ({len(locator.locs)}), usually from a call to"
+                    " set_ticks, does not match"
+                    f" the number of labels ({len(labels)}).")
+            tickd = {loc: lab for loc, lab in zip(locator.locs, labels)}
+            func = functools.partial(self._format_with_dict, tickd)
+            formatter = mticker.FuncFormatter(func)
+        else:
+            _api.warn_external(
+                 "set_ticklabels() should only be used with a fixed number of "
+                 "ticks, i.e. after set_ticks() or using a FixedLocator.")
+            formatter = mticker.FixedFormatter(labels)
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="FixedFormatter should only be used together with FixedLocator")
+            if minor:
+                self.set_minor_formatter(formatter)
+                locs = self.get_minorticklocs()
+                ticks = self.get_minor_ticks(len(locs))
+            else:
+                self.set_major_formatter(formatter)
+                locs = self.get_majorticklocs()
+                ticks = self.get_major_ticks(len(locs))
+
+        ret = []
+        if fontdict is not None:
+            kwargs.update(fontdict)
+        for pos, (loc, tick) in enumerate(zip(locs, ticks)):
+            tick.update_position(loc)
+            tick_label = formatter(loc, pos)
+            # deal with label1
+            tick.label1.set_text(tick_label)
+            tick.label1._internal_update(kwargs)
+            # deal with label2
+            tick.label2.set_text(tick_label)
+            tick.label2._internal_update(kwargs)
+            # only return visible tick labels
+            if tick.label1.get_visible():
+                ret.append(tick.label1)
+            if tick.label2.get_visible():
+                ret.append(tick.label2)
+
+        self.stale = True
+        return ret
+
+    def _set_tick_locations(self, ticks, *, minor=False):
+        # see docstring of set_ticks
+
+        # XXX if the user changes units, the information will be lost here
+        ticks = self.convert_units(ticks)
+        locator = mticker.FixedLocator(ticks)  # validate ticks early.
+        if len(ticks):
+            for axis in self._get_shared_axis():
+                # set_view_interval maintains any preexisting inversion.
+                axis.set_view_interval(min(ticks), max(ticks))
+        self.axes.stale = True
+        if minor:
+            self.set_minor_locator(locator)
+            return self.get_minor_ticks(len(ticks))
+        else:
+            self.set_major_locator(locator)
+            return self.get_major_ticks(len(ticks))
+
+    def set_ticks(self, ticks, labels=None, *, minor=False, **kwargs):
+        """
+        Set this Axis' tick locations and optionally tick labels.
+
+        If necessary, the view limits of the Axis are expanded so that all
+        given ticks are visible.
+
+        Parameters
+        ----------
+        ticks : 1D array-like
+            Array of tick locations (either floats or in axis units). The axis
+            `.Locator` is replaced by a `~.ticker.FixedLocator`.
+
+            Pass an empty list (``set_ticks([])``) to remove all ticks.
+
+            Some tick formatters will not label arbitrary tick positions;
+            e.g. log formatters only label decade ticks by default. In
+            such a case you can set a formatter explicitly on the axis
+            using `.Axis.set_major_formatter` or provide formatted
+            *labels* yourself.
+
+        labels : list of str, optional
+            Tick labels for each location in *ticks*; must have the same length as
+            *ticks*. If set, the labels are used as is, via a `.FixedFormatter`.
+            If not set, the labels are generated using the axis tick `.Formatter`.
+
+        minor : bool, default: False
+            If ``False``, set only the major ticks; if ``True``, only the minor ticks.
+
+        **kwargs
+            `.Text` properties for the labels. Using these is only allowed if
+            you pass *labels*. In other cases, please use `~.Axes.tick_params`.
+
+        Notes
+        -----
+        The mandatory expansion of the view limits is an intentional design
+        choice to prevent the surprise of a non-visible tick. If you need
+        other limits, you should set the limits explicitly after setting the
+        ticks.
+        """
+        if labels is None and kwargs:
+            first_key = next(iter(kwargs))
+            raise ValueError(
+                f"Incorrect use of keyword argument {first_key!r}. Keyword arguments "
+                "other than 'minor' modify the text labels and can only be used if "
+                "'labels' are passed as well.")
+        result = self._set_tick_locations(ticks, minor=minor)
+        if labels is not None:
+            self.set_ticklabels(labels, minor=minor, **kwargs)
+        return result
+
+    def _get_tick_boxes_siblings(self, renderer):
+        """
+        Get the bounding boxes for this `.axis` and its siblings
+        as set by `.Figure.align_xlabels` or  `.Figure.align_ylabels`.
+
+        By default, it just gets bboxes for *self*.
+        """
+        # Get the Grouper keeping track of x or y label groups for this figure.
+        name = self._get_axis_name()
+        if name not in self.get_figure(root=False)._align_label_groups:
+            return [], []
+        grouper = self.get_figure(root=False)._align_label_groups[name]
+        bboxes = []
+        bboxes2 = []
+        # If we want to align labels from other Axes:
+        for ax in grouper.get_siblings(self.axes):
+            axis = ax._axis_map[name]
+            ticks_to_draw = axis._update_ticks()
+            tlb, tlb2 = axis._get_ticklabel_bboxes(ticks_to_draw, renderer)
+            bboxes.extend(tlb)
+            bboxes2.extend(tlb2)
+        return bboxes, bboxes2
+
+    def _update_label_position(self, renderer):
+        """
+        Update the label position based on the bounding box enclosing
+        all the ticklabels and axis spine.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def _update_offset_text_position(self, bboxes, bboxes2):
+        """
+        Update the offset text position based on the sequence of bounding
+        boxes of all the ticklabels.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def axis_date(self, tz=None):
+        """
+        Set up axis ticks and labels to treat data along this Axis as dates.
+
+        Parameters
+        ----------
+        tz : str or `datetime.tzinfo`, default: :rc:`timezone`
+            The timezone used to create date labels.
+        """
+        # By providing a sample datetime instance with the desired timezone,
+        # the registered converter can be selected, and the "units" attribute,
+        # which is the timezone, can be set.
+        if isinstance(tz, str):
+            import dateutil.tz
+            tz = dateutil.tz.gettz(tz)
+        self.update_units(datetime.datetime(2009, 1, 1, 0, 0, 0, 0, tz))
+
+    def get_tick_space(self):
+        """Return the estimated number of ticks that can fit on the axis."""
+        # Must be overridden in the subclass
+        raise NotImplementedError()
+
+    def _get_ticks_position(self):
+        """
+        Helper for `XAxis.get_ticks_position` and `YAxis.get_ticks_position`.
+
+        Check the visibility of tick1line, label1, tick2line, and label2 on
+        the first major and the first minor ticks, and return
+
+        - 1 if only tick1line and label1 are visible (which corresponds to
+          "bottom" for the x-axis and "left" for the y-axis);
+        - 2 if only tick2line and label2 are visible (which corresponds to
+          "top" for the x-axis and "right" for the y-axis);
+        - "default" if only tick1line, tick2line and label1 are visible;
+        - "unknown" otherwise.
+        """
+        major = self.majorTicks[0]
+        minor = self.minorTicks[0]
+        if all(tick.tick1line.get_visible()
+               and not tick.tick2line.get_visible()
+               and tick.label1.get_visible()
+               and not tick.label2.get_visible()
+               for tick in [major, minor]):
+            return 1
+        elif all(tick.tick2line.get_visible()
+                 and not tick.tick1line.get_visible()
+                 and tick.label2.get_visible()
+                 and not tick.label1.get_visible()
+                 for tick in [major, minor]):
+            return 2
+        elif all(tick.tick1line.get_visible()
+                 and tick.tick2line.get_visible()
+                 and tick.label1.get_visible()
+                 and not tick.label2.get_visible()
+                 for tick in [major, minor]):
+            return "default"
+        else:
+            return "unknown"
+
+    def get_label_position(self):
+        """
+        Return the label position (top or bottom)
+        """
+        return self.label_position
+
+    def set_label_position(self, position):
+        """
+        Set the label position (top or bottom)
+
+        Parameters
+        ----------
+        position : {'top', 'bottom'}
+        """
+        raise NotImplementedError()
+
+    def get_minpos(self):
+        raise NotImplementedError()
+
+
+def _make_getset_interval(method_name, lim_name, attr_name):
+    """
+    Helper to generate ``get_{data,view}_interval`` and
+    ``set_{data,view}_interval`` implementations.
+    """
+
+    def getter(self):
+        # docstring inherited.
+        return getattr(getattr(self.axes, lim_name), attr_name)
+
+    def setter(self, vmin, vmax, ignore=False):
+        # docstring inherited.
+        if ignore:
+            setattr(getattr(self.axes, lim_name), attr_name, (vmin, vmax))
+        else:
+            oldmin, oldmax = getter(self)
+            if oldmin < oldmax:
+                setter(self, min(vmin, vmax, oldmin), max(vmin, vmax, oldmax),
+                       ignore=True)
+            else:
+                setter(self, max(vmin, vmax, oldmin), min(vmin, vmax, oldmax),
+                       ignore=True)
+        self.stale = True
+
+    getter.__name__ = f"get_{method_name}_interval"
+    setter.__name__ = f"set_{method_name}_interval"
+
+    return getter, setter
+
+
+class XAxis(Axis):
+    __name__ = 'xaxis'
+    axis_name = 'x'  #: Read-only name identifying the axis.
+    _tick_class = XTick
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._init()
+
+    def _init(self):
+        """
+        Initialize the label and offsetText instance values and
+        `label_position` / `offset_text_position`.
+        """
+        # x in axes coords, y in display coords (to be updated at draw time by
+        # _update_label_positions and _update_offset_text_position).
+        self.label.set(
+            x=0.5, y=0,
+            verticalalignment='top', horizontalalignment='center',
+            transform=mtransforms.blended_transform_factory(
+                self.axes.transAxes, mtransforms.IdentityTransform()),
+        )
+        self.label_position = 'bottom'
+
+        if mpl.rcParams['xtick.labelcolor'] == 'inherit':
+            tick_color = mpl.rcParams['xtick.color']
+        else:
+            tick_color = mpl.rcParams['xtick.labelcolor']
+
+        self.offsetText.set(
+            x=1, y=0,
+            verticalalignment='top', horizontalalignment='right',
+            transform=mtransforms.blended_transform_factory(
+                self.axes.transAxes, mtransforms.IdentityTransform()),
+            fontsize=mpl.rcParams['xtick.labelsize'],
+            color=tick_color
+        )
+        self.offset_text_position = 'bottom'
+
+    def contains(self, mouseevent):
+        """Test whether the mouse event occurred in the x-axis."""
+        if self._different_canvas(mouseevent):
+            return False, {}
+        x, y = mouseevent.x, mouseevent.y
+        try:
+            trans = self.axes.transAxes.inverted()
+            xaxes, yaxes = trans.transform((x, y))
+        except ValueError:
+            return False, {}
+        (l, b), (r, t) = self.axes.transAxes.transform([(0, 0), (1, 1)])
+        inaxis = 0 <= xaxes <= 1 and (
+            b - self._pickradius < y < b or
+            t < y < t + self._pickradius)
+        return inaxis, {}
+
+    def set_label_position(self, position):
+        """
+        Set the label position (top or bottom)
+
+        Parameters
+        ----------
+        position : {'top', 'bottom'}
+        """
+        self.label.set_verticalalignment(_api.check_getitem({
+            'top': 'baseline', 'bottom': 'top',
+        }, position=position))
+        self.label_position = position
+        self.stale = True
+
+    def _update_label_position(self, renderer):
+        """
+        Update the label position based on the bounding box enclosing
+        all the ticklabels and axis spine
+        """
+        if not self._autolabelpos:
+            return
+
+        # get bounding boxes for this axis and any siblings
+        # that have been set by `fig.align_xlabels()`
+        bboxes, bboxes2 = self._get_tick_boxes_siblings(renderer=renderer)
+        x, y = self.label.get_position()
+
+        if self.label_position == 'bottom':
+            # Union with extents of the bottom spine if present, of the axes otherwise.
+            bbox = mtransforms.Bbox.union([
+                *bboxes, self.axes.spines.get("bottom", self.axes).get_window_extent()])
+            self.label.set_position(
+                (x, bbox.y0 - self.labelpad * self.get_figure(root=True).dpi / 72))
+        else:
+            # Union with extents of the top spine if present, of the axes otherwise.
+            bbox = mtransforms.Bbox.union([
+                *bboxes2, self.axes.spines.get("top", self.axes).get_window_extent()])
+            self.label.set_position(
+                (x, bbox.y1 + self.labelpad * self.get_figure(root=True).dpi / 72))
+
+    def _update_offset_text_position(self, bboxes, bboxes2):
+        """
+        Update the offset_text position based on the sequence of bounding
+        boxes of all the ticklabels
+        """
+        x, y = self.offsetText.get_position()
+        if not hasattr(self, '_tick_position'):
+            self._tick_position = 'bottom'
+        if self._tick_position == 'bottom':
+            if not len(bboxes):
+                bottom = self.axes.bbox.ymin
+            else:
+                bbox = mtransforms.Bbox.union(bboxes)
+                bottom = bbox.y0
+            y = bottom - self.OFFSETTEXTPAD * self.get_figure(root=True).dpi / 72
+        else:
+            if not len(bboxes2):
+                top = self.axes.bbox.ymax
+            else:
+                bbox = mtransforms.Bbox.union(bboxes2)
+                top = bbox.y1
+            y = top + self.OFFSETTEXTPAD * self.get_figure(root=True).dpi / 72
+        self.offsetText.set_position((x, y))
+
+    def set_ticks_position(self, position):
+        """
+        Set the ticks position.
+
+        Parameters
+        ----------
+        position : {'top', 'bottom', 'both', 'default', 'none'}
+            'both' sets the ticks to appear on both positions, but does not
+            change the tick labels.  'default' resets the tick positions to
+            the default: ticks on both positions, labels at bottom.  'none'
+            can be used if you don't want any ticks. 'none' and 'both'
+            affect only the ticks, not the labels.
+        """
+        if position == 'top':
+            self.set_tick_params(which='both', top=True, labeltop=True,
+                                 bottom=False, labelbottom=False)
+            self._tick_position = 'top'
+            self.offsetText.set_verticalalignment('bottom')
+        elif position == 'bottom':
+            self.set_tick_params(which='both', top=False, labeltop=False,
+                                 bottom=True, labelbottom=True)
+            self._tick_position = 'bottom'
+            self.offsetText.set_verticalalignment('top')
+        elif position == 'both':
+            self.set_tick_params(which='both', top=True,
+                                 bottom=True)
+        elif position == 'none':
+            self.set_tick_params(which='both', top=False,
+                                 bottom=False)
+        elif position == 'default':
+            self.set_tick_params(which='both', top=True, labeltop=False,
+                                 bottom=True, labelbottom=True)
+            self._tick_position = 'bottom'
+            self.offsetText.set_verticalalignment('top')
+        else:
+            _api.check_in_list(['top', 'bottom', 'both', 'default', 'none'],
+                               position=position)
+        self.stale = True
+
+    def tick_top(self):
+        """
+        Move ticks and ticklabels (if present) to the top of the Axes.
+        """
+        label = True
+        if 'label1On' in self._major_tick_kw:
+            label = (self._major_tick_kw['label1On']
+                     or self._major_tick_kw['label2On'])
+        self.set_ticks_position('top')
+        # If labels were turned off before this was called, leave them off.
+        self.set_tick_params(which='both', labeltop=label)
+
+    def tick_bottom(self):
+        """
+        Move ticks and ticklabels (if present) to the bottom of the Axes.
+        """
+        label = True
+        if 'label1On' in self._major_tick_kw:
+            label = (self._major_tick_kw['label1On']
+                     or self._major_tick_kw['label2On'])
+        self.set_ticks_position('bottom')
+        # If labels were turned off before this was called, leave them off.
+        self.set_tick_params(which='both', labelbottom=label)
+
+    def get_ticks_position(self):
+        """
+        Return the ticks position ("top", "bottom", "default", or "unknown").
+        """
+        return {1: "bottom", 2: "top",
+                "default": "default", "unknown": "unknown"}[
+                    self._get_ticks_position()]
+
+    get_view_interval, set_view_interval = _make_getset_interval(
+        "view", "viewLim", "intervalx")
+    get_data_interval, set_data_interval = _make_getset_interval(
+        "data", "dataLim", "intervalx")
+
+    def get_minpos(self):
+        return self.axes.dataLim.minposx
+
+    def set_default_intervals(self):
+        # docstring inherited
+        # only change view if dataLim has not changed and user has
+        # not changed the view:
+        if (not self.axes.dataLim.mutatedx() and
+                not self.axes.viewLim.mutatedx()):
+            if self._converter is not None:
+                info = self._converter.axisinfo(self.units, self)
+                if info.default_limits is not None:
+                    xmin, xmax = self.convert_units(info.default_limits)
+                    self.axes.viewLim.intervalx = xmin, xmax
+        self.stale = True
+
+    def get_tick_space(self):
+        ends = mtransforms.Bbox.unit().transformed(
+            self.axes.transAxes - self.get_figure(root=False).dpi_scale_trans)
+        length = ends.width * 72
+        # There is a heuristic here that the aspect ratio of tick text
+        # is no more than 3:1
+        size = self._get_tick_label_size('x') * 3
+        if size > 0:
+            return int(np.floor(length / size))
+        else:
+            return 2**31 - 1
+
+
+class YAxis(Axis):
+    __name__ = 'yaxis'
+    axis_name = 'y'  #: Read-only name identifying the axis.
+    _tick_class = YTick
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._init()
+
+    def _init(self):
+        """
+        Initialize the label and offsetText instance values and
+        `label_position` / `offset_text_position`.
+        """
+        # x in display coords, y in axes coords (to be updated at draw time by
+        # _update_label_positions and _update_offset_text_position).
+        self.label.set(
+            x=0, y=0.5,
+            verticalalignment='bottom', horizontalalignment='center',
+            rotation='vertical', rotation_mode='anchor',
+            transform=mtransforms.blended_transform_factory(
+                mtransforms.IdentityTransform(), self.axes.transAxes),
+        )
+        self.label_position = 'left'
+
+        if mpl.rcParams['ytick.labelcolor'] == 'inherit':
+            tick_color = mpl.rcParams['ytick.color']
+        else:
+            tick_color = mpl.rcParams['ytick.labelcolor']
+
+        # x in axes coords, y in display coords(!).
+        self.offsetText.set(
+            x=0, y=0.5,
+            verticalalignment='baseline', horizontalalignment='left',
+            transform=mtransforms.blended_transform_factory(
+                self.axes.transAxes, mtransforms.IdentityTransform()),
+            fontsize=mpl.rcParams['ytick.labelsize'],
+            color=tick_color
+        )
+        self.offset_text_position = 'left'
+
+    def contains(self, mouseevent):
+        # docstring inherited
+        if self._different_canvas(mouseevent):
+            return False, {}
+        x, y = mouseevent.x, mouseevent.y
+        try:
+            trans = self.axes.transAxes.inverted()
+            xaxes, yaxes = trans.transform((x, y))
+        except ValueError:
+            return False, {}
+        (l, b), (r, t) = self.axes.transAxes.transform([(0, 0), (1, 1)])
+        inaxis = 0 <= yaxes <= 1 and (
+            l - self._pickradius < x < l or
+            r < x < r + self._pickradius)
+        return inaxis, {}
+
+    def set_label_position(self, position):
+        """
+        Set the label position (left or right)
+
+        Parameters
+        ----------
+        position : {'left', 'right'}
+        """
+        self.label.set_rotation_mode('anchor')
+        self.label.set_verticalalignment(_api.check_getitem({
+            'left': 'bottom', 'right': 'top',
+        }, position=position))
+        self.label_position = position
+        self.stale = True
+
+    def _update_label_position(self, renderer):
+        """
+        Update the label position based on the bounding box enclosing
+        all the ticklabels and axis spine
+        """
+        if not self._autolabelpos:
+            return
+
+        # get bounding boxes for this axis and any siblings
+        # that have been set by `fig.align_ylabels()`
+        bboxes, bboxes2 = self._get_tick_boxes_siblings(renderer=renderer)
+        x, y = self.label.get_position()
+
+        if self.label_position == 'left':
+            # Union with extents of the left spine if present, of the axes otherwise.
+            bbox = mtransforms.Bbox.union([
+                *bboxes, self.axes.spines.get("left", self.axes).get_window_extent()])
+            self.label.set_position(
+                (bbox.x0 - self.labelpad * self.get_figure(root=True).dpi / 72, y))
+        else:
+            # Union with extents of the right spine if present, of the axes otherwise.
+            bbox = mtransforms.Bbox.union([
+                *bboxes2, self.axes.spines.get("right", self.axes).get_window_extent()])
+            self.label.set_position(
+                (bbox.x1 + self.labelpad * self.get_figure(root=True).dpi / 72, y))
+
+    def _update_offset_text_position(self, bboxes, bboxes2):
+        """
+        Update the offset_text position based on the sequence of bounding
+        boxes of all the ticklabels
+        """
+        x, _ = self.offsetText.get_position()
+        if 'outline' in self.axes.spines:
+            # Special case for colorbars:
+            bbox = self.axes.spines['outline'].get_window_extent()
+        else:
+            bbox = self.axes.bbox
+        top = bbox.ymax
+        self.offsetText.set_position(
+            (x, top + self.OFFSETTEXTPAD * self.get_figure(root=True).dpi / 72)
+        )
+
+    def set_offset_position(self, position):
+        """
+        Parameters
+        ----------
+        position : {'left', 'right'}
+        """
+        x, y = self.offsetText.get_position()
+        x = _api.check_getitem({'left': 0, 'right': 1}, position=position)
+
+        self.offsetText.set_ha(position)
+        self.offsetText.set_position((x, y))
+        self.stale = True
+
+    def set_ticks_position(self, position):
+        """
+        Set the ticks position.
+
+        Parameters
+        ----------
+        position : {'left', 'right', 'both', 'default', 'none'}
+            'both' sets the ticks to appear on both positions, but does not
+            change the tick labels.  'default' resets the tick positions to
+            the default: ticks on both positions, labels at left.  'none'
+            can be used if you don't want any ticks. 'none' and 'both'
+            affect only the ticks, not the labels.
+        """
+        if position == 'right':
+            self.set_tick_params(which='both', right=True, labelright=True,
+                                 left=False, labelleft=False)
+            self.set_offset_position(position)
+        elif position == 'left':
+            self.set_tick_params(which='both', right=False, labelright=False,
+                                 left=True, labelleft=True)
+            self.set_offset_position(position)
+        elif position == 'both':
+            self.set_tick_params(which='both', right=True,
+                                 left=True)
+        elif position == 'none':
+            self.set_tick_params(which='both', right=False,
+                                 left=False)
+        elif position == 'default':
+            self.set_tick_params(which='both', right=True, labelright=False,
+                                 left=True, labelleft=True)
+        else:
+            _api.check_in_list(['left', 'right', 'both', 'default', 'none'],
+                               position=position)
+        self.stale = True
+
+    def tick_right(self):
+        """
+        Move ticks and ticklabels (if present) to the right of the Axes.
+        """
+        label = True
+        if 'label1On' in self._major_tick_kw:
+            label = (self._major_tick_kw['label1On']
+                     or self._major_tick_kw['label2On'])
+        self.set_ticks_position('right')
+        # if labels were turned off before this was called
+        # leave them off
+        self.set_tick_params(which='both', labelright=label)
+
+    def tick_left(self):
+        """
+        Move ticks and ticklabels (if present) to the left of the Axes.
+        """
+        label = True
+        if 'label1On' in self._major_tick_kw:
+            label = (self._major_tick_kw['label1On']
+                     or self._major_tick_kw['label2On'])
+        self.set_ticks_position('left')
+        # if labels were turned off before this was called
+        # leave them off
+        self.set_tick_params(which='both', labelleft=label)
+
+    def get_ticks_position(self):
+        """
+        Return the ticks position ("left", "right", "default", or "unknown").
+        """
+        return {1: "left", 2: "right",
+                "default": "default", "unknown": "unknown"}[
+                    self._get_ticks_position()]
+
+    get_view_interval, set_view_interval = _make_getset_interval(
+        "view", "viewLim", "intervaly")
+    get_data_interval, set_data_interval = _make_getset_interval(
+        "data", "dataLim", "intervaly")
+
+    def get_minpos(self):
+        return self.axes.dataLim.minposy
+
+    def set_default_intervals(self):
+        # docstring inherited
+        # only change view if dataLim has not changed and user has
+        # not changed the view:
+        if (not self.axes.dataLim.mutatedy() and
+                not self.axes.viewLim.mutatedy()):
+            if self._converter is not None:
+                info = self._converter.axisinfo(self.units, self)
+                if info.default_limits is not None:
+                    ymin, ymax = self.convert_units(info.default_limits)
+                    self.axes.viewLim.intervaly = ymin, ymax
+        self.stale = True
+
+    def get_tick_space(self):
+        ends = mtransforms.Bbox.unit().transformed(
+            self.axes.transAxes - self.get_figure(root=False).dpi_scale_trans)
+        length = ends.height * 72
+        # Having a spacing of at least 2 just looks good.
+        size = self._get_tick_label_size('y') * 2
+        if size > 0:
+            return int(np.floor(length / size))
+        else:
+            return 2**31 - 1
diff --git a/lib/python3.12/site-packages/matplotlib/axis.pyi b/lib/python3.12/site-packages/matplotlib/axis.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..f2c5b1fc586d5a33237ace5ec264b6f6fde49080
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/axis.pyi
@@ -0,0 +1,280 @@
+from collections.abc import Callable, Iterable, Sequence
+import datetime
+from typing import Any, Literal, overload
+from typing_extensions import Self  # < Py 3.11
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+import matplotlib.artist as martist
+from matplotlib import cbook
+from matplotlib.axes import Axes
+from matplotlib.backend_bases import RendererBase
+from matplotlib.lines import Line2D
+from matplotlib.text import Text
+from matplotlib.ticker import Locator, Formatter
+from matplotlib.transforms import Transform, Bbox
+from matplotlib.typing import ColorType
+from matplotlib.units import ConversionInterface
+
+
+GRIDLINE_INTERPOLATION_STEPS: int
+
+class Tick(martist.Artist):
+    axes: Axes
+    tick1line: Line2D
+    tick2line: Line2D
+    gridline: Line2D
+    label1: Text
+    label2: Text
+    def __init__(
+        self,
+        axes: Axes,
+        loc: float,
+        *,
+        size: float | None = ...,
+        width: float | None = ...,
+        color: ColorType | None = ...,
+        tickdir: Literal["in", "inout", "out"] | None = ...,
+        pad: float | None = ...,
+        labelsize: float | None = ...,
+        labelcolor: ColorType | None = ...,
+        labelfontfamily: str | Sequence[str] | None = ...,
+        zorder: float | None = ...,
+        gridOn: bool | None = ...,
+        tick1On: bool = ...,
+        tick2On: bool = ...,
+        label1On: bool = ...,
+        label2On: bool = ...,
+        major: bool = ...,
+        labelrotation: float = ...,
+        grid_color: ColorType | None = ...,
+        grid_linestyle: str | None = ...,
+        grid_linewidth: float | None = ...,
+        grid_alpha: float | None = ...,
+        **kwargs
+    ) -> None: ...
+    def get_tickdir(self) -> Literal["in", "inout", "out"]: ...
+    def get_tick_padding(self) -> float: ...
+    def get_children(self) -> list[martist.Artist]: ...
+    stale: bool
+    def set_pad(self, val: float) -> None: ...
+    def get_pad(self) -> None: ...
+    def get_loc(self) -> float: ...
+    def set_url(self, url: str | None) -> None: ...
+    def get_view_interval(self) -> ArrayLike: ...
+    def update_position(self, loc: float) -> None: ...
+
+class XTick(Tick):
+    __name__: str
+    def __init__(self, *args, **kwargs) -> None: ...
+    stale: bool
+    def update_position(self, loc: float) -> None: ...
+    def get_view_interval(self) -> np.ndarray: ...
+
+class YTick(Tick):
+    __name__: str
+    def __init__(self, *args, **kwargs) -> None: ...
+    stale: bool
+    def update_position(self, loc: float) -> None: ...
+    def get_view_interval(self) -> np.ndarray: ...
+
+class Ticker:
+    def __init__(self) -> None: ...
+    @property
+    def locator(self) -> Locator | None: ...
+    @locator.setter
+    def locator(self, locator: Locator) -> None: ...
+    @property
+    def formatter(self) -> Formatter | None: ...
+    @formatter.setter
+    def formatter(self, formatter: Formatter) -> None: ...
+
+class _LazyTickList:
+    def __init__(self, major: bool) -> None: ...
+    @overload
+    def __get__(self, instance: None, owner: None) -> Self: ...
+    @overload
+    def __get__(self, instance: Axis, owner: type[Axis]) -> list[Tick]: ...
+
+class Axis(martist.Artist):
+    OFFSETTEXTPAD: int
+    isDefault_label: bool
+    axes: Axes
+    major: Ticker
+    minor: Ticker
+    callbacks: cbook.CallbackRegistry
+    label: Text
+    offsetText: Text
+    labelpad: float
+    pickradius: float
+    def __init__(self, axes, *, pickradius: float = ...,
+                 clear: bool = ...) -> None: ...
+    @property
+    def isDefault_majloc(self) -> bool: ...
+    @isDefault_majloc.setter
+    def isDefault_majloc(self, value: bool) -> None: ...
+    @property
+    def isDefault_majfmt(self) -> bool: ...
+    @isDefault_majfmt.setter
+    def isDefault_majfmt(self, value: bool) -> None: ...
+    @property
+    def isDefault_minloc(self) -> bool: ...
+    @isDefault_minloc.setter
+    def isDefault_minloc(self, value: bool) -> None: ...
+    @property
+    def isDefault_minfmt(self) -> bool: ...
+    @isDefault_minfmt.setter
+    def isDefault_minfmt(self, value: bool) -> None: ...
+    majorTicks: _LazyTickList
+    minorTicks: _LazyTickList
+    def get_remove_overlapping_locs(self) -> bool: ...
+    def set_remove_overlapping_locs(self, val: bool) -> None: ...
+    @property
+    def remove_overlapping_locs(self) -> bool: ...
+    @remove_overlapping_locs.setter
+    def remove_overlapping_locs(self, val: bool) -> None: ...
+    stale: bool
+    def set_label_coords(
+        self, x: float, y: float, transform: Transform | None = ...
+    ) -> None: ...
+    def get_transform(self) -> Transform: ...
+    def get_scale(self) -> str: ...
+    def limit_range_for_scale(
+        self, vmin: float, vmax: float
+    ) -> tuple[float, float]: ...
+    def get_children(self) -> list[martist.Artist]: ...
+    # TODO units
+    converter: Any
+    units: Any
+    def clear(self) -> None: ...
+    def reset_ticks(self) -> None: ...
+    def minorticks_on(self) -> None: ...
+    def minorticks_off(self) -> None: ...
+    def set_tick_params(
+        self,
+        which: Literal["major", "minor", "both"] = ...,
+        reset: bool = ...,
+        **kwargs
+    ) -> None: ...
+    def get_tick_params(
+        self, which: Literal["major", "minor"] = ...
+    ) -> dict[str, Any]: ...
+    def get_view_interval(self) -> tuple[float, float]: ...
+    def set_view_interval(
+        self, vmin: float, vmax: float, ignore: bool = ...
+    ) -> None: ...
+    def get_data_interval(self) -> tuple[float, float]: ...
+    def set_data_interval(
+        self, vmin: float, vmax: float, ignore: bool = ...
+    ) -> None: ...
+    def get_inverted(self) -> bool: ...
+    def set_inverted(self, inverted: bool) -> None: ...
+    def set_default_intervals(self) -> None: ...
+    def get_tightbbox(
+        self, renderer: RendererBase | None = ..., *, for_layout_only: bool = ...
+    ) -> Bbox | None: ...
+    def get_tick_padding(self) -> float: ...
+    def get_gridlines(self) -> list[Line2D]: ...
+    def get_label(self) -> Text: ...
+    def get_offset_text(self) -> Text: ...
+    def get_pickradius(self) -> float: ...
+    def get_majorticklabels(self) -> list[Text]: ...
+    def get_minorticklabels(self) -> list[Text]: ...
+    def get_ticklabels(
+        self, minor: bool = ..., which: Literal["major", "minor", "both"] | None = ...
+    ) -> list[Text]: ...
+    def get_majorticklines(self) -> list[Line2D]: ...
+    def get_minorticklines(self) -> list[Line2D]: ...
+    def get_ticklines(self, minor: bool = ...) -> list[Line2D]: ...
+    def get_majorticklocs(self) -> np.ndarray: ...
+    def get_minorticklocs(self) -> np.ndarray: ...
+    def get_ticklocs(self, *, minor: bool = ...) -> np.ndarray: ...
+    def get_ticks_direction(self, minor: bool = ...) -> np.ndarray: ...
+    def get_label_text(self) -> str: ...
+    def get_major_locator(self) -> Locator: ...
+    def get_minor_locator(self) -> Locator: ...
+    def get_major_formatter(self) -> Formatter: ...
+    def get_minor_formatter(self) -> Formatter: ...
+    def get_major_ticks(self, numticks: int | None = ...) -> list[Tick]: ...
+    def get_minor_ticks(self, numticks: int | None = ...) -> list[Tick]: ...
+    def grid(
+        self,
+        visible: bool | None = ...,
+        which: Literal["major", "minor", "both"] = ...,
+        **kwargs
+    ) -> None: ...
+    # TODO units
+    def update_units(self, data): ...
+    def have_units(self) -> bool: ...
+    def convert_units(self, x): ...
+    def get_converter(self) -> ConversionInterface | None: ...
+    def set_converter(self, converter: ConversionInterface) -> None: ...
+    def set_units(self, u) -> None: ...
+    def get_units(self): ...
+    def set_label_text(
+        self, label: str, fontdict: dict[str, Any] | None = ..., **kwargs
+    ) -> Text: ...
+    def set_major_formatter(
+        self, formatter: Formatter | str | Callable[[float, float], str]
+    ) -> None: ...
+    def set_minor_formatter(
+        self, formatter: Formatter | str | Callable[[float, float], str]
+    ) -> None: ...
+    def set_major_locator(self, locator: Locator) -> None: ...
+    def set_minor_locator(self, locator: Locator) -> None: ...
+    def set_pickradius(self, pickradius: float) -> None: ...
+    def set_ticklabels(
+        self,
+        labels: Iterable[str | Text],
+        *,
+        minor: bool = ...,
+        fontdict: dict[str, Any] | None = ...,
+        **kwargs
+    ) -> list[Text]: ...
+    def set_ticks(
+        self,
+        ticks: ArrayLike,
+        labels: Iterable[str] | None = ...,
+        *,
+        minor: bool = ...,
+        **kwargs
+    ) -> list[Tick]: ...
+    def axis_date(self, tz: str | datetime.tzinfo | None = ...) -> None: ...
+    def get_tick_space(self) -> int: ...
+    def get_label_position(self) -> Literal["top", "bottom"]: ...
+    def set_label_position(
+        self, position: Literal["top", "bottom", "left", "right"]
+    ) -> None: ...
+    def get_minpos(self) -> float: ...
+
+class XAxis(Axis):
+    __name__: str
+    axis_name: str
+    def __init__(self, *args, **kwargs) -> None: ...
+    label_position: Literal["bottom", "top"]
+    stale: bool
+    def set_label_position(self, position: Literal["bottom", "top"]) -> None: ...  # type: ignore[override]
+    def set_ticks_position(
+        self, position: Literal["top", "bottom", "both", "default", "none"]
+    ) -> None: ...
+    def tick_top(self) -> None: ...
+    def tick_bottom(self) -> None: ...
+    def get_ticks_position(self) -> Literal["top", "bottom", "default", "unknown"]: ...
+    def get_tick_space(self) -> int: ...
+
+class YAxis(Axis):
+    __name__: str
+    axis_name: str
+    def __init__(self, *args, **kwargs) -> None: ...
+    label_position: Literal["left", "right"]
+    stale: bool
+    def set_label_position(self, position: Literal["left", "right"]) -> None: ...  # type: ignore[override]
+    def set_offset_position(self, position: Literal["left", "right"]) -> None: ...
+    def set_ticks_position(
+        self, position: Literal["left", "right", "both", "default", "none"]
+    ) -> None: ...
+    def tick_right(self) -> None: ...
+    def tick_left(self) -> None: ...
+    def get_ticks_position(self) -> Literal["left", "right", "default", "unknown"]: ...
+    def get_tick_space(self) -> int: ...
diff --git a/lib/python3.12/site-packages/matplotlib/backend_bases.py b/lib/python3.12/site-packages/matplotlib/backend_bases.py
new file mode 100644
index 0000000000000000000000000000000000000000..a889a6b26e8e64e8f30e91ad2f66bdf2ff7c05d6
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/backend_bases.py
@@ -0,0 +1,3583 @@
+"""
+Abstract base classes define the primitives that renderers and
+graphics contexts must implement to serve as a Matplotlib backend.
+
+`RendererBase`
+    An abstract base class to handle drawing/rendering operations.
+
+`FigureCanvasBase`
+    The abstraction layer that separates the `.Figure` from the backend
+    specific details like a user interface drawing area.
+
+`GraphicsContextBase`
+    An abstract base class that provides color, line styles, etc.
+
+`Event`
+    The base class for all of the Matplotlib event handling.  Derived classes
+    such as `KeyEvent` and `MouseEvent` store the meta data like keys and
+    buttons pressed, x and y locations in pixel and `~.axes.Axes` coordinates.
+
+`ShowBase`
+    The base class for the ``Show`` class of each interactive backend; the
+    'show' callable is then set to ``Show.__call__``.
+
+`ToolContainerBase`
+    The base class for the Toolbar class of each interactive backend.
+"""
+
+from collections import namedtuple
+from contextlib import ExitStack, contextmanager, nullcontext
+from enum import Enum, IntEnum
+import functools
+import importlib
+import inspect
+import io
+import itertools
+import logging
+import os
+import pathlib
+import signal
+import socket
+import sys
+import time
+import weakref
+from weakref import WeakKeyDictionary
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib import (
+    _api, backend_tools as tools, cbook, colors, _docstring, text,
+    _tight_bbox, transforms, widgets, is_interactive, rcParams)
+from matplotlib._pylab_helpers import Gcf
+from matplotlib.backend_managers import ToolManager
+from matplotlib.cbook import _setattr_cm
+from matplotlib.layout_engine import ConstrainedLayoutEngine
+from matplotlib.path import Path
+from matplotlib.texmanager import TexManager
+from matplotlib.transforms import Affine2D
+from matplotlib._enums import JoinStyle, CapStyle
+
+
+_log = logging.getLogger(__name__)
+_default_filetypes = {
+    'eps': 'Encapsulated Postscript',
+    'jpg': 'Joint Photographic Experts Group',
+    'jpeg': 'Joint Photographic Experts Group',
+    'pdf': 'Portable Document Format',
+    'pgf': 'PGF code for LaTeX',
+    'png': 'Portable Network Graphics',
+    'ps': 'Postscript',
+    'raw': 'Raw RGBA bitmap',
+    'rgba': 'Raw RGBA bitmap',
+    'svg': 'Scalable Vector Graphics',
+    'svgz': 'Scalable Vector Graphics',
+    'tif': 'Tagged Image File Format',
+    'tiff': 'Tagged Image File Format',
+    'webp': 'WebP Image Format',
+}
+_default_backends = {
+    'eps': 'matplotlib.backends.backend_ps',
+    'jpg': 'matplotlib.backends.backend_agg',
+    'jpeg': 'matplotlib.backends.backend_agg',
+    'pdf': 'matplotlib.backends.backend_pdf',
+    'pgf': 'matplotlib.backends.backend_pgf',
+    'png': 'matplotlib.backends.backend_agg',
+    'ps': 'matplotlib.backends.backend_ps',
+    'raw': 'matplotlib.backends.backend_agg',
+    'rgba': 'matplotlib.backends.backend_agg',
+    'svg': 'matplotlib.backends.backend_svg',
+    'svgz': 'matplotlib.backends.backend_svg',
+    'tif': 'matplotlib.backends.backend_agg',
+    'tiff': 'matplotlib.backends.backend_agg',
+    'webp': 'matplotlib.backends.backend_agg',
+}
+
+
+def register_backend(format, backend, description=None):
+    """
+    Register a backend for saving to a given file format.
+
+    Parameters
+    ----------
+    format : str
+        File extension
+    backend : module string or canvas class
+        Backend for handling file output
+    description : str, default: ""
+        Description of the file type.
+    """
+    if description is None:
+        description = ''
+    _default_backends[format] = backend
+    _default_filetypes[format] = description
+
+
+def get_registered_canvas_class(format):
+    """
+    Return the registered default canvas for given file format.
+    Handles deferred import of required backend.
+    """
+    if format not in _default_backends:
+        return None
+    backend_class = _default_backends[format]
+    if isinstance(backend_class, str):
+        backend_class = importlib.import_module(backend_class).FigureCanvas
+        _default_backends[format] = backend_class
+    return backend_class
+
+
+class RendererBase:
+    """
+    An abstract base class to handle drawing/rendering operations.
+
+    The following methods must be implemented in the backend for full
+    functionality (though just implementing `draw_path` alone would give a
+    highly capable backend):
+
+    * `draw_path`
+    * `draw_image`
+    * `draw_gouraud_triangles`
+
+    The following methods *should* be implemented in the backend for
+    optimization reasons:
+
+    * `draw_text`
+    * `draw_markers`
+    * `draw_path_collection`
+    * `draw_quad_mesh`
+    """
+    def __init__(self):
+        super().__init__()
+        self._texmanager = None
+        self._text2path = text.TextToPath()
+        self._raster_depth = 0
+        self._rasterizing = False
+
+    def open_group(self, s, gid=None):
+        """
+        Open a grouping element with label *s* and *gid* (if set) as id.
+
+        Only used by the SVG renderer.
+        """
+
+    def close_group(self, s):
+        """
+        Close a grouping element with label *s*.
+
+        Only used by the SVG renderer.
+        """
+
+    def draw_path(self, gc, path, transform, rgbFace=None):
+        """Draw a `~.path.Path` instance using the given affine transform."""
+        raise NotImplementedError
+
+    def draw_markers(self, gc, marker_path, marker_trans, path,
+                     trans, rgbFace=None):
+        """
+        Draw a marker at each of *path*'s vertices (excluding control points).
+
+        The base (fallback) implementation makes multiple calls to `draw_path`.
+        Backends may want to override this method in order to draw the marker
+        only once and reuse it multiple times.
+
+        Parameters
+        ----------
+        gc : `.GraphicsContextBase`
+            The graphics context.
+        marker_path : `~matplotlib.path.Path`
+            The path for the marker.
+        marker_trans : `~matplotlib.transforms.Transform`
+            An affine transform applied to the marker.
+        path : `~matplotlib.path.Path`
+            The locations to draw the markers.
+        trans : `~matplotlib.transforms.Transform`
+            An affine transform applied to the path.
+        rgbFace : :mpltype:`color`, optional
+        """
+        for vertices, codes in path.iter_segments(trans, simplify=False):
+            if len(vertices):
+                x, y = vertices[-2:]
+                self.draw_path(gc, marker_path,
+                               marker_trans +
+                               transforms.Affine2D().translate(x, y),
+                               rgbFace)
+
+    def draw_path_collection(self, gc, master_transform, paths, all_transforms,
+                             offsets, offset_trans, facecolors, edgecolors,
+                             linewidths, linestyles, antialiaseds, urls,
+                             offset_position):
+        """
+        Draw a collection of *paths*.
+
+        Each path is first transformed by the corresponding entry
+        in *all_transforms* (a list of (3, 3) matrices) and then by
+        *master_transform*.  They are then translated by the corresponding
+        entry in *offsets*, which has been first transformed by *offset_trans*.
+
+        *facecolors*, *edgecolors*, *linewidths*, *linestyles*, and
+        *antialiased* are lists that set the corresponding properties.
+
+        *offset_position* is unused now, but the argument is kept for
+        backwards compatibility.
+
+        The base (fallback) implementation makes multiple calls to `draw_path`.
+        Backends may want to override this in order to render each set of
+        path data only once, and then reference that path multiple times with
+        the different offsets, colors, styles etc.  The generator methods
+        `_iter_collection_raw_paths` and `_iter_collection` are provided to
+        help with (and standardize) the implementation across backends.  It
+        is highly recommended to use those generators, so that changes to the
+        behavior of `draw_path_collection` can be made globally.
+        """
+        path_ids = self._iter_collection_raw_paths(master_transform,
+                                                   paths, all_transforms)
+
+        for xo, yo, path_id, gc0, rgbFace in self._iter_collection(
+                gc, list(path_ids), offsets, offset_trans,
+                facecolors, edgecolors, linewidths, linestyles,
+                antialiaseds, urls, offset_position):
+            path, transform = path_id
+            # Only apply another translation if we have an offset, else we
+            # reuse the initial transform.
+            if xo != 0 or yo != 0:
+                # The transformation can be used by multiple paths. Since
+                # translate is a inplace operation, we need to copy the
+                # transformation by .frozen() before applying the translation.
+                transform = transform.frozen()
+                transform.translate(xo, yo)
+            self.draw_path(gc0, path, transform, rgbFace)
+
+    def draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,
+                       coordinates, offsets, offsetTrans, facecolors,
+                       antialiased, edgecolors):
+        """
+        Draw a quadmesh.
+
+        The base (fallback) implementation converts the quadmesh to paths and
+        then calls `draw_path_collection`.
+        """
+
+        from matplotlib.collections import QuadMesh
+        paths = QuadMesh._convert_mesh_to_paths(coordinates)
+
+        if edgecolors is None:
+            edgecolors = facecolors
+        linewidths = np.array([gc.get_linewidth()], float)
+
+        return self.draw_path_collection(
+            gc, master_transform, paths, [], offsets, offsetTrans, facecolors,
+            edgecolors, linewidths, [], [antialiased], [None], 'screen')
+
+    def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
+                               transform):
+        """
+        Draw a series of Gouraud triangles.
+
+        Parameters
+        ----------
+        gc : `.GraphicsContextBase`
+            The graphics context.
+        triangles_array : (N, 3, 2) array-like
+            Array of *N* (x, y) points for the triangles.
+        colors_array : (N, 3, 4) array-like
+            Array of *N* RGBA colors for each point of the triangles.
+        transform : `~matplotlib.transforms.Transform`
+            An affine transform to apply to the points.
+        """
+        raise NotImplementedError
+
+    def _iter_collection_raw_paths(self, master_transform, paths,
+                                   all_transforms):
+        """
+        Helper method (along with `_iter_collection`) to implement
+        `draw_path_collection` in a memory-efficient manner.
+
+        This method yields all of the base path/transform combinations, given a
+        master transform, a list of paths and list of transforms.
+
+        The arguments should be exactly what is passed in to
+        `draw_path_collection`.
+
+        The backend should take each yielded path and transform and create an
+        object that can be referenced (reused) later.
+        """
+        Npaths = len(paths)
+        Ntransforms = len(all_transforms)
+        N = max(Npaths, Ntransforms)
+
+        if Npaths == 0:
+            return
+
+        transform = transforms.IdentityTransform()
+        for i in range(N):
+            path = paths[i % Npaths]
+            if Ntransforms:
+                transform = Affine2D(all_transforms[i % Ntransforms])
+            yield path, transform + master_transform
+
+    def _iter_collection_uses_per_path(self, paths, all_transforms,
+                                       offsets, facecolors, edgecolors):
+        """
+        Compute how many times each raw path object returned by
+        `_iter_collection_raw_paths` would be used when calling
+        `_iter_collection`. This is intended for the backend to decide
+        on the tradeoff between using the paths in-line and storing
+        them once and reusing. Rounds up in case the number of uses
+        is not the same for every path.
+        """
+        Npaths = len(paths)
+        if Npaths == 0 or len(facecolors) == len(edgecolors) == 0:
+            return 0
+        Npath_ids = max(Npaths, len(all_transforms))
+        N = max(Npath_ids, len(offsets))
+        return (N + Npath_ids - 1) // Npath_ids
+
+    def _iter_collection(self, gc, path_ids, offsets, offset_trans, facecolors,
+                         edgecolors, linewidths, linestyles,
+                         antialiaseds, urls, offset_position):
+        """
+        Helper method (along with `_iter_collection_raw_paths`) to implement
+        `draw_path_collection` in a memory-efficient manner.
+
+        This method yields all of the path, offset and graphics context
+        combinations to draw the path collection.  The caller should already
+        have looped over the results of `_iter_collection_raw_paths` to draw
+        this collection.
+
+        The arguments should be the same as that passed into
+        `draw_path_collection`, with the exception of *path_ids*, which is a
+        list of arbitrary objects that the backend will use to reference one of
+        the paths created in the `_iter_collection_raw_paths` stage.
+
+        Each yielded result is of the form::
+
+           xo, yo, path_id, gc, rgbFace
+
+        where *xo*, *yo* is an offset; *path_id* is one of the elements of
+        *path_ids*; *gc* is a graphics context and *rgbFace* is a color to
+        use for filling the path.
+        """
+        Npaths = len(path_ids)
+        Noffsets = len(offsets)
+        N = max(Npaths, Noffsets)
+        Nfacecolors = len(facecolors)
+        Nedgecolors = len(edgecolors)
+        Nlinewidths = len(linewidths)
+        Nlinestyles = len(linestyles)
+        Nurls = len(urls)
+
+        if (Nfacecolors == 0 and Nedgecolors == 0) or Npaths == 0:
+            return
+
+        gc0 = self.new_gc()
+        gc0.copy_properties(gc)
+
+        def cycle_or_default(seq, default=None):
+            # Cycle over *seq* if it is not empty; else always yield *default*.
+            return (itertools.cycle(seq) if len(seq)
+                    else itertools.repeat(default))
+
+        pathids = cycle_or_default(path_ids)
+        toffsets = cycle_or_default(offset_trans.transform(offsets), (0, 0))
+        fcs = cycle_or_default(facecolors)
+        ecs = cycle_or_default(edgecolors)
+        lws = cycle_or_default(linewidths)
+        lss = cycle_or_default(linestyles)
+        aas = cycle_or_default(antialiaseds)
+        urls = cycle_or_default(urls)
+
+        if Nedgecolors == 0:
+            gc0.set_linewidth(0.0)
+
+        for pathid, (xo, yo), fc, ec, lw, ls, aa, url in itertools.islice(
+                zip(pathids, toffsets, fcs, ecs, lws, lss, aas, urls), N):
+            if not (np.isfinite(xo) and np.isfinite(yo)):
+                continue
+            if Nedgecolors:
+                if Nlinewidths:
+                    gc0.set_linewidth(lw)
+                if Nlinestyles:
+                    gc0.set_dashes(*ls)
+                if len(ec) == 4 and ec[3] == 0.0:
+                    gc0.set_linewidth(0)
+                else:
+                    gc0.set_foreground(ec)
+            if fc is not None and len(fc) == 4 and fc[3] == 0:
+                fc = None
+            gc0.set_antialiased(aa)
+            if Nurls:
+                gc0.set_url(url)
+            yield xo, yo, pathid, gc0, fc
+        gc0.restore()
+
+    def get_image_magnification(self):
+        """
+        Get the factor by which to magnify images passed to `draw_image`.
+        Allows a backend to have images at a different resolution to other
+        artists.
+        """
+        return 1.0
+
+    def draw_image(self, gc, x, y, im, transform=None):
+        """
+        Draw an RGBA image.
+
+        Parameters
+        ----------
+        gc : `.GraphicsContextBase`
+            A graphics context with clipping information.
+
+        x : float
+            The distance in physical units (i.e., dots or pixels) from the left
+            hand side of the canvas.
+
+        y : float
+            The distance in physical units (i.e., dots or pixels) from the
+            bottom side of the canvas.
+
+        im : (N, M, 4) array of `numpy.uint8`
+            An array of RGBA pixels.
+
+        transform : `~matplotlib.transforms.Affine2DBase`
+            If and only if the concrete backend is written such that
+            `option_scale_image` returns ``True``, an affine transformation
+            (i.e., an `.Affine2DBase`) *may* be passed to `draw_image`.  The
+            translation vector of the transformation is given in physical units
+            (i.e., dots or pixels). Note that the transformation does not
+            override *x* and *y*, and has to be applied *before* translating
+            the result by *x* and *y* (this can be accomplished by adding *x*
+            and *y* to the translation vector defined by *transform*).
+        """
+        raise NotImplementedError
+
+    def option_image_nocomposite(self):
+        """
+        Return whether image composition by Matplotlib should be skipped.
+
+        Raster backends should usually return False (letting the C-level
+        rasterizer take care of image composition); vector backends should
+        usually return ``not rcParams["image.composite_image"]``.
+        """
+        return False
+
+    def option_scale_image(self):
+        """
+        Return whether arbitrary affine transformations in `draw_image` are
+        supported (True for most vector backends).
+        """
+        return False
+
+    def draw_tex(self, gc, x, y, s, prop, angle, *, mtext=None):
+        """
+        Draw a TeX instance.
+
+        Parameters
+        ----------
+        gc : `.GraphicsContextBase`
+            The graphics context.
+        x : float
+            The x location of the text in display coords.
+        y : float
+            The y location of the text baseline in display coords.
+        s : str
+            The TeX text string.
+        prop : `~matplotlib.font_manager.FontProperties`
+            The font properties.
+        angle : float
+            The rotation angle in degrees anti-clockwise.
+        mtext : `~matplotlib.text.Text`
+            The original text object to be rendered.
+        """
+        self._draw_text_as_path(gc, x, y, s, prop, angle, ismath="TeX")
+
+    def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
+        """
+        Draw a text instance.
+
+        Parameters
+        ----------
+        gc : `.GraphicsContextBase`
+            The graphics context.
+        x : float
+            The x location of the text in display coords.
+        y : float
+            The y location of the text baseline in display coords.
+        s : str
+            The text string.
+        prop : `~matplotlib.font_manager.FontProperties`
+            The font properties.
+        angle : float
+            The rotation angle in degrees anti-clockwise.
+        ismath : bool or "TeX"
+            If True, use mathtext parser.
+        mtext : `~matplotlib.text.Text`
+            The original text object to be rendered.
+
+        Notes
+        -----
+        **Notes for backend implementers:**
+
+        `.RendererBase.draw_text` also supports passing "TeX" to the *ismath*
+        parameter to use TeX rendering, but this is not required for actual
+        rendering backends, and indeed many builtin backends do not support
+        this.  Rather, TeX rendering is provided by `~.RendererBase.draw_tex`.
+        """
+        self._draw_text_as_path(gc, x, y, s, prop, angle, ismath)
+
+    def _draw_text_as_path(self, gc, x, y, s, prop, angle, ismath):
+        """
+        Draw the text by converting them to paths using `.TextToPath`.
+
+        This private helper supports the same parameters as
+        `~.RendererBase.draw_text`; setting *ismath* to "TeX" triggers TeX
+        rendering.
+        """
+        text2path = self._text2path
+        fontsize = self.points_to_pixels(prop.get_size_in_points())
+        verts, codes = text2path.get_text_path(prop, s, ismath=ismath)
+        path = Path(verts, codes)
+        if self.flipy():
+            width, height = self.get_canvas_width_height()
+            transform = (Affine2D()
+                         .scale(fontsize / text2path.FONT_SCALE)
+                         .rotate_deg(angle)
+                         .translate(x, height - y))
+        else:
+            transform = (Affine2D()
+                         .scale(fontsize / text2path.FONT_SCALE)
+                         .rotate_deg(angle)
+                         .translate(x, y))
+        color = gc.get_rgb()
+        gc.set_linewidth(0.0)
+        self.draw_path(gc, path, transform, rgbFace=color)
+
+    def get_text_width_height_descent(self, s, prop, ismath):
+        """
+        Get the width, height, and descent (offset from the bottom to the baseline), in
+        display coords, of the string *s* with `.FontProperties` *prop*.
+
+        Whitespace at the start and the end of *s* is included in the reported width.
+        """
+        fontsize = prop.get_size_in_points()
+
+        if ismath == 'TeX':
+            # todo: handle properties
+            return self.get_texmanager().get_text_width_height_descent(
+                s, fontsize, renderer=self)
+
+        dpi = self.points_to_pixels(72)
+        if ismath:
+            dims = self._text2path.mathtext_parser.parse(s, dpi, prop)
+            return dims[0:3]  # return width, height, descent
+
+        flags = self._text2path._get_hinting_flag()
+        font = self._text2path._get_font(prop)
+        font.set_size(fontsize, dpi)
+        # the width and height of unrotated string
+        font.set_text(s, 0.0, flags=flags)
+        w, h = font.get_width_height()
+        d = font.get_descent()
+        w /= 64.0  # convert from subpixels
+        h /= 64.0
+        d /= 64.0
+        return w, h, d
+
+    def flipy(self):
+        """
+        Return whether y values increase from top to bottom.
+
+        Note that this only affects drawing of texts.
+        """
+        return True
+
+    def get_canvas_width_height(self):
+        """Return the canvas width and height in display coords."""
+        return 1, 1
+
+    def get_texmanager(self):
+        """Return the `.TexManager` instance."""
+        if self._texmanager is None:
+            self._texmanager = TexManager()
+        return self._texmanager
+
+    def new_gc(self):
+        """Return an instance of a `.GraphicsContextBase`."""
+        return GraphicsContextBase()
+
+    def points_to_pixels(self, points):
+        """
+        Convert points to display units.
+
+        You need to override this function (unless your backend
+        doesn't have a dpi, e.g., postscript or svg).  Some imaging
+        systems assume some value for pixels per inch::
+
+            points to pixels = points * pixels_per_inch/72 * dpi/72
+
+        Parameters
+        ----------
+        points : float or array-like
+
+        Returns
+        -------
+        Points converted to pixels
+        """
+        return points
+
+    def start_rasterizing(self):
+        """
+        Switch to the raster renderer.
+
+        Used by `.MixedModeRenderer`.
+        """
+
+    def stop_rasterizing(self):
+        """
+        Switch back to the vector renderer and draw the contents of the raster
+        renderer as an image on the vector renderer.
+
+        Used by `.MixedModeRenderer`.
+        """
+
+    def start_filter(self):
+        """
+        Switch to a temporary renderer for image filtering effects.
+
+        Currently only supported by the agg renderer.
+        """
+
+    def stop_filter(self, filter_func):
+        """
+        Switch back to the original renderer.  The contents of the temporary
+        renderer is processed with the *filter_func* and is drawn on the
+        original renderer as an image.
+
+        Currently only supported by the agg renderer.
+        """
+
+    def _draw_disabled(self):
+        """
+        Context manager to temporary disable drawing.
+
+        This is used for getting the drawn size of Artists.  This lets us
+        run the draw process to update any Python state but does not pay the
+        cost of the draw_XYZ calls on the canvas.
+        """
+        no_ops = {
+            meth_name: lambda *args, **kwargs: None
+            for meth_name in dir(RendererBase)
+            if (meth_name.startswith("draw_")
+                or meth_name in ["open_group", "close_group"])
+        }
+
+        return _setattr_cm(self, **no_ops)
+
+
+class GraphicsContextBase:
+    """An abstract base class that provides color, line styles, etc."""
+
+    def __init__(self):
+        self._alpha = 1.0
+        self._forced_alpha = False  # if True, _alpha overrides A from RGBA
+        self._antialiased = 1  # use 0, 1 not True, False for extension code
+        self._capstyle = CapStyle('butt')
+        self._cliprect = None
+        self._clippath = None
+        self._dashes = 0, None
+        self._joinstyle = JoinStyle('round')
+        self._linestyle = 'solid'
+        self._linewidth = 1
+        self._rgb = (0.0, 0.0, 0.0, 1.0)
+        self._hatch = None
+        self._hatch_color = colors.to_rgba(rcParams['hatch.color'])
+        self._hatch_linewidth = rcParams['hatch.linewidth']
+        self._url = None
+        self._gid = None
+        self._snap = None
+        self._sketch = None
+
+    def copy_properties(self, gc):
+        """Copy properties from *gc* to self."""
+        self._alpha = gc._alpha
+        self._forced_alpha = gc._forced_alpha
+        self._antialiased = gc._antialiased
+        self._capstyle = gc._capstyle
+        self._cliprect = gc._cliprect
+        self._clippath = gc._clippath
+        self._dashes = gc._dashes
+        self._joinstyle = gc._joinstyle
+        self._linestyle = gc._linestyle
+        self._linewidth = gc._linewidth
+        self._rgb = gc._rgb
+        self._hatch = gc._hatch
+        self._hatch_color = gc._hatch_color
+        self._hatch_linewidth = gc._hatch_linewidth
+        self._url = gc._url
+        self._gid = gc._gid
+        self._snap = gc._snap
+        self._sketch = gc._sketch
+
+    def restore(self):
+        """
+        Restore the graphics context from the stack - needed only
+        for backends that save graphics contexts on a stack.
+        """
+
+    def get_alpha(self):
+        """
+        Return the alpha value used for blending - not supported on all
+        backends.
+        """
+        return self._alpha
+
+    def get_antialiased(self):
+        """Return whether the object should try to do antialiased rendering."""
+        return self._antialiased
+
+    def get_capstyle(self):
+        """Return the `.CapStyle`."""
+        return self._capstyle.name
+
+    def get_clip_rectangle(self):
+        """
+        Return the clip rectangle as a `~matplotlib.transforms.Bbox` instance.
+        """
+        return self._cliprect
+
+    def get_clip_path(self):
+        """
+        Return the clip path in the form (path, transform), where path
+        is a `~.path.Path` instance, and transform is
+        an affine transform to apply to the path before clipping.
+        """
+        if self._clippath is not None:
+            tpath, tr = self._clippath.get_transformed_path_and_affine()
+            if np.all(np.isfinite(tpath.vertices)):
+                return tpath, tr
+            else:
+                _log.warning("Ill-defined clip_path detected. Returning None.")
+                return None, None
+        return None, None
+
+    def get_dashes(self):
+        """
+        Return the dash style as an (offset, dash-list) pair.
+
+        See `.set_dashes` for details.
+
+        Default value is (None, None).
+        """
+        return self._dashes
+
+    def get_forced_alpha(self):
+        """
+        Return whether the value given by get_alpha() should be used to
+        override any other alpha-channel values.
+        """
+        return self._forced_alpha
+
+    def get_joinstyle(self):
+        """Return the `.JoinStyle`."""
+        return self._joinstyle.name
+
+    def get_linewidth(self):
+        """Return the line width in points."""
+        return self._linewidth
+
+    def get_rgb(self):
+        """Return a tuple of three or four floats from 0-1."""
+        return self._rgb
+
+    def get_url(self):
+        """Return a url if one is set, None otherwise."""
+        return self._url
+
+    def get_gid(self):
+        """Return the object identifier if one is set, None otherwise."""
+        return self._gid
+
+    def get_snap(self):
+        """
+        Return the snap setting, which can be:
+
+        * True: snap vertices to the nearest pixel center
+        * False: leave vertices as-is
+        * None: (auto) If the path contains only rectilinear line segments,
+          round to the nearest pixel center
+        """
+        return self._snap
+
+    def set_alpha(self, alpha):
+        """
+        Set the alpha value used for blending - not supported on all backends.
+
+        If ``alpha=None`` (the default), the alpha components of the
+        foreground and fill colors will be used to set their respective
+        transparencies (where applicable); otherwise, ``alpha`` will override
+        them.
+        """
+        if alpha is not None:
+            self._alpha = alpha
+            self._forced_alpha = True
+        else:
+            self._alpha = 1.0
+            self._forced_alpha = False
+        self.set_foreground(self._rgb, isRGBA=True)
+
+    def set_antialiased(self, b):
+        """Set whether object should be drawn with antialiased rendering."""
+        # Use ints to make life easier on extension code trying to read the gc.
+        self._antialiased = int(bool(b))
+
+    @_docstring.interpd
+    def set_capstyle(self, cs):
+        """
+        Set how to draw endpoints of lines.
+
+        Parameters
+        ----------
+        cs : `.CapStyle` or %(CapStyle)s
+        """
+        self._capstyle = CapStyle(cs)
+
+    def set_clip_rectangle(self, rectangle):
+        """Set the clip rectangle to a `.Bbox` or None."""
+        self._cliprect = rectangle
+
+    def set_clip_path(self, path):
+        """Set the clip path to a `.TransformedPath` or None."""
+        _api.check_isinstance((transforms.TransformedPath, None), path=path)
+        self._clippath = path
+
+    def set_dashes(self, dash_offset, dash_list):
+        """
+        Set the dash style for the gc.
+
+        Parameters
+        ----------
+        dash_offset : float
+            Distance, in points, into the dash pattern at which to
+            start the pattern. It is usually set to 0.
+        dash_list : array-like or None
+            The on-off sequence as points.  None specifies a solid line. All
+            values must otherwise be non-negative (:math:`\\ge 0`).
+
+        Notes
+        -----
+        See p. 666 of the PostScript
+        `Language Reference
+        <https://www.adobe.com/jp/print/postscript/pdfs/PLRM.pdf>`_
+        for more info.
+        """
+        if dash_list is not None:
+            dl = np.asarray(dash_list)
+            if np.any(dl < 0.0):
+                raise ValueError(
+                    "All values in the dash list must be non-negative")
+            if dl.size and not np.any(dl > 0.0):
+                raise ValueError(
+                    'At least one value in the dash list must be positive')
+        self._dashes = dash_offset, dash_list
+
+    def set_foreground(self, fg, isRGBA=False):
+        """
+        Set the foreground color.
+
+        Parameters
+        ----------
+        fg : :mpltype:`color`
+        isRGBA : bool
+            If *fg* is known to be an ``(r, g, b, a)`` tuple, *isRGBA* can be
+            set to True to improve performance.
+        """
+        if self._forced_alpha and isRGBA:
+            self._rgb = fg[:3] + (self._alpha,)
+        elif self._forced_alpha:
+            self._rgb = colors.to_rgba(fg, self._alpha)
+        elif isRGBA:
+            self._rgb = fg
+        else:
+            self._rgb = colors.to_rgba(fg)
+
+    @_docstring.interpd
+    def set_joinstyle(self, js):
+        """
+        Set how to draw connections between line segments.
+
+        Parameters
+        ----------
+        js : `.JoinStyle` or %(JoinStyle)s
+        """
+        self._joinstyle = JoinStyle(js)
+
+    def set_linewidth(self, w):
+        """Set the linewidth in points."""
+        self._linewidth = float(w)
+
+    def set_url(self, url):
+        """Set the url for links in compatible backends."""
+        self._url = url
+
+    def set_gid(self, id):
+        """Set the id."""
+        self._gid = id
+
+    def set_snap(self, snap):
+        """
+        Set the snap setting which may be:
+
+        * True: snap vertices to the nearest pixel center
+        * False: leave vertices as-is
+        * None: (auto) If the path contains only rectilinear line segments,
+          round to the nearest pixel center
+        """
+        self._snap = snap
+
+    def set_hatch(self, hatch):
+        """Set the hatch style (for fills)."""
+        self._hatch = hatch
+
+    def get_hatch(self):
+        """Get the current hatch style."""
+        return self._hatch
+
+    def get_hatch_path(self, density=6.0):
+        """Return a `.Path` for the current hatch."""
+        hatch = self.get_hatch()
+        if hatch is None:
+            return None
+        return Path.hatch(hatch, density)
+
+    def get_hatch_color(self):
+        """Get the hatch color."""
+        return self._hatch_color
+
+    def set_hatch_color(self, hatch_color):
+        """Set the hatch color."""
+        self._hatch_color = hatch_color
+
+    def get_hatch_linewidth(self):
+        """Get the hatch linewidth."""
+        return self._hatch_linewidth
+
+    def set_hatch_linewidth(self, hatch_linewidth):
+        """Set the hatch linewidth."""
+        self._hatch_linewidth = hatch_linewidth
+
+    def get_sketch_params(self):
+        """
+        Return the sketch parameters for the artist.
+
+        Returns
+        -------
+        tuple or `None`
+
+            A 3-tuple with the following elements:
+
+            * ``scale``: The amplitude of the wiggle perpendicular to the
+              source line.
+            * ``length``: The length of the wiggle along the line.
+            * ``randomness``: The scale factor by which the length is
+              shrunken or expanded.
+
+            May return `None` if no sketch parameters were set.
+        """
+        return self._sketch
+
+    def set_sketch_params(self, scale=None, length=None, randomness=None):
+        """
+        Set the sketch parameters.
+
+        Parameters
+        ----------
+        scale : float, optional
+            The amplitude of the wiggle perpendicular to the source line, in
+            pixels.  If scale is `None`, or not provided, no sketch filter will
+            be provided.
+        length : float, default: 128
+            The length of the wiggle along the line, in pixels.
+        randomness : float, default: 16
+            The scale factor by which the length is shrunken or expanded.
+        """
+        self._sketch = (
+            None if scale is None
+            else (scale, length or 128., randomness or 16.))
+
+
+class TimerBase:
+    """
+    A base class for providing timer events, useful for things animations.
+    Backends need to implement a few specific methods in order to use their
+    own timing mechanisms so that the timer events are integrated into their
+    event loops.
+
+    Subclasses must override the following methods:
+
+    - ``_timer_start``: Backend-specific code for starting the timer.
+    - ``_timer_stop``: Backend-specific code for stopping the timer.
+
+    Subclasses may additionally override the following methods:
+
+    - ``_timer_set_single_shot``: Code for setting the timer to single shot
+      operating mode, if supported by the timer object.  If not, the `Timer`
+      class itself will store the flag and the ``_on_timer`` method should be
+      overridden to support such behavior.
+
+    - ``_timer_set_interval``: Code for setting the interval on the timer, if
+      there is a method for doing so on the timer object.
+
+    - ``_on_timer``: The internal function that any timer object should call,
+      which will handle the task of running all callbacks that have been set.
+    """
+
+    def __init__(self, interval=None, callbacks=None):
+        """
+        Parameters
+        ----------
+        interval : int, default: 1000ms
+            The time between timer events in milliseconds.  Will be stored as
+            ``timer.interval``.
+        callbacks : list[tuple[callable, tuple, dict]]
+            List of (func, args, kwargs) tuples that will be called upon timer
+            events.  This list is accessible as ``timer.callbacks`` and can be
+            manipulated directly, or the functions `~.TimerBase.add_callback`
+            and `~.TimerBase.remove_callback` can be used.
+        """
+        self.callbacks = [] if callbacks is None else callbacks.copy()
+        # Set .interval and not ._interval to go through the property setter.
+        self.interval = 1000 if interval is None else interval
+        self.single_shot = False
+
+    def __del__(self):
+        """Need to stop timer and possibly disconnect timer."""
+        self._timer_stop()
+
+    @_api.delete_parameter("3.9", "interval", alternative="timer.interval")
+    def start(self, interval=None):
+        """
+        Start the timer object.
+
+        Parameters
+        ----------
+        interval : int, optional
+            Timer interval in milliseconds; overrides a previously set interval
+            if provided.
+        """
+        if interval is not None:
+            self.interval = interval
+        self._timer_start()
+
+    def stop(self):
+        """Stop the timer."""
+        self._timer_stop()
+
+    def _timer_start(self):
+        pass
+
+    def _timer_stop(self):
+        pass
+
+    @property
+    def interval(self):
+        """The time between timer events, in milliseconds."""
+        return self._interval
+
+    @interval.setter
+    def interval(self, interval):
+        # Force to int since none of the backends actually support fractional
+        # milliseconds, and some error or give warnings.
+        # Some backends also fail when interval == 0, so ensure >= 1 msec
+        interval = max(int(interval), 1)
+        self._interval = interval
+        self._timer_set_interval()
+
+    @property
+    def single_shot(self):
+        """Whether this timer should stop after a single run."""
+        return self._single
+
+    @single_shot.setter
+    def single_shot(self, ss):
+        self._single = ss
+        self._timer_set_single_shot()
+
+    def add_callback(self, func, *args, **kwargs):
+        """
+        Register *func* to be called by timer when the event fires. Any
+        additional arguments provided will be passed to *func*.
+
+        This function returns *func*, which makes it possible to use it as a
+        decorator.
+        """
+        self.callbacks.append((func, args, kwargs))
+        return func
+
+    def remove_callback(self, func, *args, **kwargs):
+        """
+        Remove *func* from list of callbacks.
+
+        *args* and *kwargs* are optional and used to distinguish between copies
+        of the same function registered to be called with different arguments.
+        This behavior is deprecated.  In the future, ``*args, **kwargs`` won't
+        be considered anymore; to keep a specific callback removable by itself,
+        pass it to `add_callback` as a `functools.partial` object.
+        """
+        if args or kwargs:
+            _api.warn_deprecated(
+                "3.1", message="In a future version, Timer.remove_callback "
+                "will not take *args, **kwargs anymore, but remove all "
+                "callbacks where the callable matches; to keep a specific "
+                "callback removable by itself, pass it to add_callback as a "
+                "functools.partial object.")
+            self.callbacks.remove((func, args, kwargs))
+        else:
+            funcs = [c[0] for c in self.callbacks]
+            if func in funcs:
+                self.callbacks.pop(funcs.index(func))
+
+    def _timer_set_interval(self):
+        """Used to set interval on underlying timer object."""
+
+    def _timer_set_single_shot(self):
+        """Used to set single shot on underlying timer object."""
+
+    def _on_timer(self):
+        """
+        Runs all function that have been registered as callbacks. Functions
+        can return False (or 0) if they should not be called any more. If there
+        are no callbacks, the timer is automatically stopped.
+        """
+        for func, args, kwargs in self.callbacks:
+            ret = func(*args, **kwargs)
+            # docstring above explains why we use `if ret == 0` here,
+            # instead of `if not ret`.
+            # This will also catch `ret == False` as `False == 0`
+            # but does not annoy the linters
+            # https://docs.python.org/3/library/stdtypes.html#boolean-values
+            if ret == 0:
+                self.callbacks.remove((func, args, kwargs))
+
+        if len(self.callbacks) == 0:
+            self.stop()
+
+
+class Event:
+    """
+    A Matplotlib event.
+
+    The following attributes are defined and shown with their default values.
+    Subclasses may define additional attributes.
+
+    Attributes
+    ----------
+    name : str
+        The event name.
+    canvas : `FigureCanvasBase`
+        The backend-specific canvas instance generating the event.
+    guiEvent
+        The GUI event that triggered the Matplotlib event.
+    """
+
+    def __init__(self, name, canvas, guiEvent=None):
+        self.name = name
+        self.canvas = canvas
+        self.guiEvent = guiEvent
+
+    def _process(self):
+        """Process this event on ``self.canvas``, then unset ``guiEvent``."""
+        self.canvas.callbacks.process(self.name, self)
+        self.guiEvent = None
+
+
+class DrawEvent(Event):
+    """
+    An event triggered by a draw operation on the canvas.
+
+    In most backends, callbacks subscribed to this event will be fired after
+    the rendering is complete but before the screen is updated. Any extra
+    artists drawn to the canvas's renderer will be reflected without an
+    explicit call to ``blit``.
+
+    .. warning::
+
+       Calling ``canvas.draw`` and ``canvas.blit`` in these callbacks may
+       not be safe with all backends and may cause infinite recursion.
+
+    A DrawEvent has a number of special attributes in addition to those defined
+    by the parent `Event` class.
+
+    Attributes
+    ----------
+    renderer : `RendererBase`
+        The renderer for the draw event.
+    """
+    def __init__(self, name, canvas, renderer):
+        super().__init__(name, canvas)
+        self.renderer = renderer
+
+
+class ResizeEvent(Event):
+    """
+    An event triggered by a canvas resize.
+
+    A ResizeEvent has a number of special attributes in addition to those
+    defined by the parent `Event` class.
+
+    Attributes
+    ----------
+    width : int
+        Width of the canvas in pixels.
+    height : int
+        Height of the canvas in pixels.
+    """
+
+    def __init__(self, name, canvas):
+        super().__init__(name, canvas)
+        self.width, self.height = canvas.get_width_height()
+
+
+class CloseEvent(Event):
+    """An event triggered by a figure being closed."""
+
+
+class LocationEvent(Event):
+    """
+    An event that has a screen location.
+
+    A LocationEvent has a number of special attributes in addition to those
+    defined by the parent `Event` class.
+
+    Attributes
+    ----------
+    x, y : int or None
+        Event location in pixels from bottom left of canvas.
+    inaxes : `~matplotlib.axes.Axes` or None
+        The `~.axes.Axes` instance over which the mouse is, if any.
+    xdata, ydata : float or None
+        Data coordinates of the mouse within *inaxes*, or *None* if the mouse
+        is not over an Axes.
+    modifiers : frozenset
+        The keyboard modifiers currently being pressed (except for KeyEvent).
+    """
+
+    _last_axes_ref = None
+
+    def __init__(self, name, canvas, x, y, guiEvent=None, *, modifiers=None):
+        super().__init__(name, canvas, guiEvent=guiEvent)
+        # x position - pixels from left of canvas
+        self.x = int(x) if x is not None else x
+        # y position - pixels from right of canvas
+        self.y = int(y) if y is not None else y
+        self.inaxes = None  # the Axes instance the mouse is over
+        self.xdata = None   # x coord of mouse in data coords
+        self.ydata = None   # y coord of mouse in data coords
+        self.modifiers = frozenset(modifiers if modifiers is not None else [])
+
+        if x is None or y is None:
+            # cannot check if event was in Axes if no (x, y) info
+            return
+
+        self._set_inaxes(self.canvas.inaxes((x, y))
+                         if self.canvas.mouse_grabber is None else
+                         self.canvas.mouse_grabber,
+                         (x, y))
+
+    # Splitting _set_inaxes out is useful for the axes_leave_event handler: it
+    # needs to generate synthetic LocationEvents with manually-set inaxes.  In
+    # that latter case, xy has already been cast to int so it can directly be
+    # read from self.x, self.y; in the normal case, however, it is more
+    # accurate to pass the untruncated float x, y values passed to the ctor.
+
+    def _set_inaxes(self, inaxes, xy=None):
+        self.inaxes = inaxes
+        if inaxes is not None:
+            try:
+                self.xdata, self.ydata = inaxes.transData.inverted().transform(
+                    xy if xy is not None else (self.x, self.y))
+            except ValueError:
+                pass
+
+
+class MouseButton(IntEnum):
+    LEFT = 1
+    MIDDLE = 2
+    RIGHT = 3
+    BACK = 8
+    FORWARD = 9
+
+
+class MouseEvent(LocationEvent):
+    """
+    A mouse event ('button_press_event', 'button_release_event', \
+'scroll_event', 'motion_notify_event').
+
+    A MouseEvent has a number of special attributes in addition to those
+    defined by the parent `Event` and `LocationEvent` classes.
+
+    Attributes
+    ----------
+    button : None or `MouseButton` or {'up', 'down'}
+        The button pressed. 'up' and 'down' are used for scroll events.
+
+        Note that LEFT and RIGHT actually refer to the "primary" and
+        "secondary" buttons, i.e. if the user inverts their left and right
+        buttons ("left-handed setting") then the LEFT button will be the one
+        physically on the right.
+
+        If this is unset, *name* is "scroll_event", and *step* is nonzero, then
+        this will be set to "up" or "down" depending on the sign of *step*.
+
+    buttons : None or frozenset
+        For 'motion_notify_event', the mouse buttons currently being pressed
+        (a set of zero or more MouseButtons);
+        for other events, None.
+
+        .. note::
+           For 'motion_notify_event', this attribute is more accurate than
+           the ``button`` (singular) attribute, which is obtained from the last
+           'button_press_event' or 'button_release_event' that occurred within
+           the canvas (and thus 1. be wrong if the last change in mouse state
+           occurred when the canvas did not have focus, and 2. cannot report
+           when multiple buttons are pressed).
+
+           This attribute is not set for 'button_press_event' and
+           'button_release_event' because GUI toolkits are inconsistent as to
+           whether they report the button state *before* or *after* the
+           press/release occurred.
+
+        .. warning::
+           On macOS, the Tk backends only report a single button even if
+           multiple buttons are pressed.
+
+    key : None or str
+        The key pressed when the mouse event triggered, e.g. 'shift'.
+        See `KeyEvent`.
+
+        .. warning::
+           This key is currently obtained from the last 'key_press_event' or
+           'key_release_event' that occurred within the canvas.  Thus, if the
+           last change of keyboard state occurred while the canvas did not have
+           focus, this attribute will be wrong.  On the other hand, the
+           ``modifiers`` attribute should always be correct, but it can only
+           report on modifier keys.
+
+    step : float
+        The number of scroll steps (positive for 'up', negative for 'down').
+        This applies only to 'scroll_event' and defaults to 0 otherwise.
+
+    dblclick : bool
+        Whether the event is a double-click. This applies only to
+        'button_press_event' and is False otherwise. In particular, it's
+        not used in 'button_release_event'.
+
+    Examples
+    --------
+    ::
+
+        def on_press(event):
+            print('you pressed', event.button, event.xdata, event.ydata)
+
+        cid = fig.canvas.mpl_connect('button_press_event', on_press)
+    """
+
+    def __init__(self, name, canvas, x, y, button=None, key=None,
+                 step=0, dblclick=False, guiEvent=None, *,
+                 buttons=None, modifiers=None):
+        super().__init__(
+            name, canvas, x, y, guiEvent=guiEvent, modifiers=modifiers)
+        if button in MouseButton.__members__.values():
+            button = MouseButton(button)
+        if name == "scroll_event" and button is None:
+            if step > 0:
+                button = "up"
+            elif step < 0:
+                button = "down"
+        self.button = button
+        if name == "motion_notify_event":
+            self.buttons = frozenset(buttons if buttons is not None else [])
+        else:
+            # We don't support 'buttons' for button_press/release_event because
+            # toolkits are inconsistent as to whether they report the state
+            # before or after the event.
+            if buttons:
+                raise ValueError(
+                    "'buttons' is only supported for 'motion_notify_event'")
+            self.buttons = None
+        self.key = key
+        self.step = step
+        self.dblclick = dblclick
+
+    def __str__(self):
+        return (f"{self.name}: "
+                f"xy=({self.x}, {self.y}) xydata=({self.xdata}, {self.ydata}) "
+                f"button={self.button} dblclick={self.dblclick} "
+                f"inaxes={self.inaxes}")
+
+
+class PickEvent(Event):
+    """
+    A pick event.
+
+    This event is fired when the user picks a location on the canvas
+    sufficiently close to an artist that has been made pickable with
+    `.Artist.set_picker`.
+
+    A PickEvent has a number of special attributes in addition to those defined
+    by the parent `Event` class.
+
+    Attributes
+    ----------
+    mouseevent : `MouseEvent`
+        The mouse event that generated the pick.
+    artist : `~matplotlib.artist.Artist`
+        The picked artist.  Note that artists are not pickable by default
+        (see `.Artist.set_picker`).
+    other
+        Additional attributes may be present depending on the type of the
+        picked object; e.g., a `.Line2D` pick may define different extra
+        attributes than a `.PatchCollection` pick.
+
+    Examples
+    --------
+    Bind a function ``on_pick()`` to pick events, that prints the coordinates
+    of the picked data point::
+
+        ax.plot(np.rand(100), 'o', picker=5)  # 5 points tolerance
+
+        def on_pick(event):
+            line = event.artist
+            xdata, ydata = line.get_data()
+            ind = event.ind
+            print(f'on pick line: {xdata[ind]:.3f}, {ydata[ind]:.3f}')
+
+        cid = fig.canvas.mpl_connect('pick_event', on_pick)
+    """
+
+    def __init__(self, name, canvas, mouseevent, artist,
+                 guiEvent=None, **kwargs):
+        if guiEvent is None:
+            guiEvent = mouseevent.guiEvent
+        super().__init__(name, canvas, guiEvent)
+        self.mouseevent = mouseevent
+        self.artist = artist
+        self.__dict__.update(kwargs)
+
+
+class KeyEvent(LocationEvent):
+    """
+    A key event (key press, key release).
+
+    A KeyEvent has a number of special attributes in addition to those defined
+    by the parent `Event` and `LocationEvent` classes.
+
+    Attributes
+    ----------
+    key : None or str
+        The key(s) pressed. Could be *None*, a single case sensitive Unicode
+        character ("g", "G", "#", etc.), a special key ("control", "shift",
+        "f1", "up", etc.) or a combination of the above (e.g., "ctrl+alt+g",
+        "ctrl+alt+G").
+
+    Notes
+    -----
+    Modifier keys will be prefixed to the pressed key and will be in the order
+    "ctrl", "alt", "super". The exception to this rule is when the pressed key
+    is itself a modifier key, therefore "ctrl+alt" and "alt+control" can both
+    be valid key values.
+
+    Examples
+    --------
+    ::
+
+        def on_key(event):
+            print('you pressed', event.key, event.xdata, event.ydata)
+
+        cid = fig.canvas.mpl_connect('key_press_event', on_key)
+    """
+
+    def __init__(self, name, canvas, key, x=0, y=0, guiEvent=None):
+        super().__init__(name, canvas, x, y, guiEvent=guiEvent)
+        self.key = key
+
+
+# Default callback for key events.
+def _key_handler(event):
+    # Dead reckoning of key.
+    if event.name == "key_press_event":
+        event.canvas._key = event.key
+    elif event.name == "key_release_event":
+        event.canvas._key = None
+
+
+# Default callback for mouse events.
+def _mouse_handler(event):
+    # Dead-reckoning of button and key.
+    if event.name == "button_press_event":
+        event.canvas._button = event.button
+    elif event.name == "button_release_event":
+        event.canvas._button = None
+    elif event.name == "motion_notify_event" and event.button is None:
+        event.button = event.canvas._button
+    if event.key is None:
+        event.key = event.canvas._key
+    # Emit axes_enter/axes_leave.
+    if event.name == "motion_notify_event":
+        last_ref = LocationEvent._last_axes_ref
+        last_axes = last_ref() if last_ref else None
+        if last_axes != event.inaxes:
+            if last_axes is not None:
+                # Create a synthetic LocationEvent for the axes_leave_event.
+                # Its inaxes attribute needs to be manually set (because the
+                # cursor is actually *out* of that Axes at that point); this is
+                # done with the internal _set_inaxes method which ensures that
+                # the xdata and ydata attributes are also correct.
+                try:
+                    canvas = last_axes.get_figure(root=True).canvas
+                    leave_event = LocationEvent(
+                        "axes_leave_event", canvas,
+                        event.x, event.y, event.guiEvent,
+                        modifiers=event.modifiers)
+                    leave_event._set_inaxes(last_axes)
+                    canvas.callbacks.process("axes_leave_event", leave_event)
+                except Exception:
+                    pass  # The last canvas may already have been torn down.
+            if event.inaxes is not None:
+                event.canvas.callbacks.process("axes_enter_event", event)
+        LocationEvent._last_axes_ref = (
+            weakref.ref(event.inaxes) if event.inaxes else None)
+
+
+def _get_renderer(figure, print_method=None):
+    """
+    Get the renderer that would be used to save a `.Figure`.
+
+    If you need a renderer without any active draw methods use
+    renderer._draw_disabled to temporary patch them out at your call site.
+    """
+    # This is implemented by triggering a draw, then immediately jumping out of
+    # Figure.draw() by raising an exception.
+
+    class Done(Exception):
+        pass
+
+    def _draw(renderer): raise Done(renderer)
+
+    with cbook._setattr_cm(figure, draw=_draw), ExitStack() as stack:
+        if print_method is None:
+            fmt = figure.canvas.get_default_filetype()
+            # Even for a canvas' default output type, a canvas switch may be
+            # needed, e.g. for FigureCanvasBase.
+            print_method = stack.enter_context(
+                figure.canvas._switch_canvas_and_return_print_method(fmt))
+        try:
+            print_method(io.BytesIO())
+        except Done as exc:
+            renderer, = exc.args
+            return renderer
+        else:
+            raise RuntimeError(f"{print_method} did not call Figure.draw, so "
+                               f"no renderer is available")
+
+
+def _no_output_draw(figure):
+    # _no_output_draw was promoted to the figure level, but
+    # keep this here in case someone was calling it...
+    figure.draw_without_rendering()
+
+
+def _is_non_interactive_terminal_ipython(ip):
+    """
+    Return whether we are in a terminal IPython, but non interactive.
+
+    When in _terminal_ IPython, ip.parent will have and `interact` attribute,
+    if this attribute is False we do not setup eventloop integration as the
+    user will _not_ interact with IPython. In all other case (ZMQKernel, or is
+    interactive), we do.
+    """
+    return (hasattr(ip, 'parent')
+            and (ip.parent is not None)
+            and getattr(ip.parent, 'interact', None) is False)
+
+
+@contextmanager
+def _allow_interrupt(prepare_notifier, handle_sigint):
+    """
+    A context manager that allows terminating a plot by sending a SIGINT.  It
+    is necessary because the running backend prevents the Python interpreter
+    from running and processing signals (i.e., to raise a KeyboardInterrupt).
+    To solve this, one needs to somehow wake up the interpreter and make it
+    close the plot window.  We do this by using the signal.set_wakeup_fd()
+    function which organizes a write of the signal number into a socketpair.
+    A backend-specific function, *prepare_notifier*, arranges to listen to
+    the pair's read socket while the event loop is running.  (If it returns a
+    notifier object, that object is kept alive while the context manager runs.)
+
+    If SIGINT was indeed caught, after exiting the on_signal() function the
+    interpreter reacts to the signal according to the handler function which
+    had been set up by a signal.signal() call; here, we arrange to call the
+    backend-specific *handle_sigint* function.  Finally, we call the old SIGINT
+    handler with the same arguments that were given to our custom handler.
+
+    We do this only if the old handler for SIGINT was not None, which means
+    that a non-python handler was installed, i.e. in Julia, and not SIG_IGN
+    which means we should ignore the interrupts.
+
+    Parameters
+    ----------
+    prepare_notifier : Callable[[socket.socket], object]
+    handle_sigint : Callable[[], object]
+    """
+
+    old_sigint_handler = signal.getsignal(signal.SIGINT)
+    if old_sigint_handler in (None, signal.SIG_IGN, signal.SIG_DFL):
+        yield
+        return
+
+    handler_args = None
+    wsock, rsock = socket.socketpair()
+    wsock.setblocking(False)
+    rsock.setblocking(False)
+    old_wakeup_fd = signal.set_wakeup_fd(wsock.fileno())
+    notifier = prepare_notifier(rsock)
+
+    def save_args_and_handle_sigint(*args):
+        nonlocal handler_args
+        handler_args = args
+        handle_sigint()
+
+    signal.signal(signal.SIGINT, save_args_and_handle_sigint)
+    try:
+        yield
+    finally:
+        wsock.close()
+        rsock.close()
+        signal.set_wakeup_fd(old_wakeup_fd)
+        signal.signal(signal.SIGINT, old_sigint_handler)
+        if handler_args is not None:
+            old_sigint_handler(*handler_args)
+
+
+class FigureCanvasBase:
+    """
+    The canvas the figure renders into.
+
+    Attributes
+    ----------
+    figure : `~matplotlib.figure.Figure`
+        A high-level figure instance.
+    """
+
+    # Set to one of {"qt", "gtk3", "gtk4", "wx", "tk", "macosx"} if an
+    # interactive framework is required, or None otherwise.
+    required_interactive_framework = None
+
+    # The manager class instantiated by new_manager.
+    # (This is defined as a classproperty because the manager class is
+    # currently defined *after* the canvas class, but one could also assign
+    # ``FigureCanvasBase.manager_class = FigureManagerBase``
+    # after defining both classes.)
+    manager_class = _api.classproperty(lambda cls: FigureManagerBase)
+
+    events = [
+        'resize_event',
+        'draw_event',
+        'key_press_event',
+        'key_release_event',
+        'button_press_event',
+        'button_release_event',
+        'scroll_event',
+        'motion_notify_event',
+        'pick_event',
+        'figure_enter_event',
+        'figure_leave_event',
+        'axes_enter_event',
+        'axes_leave_event',
+        'close_event'
+    ]
+
+    fixed_dpi = None
+
+    filetypes = _default_filetypes
+
+    @_api.classproperty
+    def supports_blit(cls):
+        """If this Canvas sub-class supports blitting."""
+        return (hasattr(cls, "copy_from_bbox")
+                and hasattr(cls, "restore_region"))
+
+    def __init__(self, figure=None):
+        from matplotlib.figure import Figure
+        self._fix_ipython_backend2gui()
+        self._is_idle_drawing = True
+        self._is_saving = False
+        if figure is None:
+            figure = Figure()
+        figure.set_canvas(self)
+        self.figure = figure
+        self.manager = None
+        self.widgetlock = widgets.LockDraw()
+        self._button = None  # the button pressed
+        self._key = None  # the key pressed
+        self.mouse_grabber = None  # the Axes currently grabbing mouse
+        self.toolbar = None  # NavigationToolbar2 will set me
+        self._is_idle_drawing = False
+        # We don't want to scale up the figure DPI more than once.
+        figure._original_dpi = figure.dpi
+        self._device_pixel_ratio = 1
+        super().__init__()  # Typically the GUI widget init (if any).
+
+    callbacks = property(lambda self: self.figure._canvas_callbacks)
+    button_pick_id = property(lambda self: self.figure._button_pick_id)
+    scroll_pick_id = property(lambda self: self.figure._scroll_pick_id)
+
+    @classmethod
+    @functools.cache
+    def _fix_ipython_backend2gui(cls):
+        # Fix hard-coded module -> toolkit mapping in IPython (used for
+        # `ipython --auto`).  This cannot be done at import time due to
+        # ordering issues, so we do it when creating a canvas, and should only
+        # be done once per class (hence the `cache`).
+
+        # This function will not be needed when Python 3.12, the latest version
+        # supported by IPython < 8.24, reaches end-of-life in late 2028.
+        # At that time this function can be made a no-op and deprecated.
+        mod_ipython = sys.modules.get("IPython")
+        if mod_ipython is None or mod_ipython.version_info[:2] >= (8, 24):
+            # Use of backend2gui is not needed for IPython >= 8.24 as the
+            # functionality has been moved to Matplotlib.
+            return
+
+        import IPython
+        ip = IPython.get_ipython()
+        if not ip:
+            return
+        from IPython.core import pylabtools as pt
+        if (not hasattr(pt, "backend2gui")
+                or not hasattr(ip, "enable_matplotlib")):
+            # In case we ever move the patch to IPython and remove these APIs,
+            # don't break on our side.
+            return
+        backend2gui_rif = {
+            "qt": "qt",
+            "gtk3": "gtk3",
+            "gtk4": "gtk4",
+            "wx": "wx",
+            "macosx": "osx",
+        }.get(cls.required_interactive_framework)
+        if backend2gui_rif:
+            if _is_non_interactive_terminal_ipython(ip):
+                ip.enable_gui(backend2gui_rif)
+
+    @classmethod
+    def new_manager(cls, figure, num):
+        """
+        Create a new figure manager for *figure*, using this canvas class.
+
+        Notes
+        -----
+        This method should not be reimplemented in subclasses.  If
+        custom manager creation logic is needed, please reimplement
+        ``FigureManager.create_with_canvas``.
+        """
+        return cls.manager_class.create_with_canvas(cls, figure, num)
+
+    @contextmanager
+    def _idle_draw_cntx(self):
+        self._is_idle_drawing = True
+        try:
+            yield
+        finally:
+            self._is_idle_drawing = False
+
+    def is_saving(self):
+        """
+        Return whether the renderer is in the process of saving
+        to a file, rather than rendering for an on-screen buffer.
+        """
+        return self._is_saving
+
+    def blit(self, bbox=None):
+        """Blit the canvas in bbox (default entire canvas)."""
+
+    def inaxes(self, xy):
+        """
+        Return the topmost visible `~.axes.Axes` containing the point *xy*.
+
+        Parameters
+        ----------
+        xy : (float, float)
+            (x, y) pixel positions from left/bottom of the canvas.
+
+        Returns
+        -------
+        `~matplotlib.axes.Axes` or None
+            The topmost visible Axes containing the point, or None if there
+            is no Axes at the point.
+        """
+        axes_list = [a for a in self.figure.get_axes()
+                     if a.patch.contains_point(xy) and a.get_visible()]
+        if axes_list:
+            axes = cbook._topmost_artist(axes_list)
+        else:
+            axes = None
+
+        return axes
+
+    def grab_mouse(self, ax):
+        """
+        Set the child `~.axes.Axes` which is grabbing the mouse events.
+
+        Usually called by the widgets themselves. It is an error to call this
+        if the mouse is already grabbed by another Axes.
+        """
+        if self.mouse_grabber not in (None, ax):
+            raise RuntimeError("Another Axes already grabs mouse input")
+        self.mouse_grabber = ax
+
+    def release_mouse(self, ax):
+        """
+        Release the mouse grab held by the `~.axes.Axes` *ax*.
+
+        Usually called by the widgets. It is ok to call this even if *ax*
+        doesn't have the mouse grab currently.
+        """
+        if self.mouse_grabber is ax:
+            self.mouse_grabber = None
+
+    def set_cursor(self, cursor):
+        """
+        Set the current cursor.
+
+        This may have no effect if the backend does not display anything.
+
+        If required by the backend, this method should trigger an update in
+        the backend event loop after the cursor is set, as this method may be
+        called e.g. before a long-running task during which the GUI is not
+        updated.
+
+        Parameters
+        ----------
+        cursor : `.Cursors`
+            The cursor to display over the canvas. Note: some backends may
+            change the cursor for the entire window.
+        """
+
+    def draw(self, *args, **kwargs):
+        """
+        Render the `.Figure`.
+
+        This method must walk the artist tree, even if no output is produced,
+        because it triggers deferred work that users may want to access
+        before saving output to disk. For example computing limits,
+        auto-limits, and tick values.
+        """
+
+    def draw_idle(self, *args, **kwargs):
+        """
+        Request a widget redraw once control returns to the GUI event loop.
+
+        Even if multiple calls to `draw_idle` occur before control returns
+        to the GUI event loop, the figure will only be rendered once.
+
+        Notes
+        -----
+        Backends may choose to override the method and implement their own
+        strategy to prevent multiple renderings.
+
+        """
+        if not self._is_idle_drawing:
+            with self._idle_draw_cntx():
+                self.draw(*args, **kwargs)
+
+    @property
+    def device_pixel_ratio(self):
+        """
+        The ratio of physical to logical pixels used for the canvas on screen.
+
+        By default, this is 1, meaning physical and logical pixels are the same
+        size. Subclasses that support High DPI screens may set this property to
+        indicate that said ratio is different. All Matplotlib interaction,
+        unless working directly with the canvas, remains in logical pixels.
+
+        """
+        return self._device_pixel_ratio
+
+    def _set_device_pixel_ratio(self, ratio):
+        """
+        Set the ratio of physical to logical pixels used for the canvas.
+
+        Subclasses that support High DPI screens can set this property to
+        indicate that said ratio is different. The canvas itself will be
+        created at the physical size, while the client side will use the
+        logical size. Thus the DPI of the Figure will change to be scaled by
+        this ratio. Implementations that support High DPI screens should use
+        physical pixels for events so that transforms back to Axes space are
+        correct.
+
+        By default, this is 1, meaning physical and logical pixels are the same
+        size.
+
+        Parameters
+        ----------
+        ratio : float
+            The ratio of logical to physical pixels used for the canvas.
+
+        Returns
+        -------
+        bool
+            Whether the ratio has changed. Backends may interpret this as a
+            signal to resize the window, repaint the canvas, or change any
+            other relevant properties.
+        """
+        if self._device_pixel_ratio == ratio:
+            return False
+        # In cases with mixed resolution displays, we need to be careful if the
+        # device pixel ratio changes - in this case we need to resize the
+        # canvas accordingly. Some backends provide events that indicate a
+        # change in DPI, but those that don't will update this before drawing.
+        dpi = ratio * self.figure._original_dpi
+        self.figure._set_dpi(dpi, forward=False)
+        self._device_pixel_ratio = ratio
+        return True
+
+    def get_width_height(self, *, physical=False):
+        """
+        Return the figure width and height in integral points or pixels.
+
+        When the figure is used on High DPI screens (and the backend supports
+        it), the truncation to integers occurs after scaling by the device
+        pixel ratio.
+
+        Parameters
+        ----------
+        physical : bool, default: False
+            Whether to return true physical pixels or logical pixels. Physical
+            pixels may be used by backends that support HiDPI, but still
+            configure the canvas using its actual size.
+
+        Returns
+        -------
+        width, height : int
+            The size of the figure, in points or pixels, depending on the
+            backend.
+        """
+        return tuple(int(size / (1 if physical else self.device_pixel_ratio))
+                     for size in self.figure.bbox.max)
+
+    @classmethod
+    def get_supported_filetypes(cls):
+        """Return dict of savefig file formats supported by this backend."""
+        return cls.filetypes
+
+    @classmethod
+    def get_supported_filetypes_grouped(cls):
+        """
+        Return a dict of savefig file formats supported by this backend,
+        where the keys are a file type name, such as 'Joint Photographic
+        Experts Group', and the values are a list of filename extensions used
+        for that filetype, such as ['jpg', 'jpeg'].
+        """
+        groupings = {}
+        for ext, name in cls.filetypes.items():
+            groupings.setdefault(name, []).append(ext)
+            groupings[name].sort()
+        return groupings
+
+    @contextmanager
+    def _switch_canvas_and_return_print_method(self, fmt, backend=None):
+        """
+        Context manager temporarily setting the canvas for saving the figure::
+
+            with (canvas._switch_canvas_and_return_print_method(fmt, backend)
+                  as print_method):
+                # ``print_method`` is a suitable ``print_{fmt}`` method, and
+                # the figure's canvas is temporarily switched to the method's
+                # canvas within the with... block.  ``print_method`` is also
+                # wrapped to suppress extra kwargs passed by ``print_figure``.
+
+        Parameters
+        ----------
+        fmt : str
+            If *backend* is None, then determine a suitable canvas class for
+            saving to format *fmt* -- either the current canvas class, if it
+            supports *fmt*, or whatever `get_registered_canvas_class` returns;
+            switch the figure canvas to that canvas class.
+        backend : str or None, default: None
+            If not None, switch the figure canvas to the ``FigureCanvas`` class
+            of the given backend.
+        """
+        canvas = None
+        if backend is not None:
+            # Return a specific canvas class, if requested.
+            from .backends.registry import backend_registry
+            canvas_class = backend_registry.load_backend_module(backend).FigureCanvas
+            if not hasattr(canvas_class, f"print_{fmt}"):
+                raise ValueError(
+                    f"The {backend!r} backend does not support {fmt} output")
+            canvas = canvas_class(self.figure)
+        elif hasattr(self, f"print_{fmt}"):
+            # Return the current canvas if it supports the requested format.
+            canvas = self
+        else:
+            # Return a default canvas for the requested format, if it exists.
+            canvas_class = get_registered_canvas_class(fmt)
+            if canvas_class is None:
+                raise ValueError(
+                    "Format {!r} is not supported (supported formats: {})".format(
+                        fmt, ", ".join(sorted(self.get_supported_filetypes()))))
+            canvas = canvas_class(self.figure)
+        canvas._is_saving = self._is_saving
+        meth = getattr(canvas, f"print_{fmt}")
+        mod = (meth.func.__module__
+               if hasattr(meth, "func")  # partialmethod, e.g. backend_wx.
+               else meth.__module__)
+        if mod.startswith(("matplotlib.", "mpl_toolkits.")):
+            optional_kws = {  # Passed by print_figure for other renderers.
+                "dpi", "facecolor", "edgecolor", "orientation",
+                "bbox_inches_restore"}
+            skip = optional_kws - {*inspect.signature(meth).parameters}
+            print_method = functools.wraps(meth)(lambda *args, **kwargs: meth(
+                *args, **{k: v for k, v in kwargs.items() if k not in skip}))
+        else:  # Let third-parties do as they see fit.
+            print_method = meth
+        try:
+            yield print_method
+        finally:
+            self.figure.canvas = self
+
+    def print_figure(
+            self, filename, dpi=None, facecolor=None, edgecolor=None,
+            orientation='portrait', format=None, *,
+            bbox_inches=None, pad_inches=None, bbox_extra_artists=None,
+            backend=None, **kwargs):
+        """
+        Render the figure to hardcopy. Set the figure patch face and edge
+        colors.  This is useful because some of the GUIs have a gray figure
+        face color background and you'll probably want to override this on
+        hardcopy.
+
+        Parameters
+        ----------
+        filename : str or path-like or file-like
+            The file where the figure is saved.
+
+        dpi : float, default: :rc:`savefig.dpi`
+            The dots per inch to save the figure in.
+
+        facecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.facecolor`
+            The facecolor of the figure.  If 'auto', use the current figure
+            facecolor.
+
+        edgecolor : :mpltype:`color` or 'auto', default: :rc:`savefig.edgecolor`
+            The edgecolor of the figure.  If 'auto', use the current figure
+            edgecolor.
+
+        orientation : {'landscape', 'portrait'}, default: 'portrait'
+            Only currently applies to PostScript printing.
+
+        format : str, optional
+            Force a specific file format. If not given, the format is inferred
+            from the *filename* extension, and if that fails from
+            :rc:`savefig.format`.
+
+        bbox_inches : 'tight' or `.Bbox`, default: :rc:`savefig.bbox`
+            Bounding box in inches: only the given portion of the figure is
+            saved.  If 'tight', try to figure out the tight bbox of the figure.
+
+        pad_inches : float or 'layout', default: :rc:`savefig.pad_inches`
+            Amount of padding in inches around the figure when bbox_inches is
+            'tight'. If 'layout' use the padding from the constrained or
+            compressed layout engine; ignored if one of those engines is not in
+            use.
+
+        bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional
+            A list of extra artists that will be considered when the
+            tight bbox is calculated.
+
+        backend : str, optional
+            Use a non-default backend to render the file, e.g. to render a
+            png file with the "cairo" backend rather than the default "agg",
+            or a pdf file with the "pgf" backend rather than the default
+            "pdf".  Note that the default backend is normally sufficient.  See
+            :ref:`the-builtin-backends` for a list of valid backends for each
+            file format.  Custom backends can be referenced as "module://...".
+        """
+        if format is None:
+            # get format from filename, or from backend's default filetype
+            if isinstance(filename, os.PathLike):
+                filename = os.fspath(filename)
+            if isinstance(filename, str):
+                format = os.path.splitext(filename)[1][1:]
+            if format is None or format == '':
+                format = self.get_default_filetype()
+                if isinstance(filename, str):
+                    filename = filename.rstrip('.') + '.' + format
+        format = format.lower()
+
+        if dpi is None:
+            dpi = rcParams['savefig.dpi']
+        if dpi == 'figure':
+            dpi = getattr(self.figure, '_original_dpi', self.figure.dpi)
+
+        # Remove the figure manager, if any, to avoid resizing the GUI widget.
+        with (cbook._setattr_cm(self, manager=None),
+              self._switch_canvas_and_return_print_method(format, backend)
+                 as print_method,
+              cbook._setattr_cm(self.figure, dpi=dpi),
+              cbook._setattr_cm(self.figure.canvas, _device_pixel_ratio=1),
+              cbook._setattr_cm(self.figure.canvas, _is_saving=True),
+              ExitStack() as stack):
+
+            for prop in ["facecolor", "edgecolor"]:
+                color = locals()[prop]
+                if color is None:
+                    color = rcParams[f"savefig.{prop}"]
+                if not cbook._str_equal(color, "auto"):
+                    stack.enter_context(self.figure._cm_set(**{prop: color}))
+
+            if bbox_inches is None:
+                bbox_inches = rcParams['savefig.bbox']
+
+            layout_engine = self.figure.get_layout_engine()
+            if layout_engine is not None or bbox_inches == "tight":
+                # we need to trigger a draw before printing to make sure
+                # CL works.  "tight" also needs a draw to get the right
+                # locations:
+                renderer = _get_renderer(
+                    self.figure,
+                    functools.partial(
+                        print_method, orientation=orientation)
+                )
+                # we do this instead of `self.figure.draw_without_rendering`
+                # so that we can inject the orientation
+                with getattr(renderer, "_draw_disabled", nullcontext)():
+                    self.figure.draw(renderer)
+            if bbox_inches:
+                if bbox_inches == "tight":
+                    bbox_inches = self.figure.get_tightbbox(
+                        renderer, bbox_extra_artists=bbox_extra_artists)
+                    if (isinstance(layout_engine, ConstrainedLayoutEngine) and
+                            pad_inches == "layout"):
+                        h_pad = layout_engine.get()["h_pad"]
+                        w_pad = layout_engine.get()["w_pad"]
+                    else:
+                        if pad_inches in [None, "layout"]:
+                            pad_inches = rcParams['savefig.pad_inches']
+                        h_pad = w_pad = pad_inches
+                    bbox_inches = bbox_inches.padded(w_pad, h_pad)
+
+                # call adjust_bbox to save only the given area
+                restore_bbox = _tight_bbox.adjust_bbox(
+                    self.figure, bbox_inches, self.figure.canvas.fixed_dpi)
+
+                _bbox_inches_restore = (bbox_inches, restore_bbox)
+            else:
+                _bbox_inches_restore = None
+
+            # we have already done layout above, so turn it off:
+            stack.enter_context(self.figure._cm_set(layout_engine='none'))
+            try:
+                # _get_renderer may change the figure dpi (as vector formats
+                # force the figure dpi to 72), so we need to set it again here.
+                with cbook._setattr_cm(self.figure, dpi=dpi):
+                    result = print_method(
+                        filename,
+                        facecolor=facecolor,
+                        edgecolor=edgecolor,
+                        orientation=orientation,
+                        bbox_inches_restore=_bbox_inches_restore,
+                        **kwargs)
+            finally:
+                if bbox_inches and restore_bbox:
+                    restore_bbox()
+
+            return result
+
+    @classmethod
+    def get_default_filetype(cls):
+        """
+        Return the default savefig file format as specified in
+        :rc:`savefig.format`.
+
+        The returned string does not include a period. This method is
+        overridden in backends that only support a single file type.
+        """
+        return rcParams['savefig.format']
+
+    def get_default_filename(self):
+        """
+        Return a suitable default filename, including the extension.
+        """
+        default_basename = (
+            self.manager.get_window_title()
+            if self.manager is not None
+            else ''
+        )
+        default_basename = default_basename or 'image'
+        # Characters to be avoided in a NT path:
+        # https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx#naming_conventions
+        # plus ' '
+        removed_chars = '<>:"/\\|?*\0 '
+        default_basename = default_basename.translate(
+            {ord(c): "_" for c in removed_chars})
+        default_filetype = self.get_default_filetype()
+        return f'{default_basename}.{default_filetype}'
+
+    def mpl_connect(self, s, func):
+        """
+        Bind function *func* to event *s*.
+
+        Parameters
+        ----------
+        s : str
+            One of the following events ids:
+
+            - 'button_press_event'
+            - 'button_release_event'
+            - 'draw_event'
+            - 'key_press_event'
+            - 'key_release_event'
+            - 'motion_notify_event'
+            - 'pick_event'
+            - 'resize_event'
+            - 'scroll_event'
+            - 'figure_enter_event',
+            - 'figure_leave_event',
+            - 'axes_enter_event',
+            - 'axes_leave_event'
+            - 'close_event'.
+
+        func : callable
+            The callback function to be executed, which must have the
+            signature::
+
+                def func(event: Event) -> Any
+
+            For the location events (button and key press/release), if the
+            mouse is over the Axes, the ``inaxes`` attribute of the event will
+            be set to the `~matplotlib.axes.Axes` the event occurs is over, and
+            additionally, the variables ``xdata`` and ``ydata`` attributes will
+            be set to the mouse location in data coordinates.  See `.KeyEvent`
+            and `.MouseEvent` for more info.
+
+            .. note::
+
+                If func is a method, this only stores a weak reference to the
+                method. Thus, the figure does not influence the lifetime of
+                the associated object. Usually, you want to make sure that the
+                object is kept alive throughout the lifetime of the figure by
+                holding a reference to it.
+
+        Returns
+        -------
+        cid
+            A connection id that can be used with
+            `.FigureCanvasBase.mpl_disconnect`.
+
+        Examples
+        --------
+        ::
+
+            def on_press(event):
+                print('you pressed', event.button, event.xdata, event.ydata)
+
+            cid = canvas.mpl_connect('button_press_event', on_press)
+        """
+
+        return self.callbacks.connect(s, func)
+
+    def mpl_disconnect(self, cid):
+        """
+        Disconnect the callback with id *cid*.
+
+        Examples
+        --------
+        ::
+
+            cid = canvas.mpl_connect('button_press_event', on_press)
+            # ... later
+            canvas.mpl_disconnect(cid)
+        """
+        self.callbacks.disconnect(cid)
+
+    # Internal subclasses can override _timer_cls instead of new_timer, though
+    # this is not a public API for third-party subclasses.
+    _timer_cls = TimerBase
+
+    def new_timer(self, interval=None, callbacks=None):
+        """
+        Create a new backend-specific subclass of `.Timer`.
+
+        This is useful for getting periodic events through the backend's native
+        event loop.  Implemented only for backends with GUIs.
+
+        Parameters
+        ----------
+        interval : int
+            Timer interval in milliseconds.
+
+        callbacks : list[tuple[callable, tuple, dict]]
+            Sequence of (func, args, kwargs) where ``func(*args, **kwargs)``
+            will be executed by the timer every *interval*.
+
+            Callbacks which return ``False`` or ``0`` will be removed from the
+            timer.
+
+        Examples
+        --------
+        >>> timer = fig.canvas.new_timer(callbacks=[(f1, (1,), {'a': 3})])
+        """
+        return self._timer_cls(interval=interval, callbacks=callbacks)
+
+    def flush_events(self):
+        """
+        Flush the GUI events for the figure.
+
+        Interactive backends need to reimplement this method.
+        """
+
+    def start_event_loop(self, timeout=0):
+        """
+        Start a blocking event loop.
+
+        Such an event loop is used by interactive functions, such as
+        `~.Figure.ginput` and `~.Figure.waitforbuttonpress`, to wait for
+        events.
+
+        The event loop blocks until a callback function triggers
+        `stop_event_loop`, or *timeout* is reached.
+
+        If *timeout* is 0 or negative, never timeout.
+
+        Only interactive backends need to reimplement this method and it relies
+        on `flush_events` being properly implemented.
+
+        Interactive backends should implement this in a more native way.
+        """
+        if timeout <= 0:
+            timeout = np.inf
+        timestep = 0.01
+        counter = 0
+        self._looping = True
+        while self._looping and counter * timestep < timeout:
+            self.flush_events()
+            time.sleep(timestep)
+            counter += 1
+
+    def stop_event_loop(self):
+        """
+        Stop the current blocking event loop.
+
+        Interactive backends need to reimplement this to match
+        `start_event_loop`
+        """
+        self._looping = False
+
+
+def key_press_handler(event, canvas=None, toolbar=None):
+    """
+    Implement the default Matplotlib key bindings for the canvas and toolbar
+    described at :ref:`key-event-handling`.
+
+    Parameters
+    ----------
+    event : `KeyEvent`
+        A key press/release event.
+    canvas : `FigureCanvasBase`, default: ``event.canvas``
+        The backend-specific canvas instance.  This parameter is kept for
+        back-compatibility, but, if set, should always be equal to
+        ``event.canvas``.
+    toolbar : `NavigationToolbar2`, default: ``event.canvas.toolbar``
+        The navigation cursor toolbar.  This parameter is kept for
+        back-compatibility, but, if set, should always be equal to
+        ``event.canvas.toolbar``.
+    """
+    if event.key is None:
+        return
+    if canvas is None:
+        canvas = event.canvas
+    if toolbar is None:
+        toolbar = canvas.toolbar
+
+    # toggle fullscreen mode (default key 'f', 'ctrl + f')
+    if event.key in rcParams['keymap.fullscreen']:
+        try:
+            canvas.manager.full_screen_toggle()
+        except AttributeError:
+            pass
+
+    # quit the figure (default key 'ctrl+w')
+    if event.key in rcParams['keymap.quit']:
+        Gcf.destroy_fig(canvas.figure)
+    if event.key in rcParams['keymap.quit_all']:
+        Gcf.destroy_all()
+
+    if toolbar is not None:
+        # home or reset mnemonic  (default key 'h', 'home' and 'r')
+        if event.key in rcParams['keymap.home']:
+            toolbar.home()
+        # forward / backward keys to enable left handed quick navigation
+        # (default key for backward: 'left', 'backspace' and 'c')
+        elif event.key in rcParams['keymap.back']:
+            toolbar.back()
+        # (default key for forward: 'right' and 'v')
+        elif event.key in rcParams['keymap.forward']:
+            toolbar.forward()
+        # pan mnemonic (default key 'p')
+        elif event.key in rcParams['keymap.pan']:
+            toolbar.pan()
+            toolbar._update_cursor(event)
+        # zoom mnemonic (default key 'o')
+        elif event.key in rcParams['keymap.zoom']:
+            toolbar.zoom()
+            toolbar._update_cursor(event)
+        # saving current figure (default key 's')
+        elif event.key in rcParams['keymap.save']:
+            toolbar.save_figure()
+
+    if event.inaxes is None:
+        return
+
+    # these bindings require the mouse to be over an Axes to trigger
+    def _get_uniform_gridstate(ticks):
+        # Return True/False if all grid lines are on or off, None if they are
+        # not all in the same state.
+        return (True if all(tick.gridline.get_visible() for tick in ticks) else
+                False if not any(tick.gridline.get_visible() for tick in ticks) else
+                None)
+
+    ax = event.inaxes
+    # toggle major grids in current Axes (default key 'g')
+    # Both here and below (for 'G'), we do nothing if *any* grid (major or
+    # minor, x or y) is not in a uniform state, to avoid messing up user
+    # customization.
+    if (event.key in rcParams['keymap.grid']
+            # Exclude minor grids not in a uniform state.
+            and None not in [_get_uniform_gridstate(ax.xaxis.minorTicks),
+                             _get_uniform_gridstate(ax.yaxis.minorTicks)]):
+        x_state = _get_uniform_gridstate(ax.xaxis.majorTicks)
+        y_state = _get_uniform_gridstate(ax.yaxis.majorTicks)
+        cycle = [(False, False), (True, False), (True, True), (False, True)]
+        try:
+            x_state, y_state = (
+                cycle[(cycle.index((x_state, y_state)) + 1) % len(cycle)])
+        except ValueError:
+            # Exclude major grids not in a uniform state.
+            pass
+        else:
+            # If turning major grids off, also turn minor grids off.
+            ax.grid(x_state, which="major" if x_state else "both", axis="x")
+            ax.grid(y_state, which="major" if y_state else "both", axis="y")
+            canvas.draw_idle()
+    # toggle major and minor grids in current Axes (default key 'G')
+    if (event.key in rcParams['keymap.grid_minor']
+            # Exclude major grids not in a uniform state.
+            and None not in [_get_uniform_gridstate(ax.xaxis.majorTicks),
+                             _get_uniform_gridstate(ax.yaxis.majorTicks)]):
+        x_state = _get_uniform_gridstate(ax.xaxis.minorTicks)
+        y_state = _get_uniform_gridstate(ax.yaxis.minorTicks)
+        cycle = [(False, False), (True, False), (True, True), (False, True)]
+        try:
+            x_state, y_state = (
+                cycle[(cycle.index((x_state, y_state)) + 1) % len(cycle)])
+        except ValueError:
+            # Exclude minor grids not in a uniform state.
+            pass
+        else:
+            ax.grid(x_state, which="both", axis="x")
+            ax.grid(y_state, which="both", axis="y")
+            canvas.draw_idle()
+    # toggle scaling of y-axes between 'log and 'linear' (default key 'l')
+    elif event.key in rcParams['keymap.yscale']:
+        scale = ax.get_yscale()
+        if scale == 'log':
+            ax.set_yscale('linear')
+            ax.get_figure(root=True).canvas.draw_idle()
+        elif scale == 'linear':
+            try:
+                ax.set_yscale('log')
+            except ValueError as exc:
+                _log.warning(str(exc))
+                ax.set_yscale('linear')
+            ax.get_figure(root=True).canvas.draw_idle()
+    # toggle scaling of x-axes between 'log and 'linear' (default key 'k')
+    elif event.key in rcParams['keymap.xscale']:
+        scalex = ax.get_xscale()
+        if scalex == 'log':
+            ax.set_xscale('linear')
+            ax.get_figure(root=True).canvas.draw_idle()
+        elif scalex == 'linear':
+            try:
+                ax.set_xscale('log')
+            except ValueError as exc:
+                _log.warning(str(exc))
+                ax.set_xscale('linear')
+            ax.get_figure(root=True).canvas.draw_idle()
+
+
+def button_press_handler(event, canvas=None, toolbar=None):
+    """
+    The default Matplotlib button actions for extra mouse buttons.
+
+    Parameters are as for `key_press_handler`, except that *event* is a
+    `MouseEvent`.
+    """
+    if canvas is None:
+        canvas = event.canvas
+    if toolbar is None:
+        toolbar = canvas.toolbar
+    if toolbar is not None:
+        button_name = str(MouseButton(event.button))
+        if button_name in rcParams['keymap.back']:
+            toolbar.back()
+        elif button_name in rcParams['keymap.forward']:
+            toolbar.forward()
+
+
+class NonGuiException(Exception):
+    """Raised when trying show a figure in a non-GUI backend."""
+    pass
+
+
+class FigureManagerBase:
+    """
+    A backend-independent abstraction of a figure container and controller.
+
+    The figure manager is used by pyplot to interact with the window in a
+    backend-independent way. It's an adapter for the real (GUI) framework that
+    represents the visual figure on screen.
+
+    The figure manager is connected to a specific canvas instance, which in turn
+    is connected to a specific figure instance. To access a figure manager for
+    a given figure in user code, you typically use ``fig.canvas.manager``.
+
+    GUI backends derive from this class to translate common operations such
+    as *show* or *resize* to the GUI-specific code. Non-GUI backends do not
+    support these operations and can just use the base class.
+
+    This following basic operations are accessible:
+
+    **Window operations**
+
+    - `~.FigureManagerBase.show`
+    - `~.FigureManagerBase.destroy`
+    - `~.FigureManagerBase.full_screen_toggle`
+    - `~.FigureManagerBase.resize`
+    - `~.FigureManagerBase.get_window_title`
+    - `~.FigureManagerBase.set_window_title`
+
+    **Key and mouse button press handling**
+
+    The figure manager sets up default key and mouse button press handling by
+    hooking up the `.key_press_handler` to the matplotlib event system. This
+    ensures the same shortcuts and mouse actions across backends.
+
+    **Other operations**
+
+    Subclasses will have additional attributes and functions to access
+    additional functionality. This is of course backend-specific. For example,
+    most GUI backends have ``window`` and ``toolbar`` attributes that give
+    access to the native GUI widgets of the respective framework.
+
+    Attributes
+    ----------
+    canvas : `FigureCanvasBase`
+        The backend-specific canvas instance.
+
+    num : int or str
+        The figure number.
+
+    key_press_handler_id : int
+        The default key handler cid, when using the toolmanager.
+        To disable the default key press handling use::
+
+            figure.canvas.mpl_disconnect(
+                figure.canvas.manager.key_press_handler_id)
+
+    button_press_handler_id : int
+        The default mouse button handler cid, when using the toolmanager.
+        To disable the default button press handling use::
+
+            figure.canvas.mpl_disconnect(
+                figure.canvas.manager.button_press_handler_id)
+    """
+
+    _toolbar2_class = None
+    _toolmanager_toolbar_class = None
+
+    def __init__(self, canvas, num):
+        self.canvas = canvas
+        canvas.manager = self  # store a pointer to parent
+        self.num = num
+        self.set_window_title(f"Figure {num:d}")
+
+        self.key_press_handler_id = None
+        self.button_press_handler_id = None
+        if rcParams['toolbar'] != 'toolmanager':
+            self.key_press_handler_id = self.canvas.mpl_connect(
+                'key_press_event', key_press_handler)
+            self.button_press_handler_id = self.canvas.mpl_connect(
+                'button_press_event', button_press_handler)
+
+        self.toolmanager = (ToolManager(canvas.figure)
+                            if mpl.rcParams['toolbar'] == 'toolmanager'
+                            else None)
+        if (mpl.rcParams["toolbar"] == "toolbar2"
+                and self._toolbar2_class):
+            self.toolbar = self._toolbar2_class(self.canvas)
+        elif (mpl.rcParams["toolbar"] == "toolmanager"
+                and self._toolmanager_toolbar_class):
+            self.toolbar = self._toolmanager_toolbar_class(self.toolmanager)
+        else:
+            self.toolbar = None
+
+        if self.toolmanager:
+            tools.add_tools_to_manager(self.toolmanager)
+            if self.toolbar:
+                tools.add_tools_to_container(self.toolbar)
+
+        @self.canvas.figure.add_axobserver
+        def notify_axes_change(fig):
+            # Called whenever the current Axes is changed.
+            if self.toolmanager is None and self.toolbar is not None:
+                self.toolbar.update()
+
+    @classmethod
+    def create_with_canvas(cls, canvas_class, figure, num):
+        """
+        Create a manager for a given *figure* using a specific *canvas_class*.
+
+        Backends should override this method if they have specific needs for
+        setting up the canvas or the manager.
+        """
+        return cls(canvas_class(figure), num)
+
+    @classmethod
+    def start_main_loop(cls):
+        """
+        Start the main event loop.
+
+        This method is called by `.FigureManagerBase.pyplot_show`, which is the
+        implementation of `.pyplot.show`.  To customize the behavior of
+        `.pyplot.show`, interactive backends should usually override
+        `~.FigureManagerBase.start_main_loop`; if more customized logic is
+        necessary, `~.FigureManagerBase.pyplot_show` can also be overridden.
+        """
+
+    @classmethod
+    def pyplot_show(cls, *, block=None):
+        """
+        Show all figures.  This method is the implementation of `.pyplot.show`.
+
+        To customize the behavior of `.pyplot.show`, interactive backends
+        should usually override `~.FigureManagerBase.start_main_loop`; if more
+        customized logic is necessary, `~.FigureManagerBase.pyplot_show` can
+        also be overridden.
+
+        Parameters
+        ----------
+        block : bool, optional
+            Whether to block by calling ``start_main_loop``.  The default,
+            None, means to block if we are neither in IPython's ``%pylab`` mode
+            nor in ``interactive`` mode.
+        """
+        managers = Gcf.get_all_fig_managers()
+        if not managers:
+            return
+        for manager in managers:
+            try:
+                manager.show()  # Emits a warning for non-interactive backend.
+            except NonGuiException as exc:
+                _api.warn_external(str(exc))
+        if block is None:
+            # Hack: Are we in IPython's %pylab mode?  In pylab mode, IPython
+            # (>= 0.10) tacks a _needmain attribute onto pyplot.show (always
+            # set to False).
+            pyplot_show = getattr(sys.modules.get("matplotlib.pyplot"), "show", None)
+            ipython_pylab = hasattr(pyplot_show, "_needmain")
+            block = not ipython_pylab and not is_interactive()
+        if block:
+            cls.start_main_loop()
+
+    def show(self):
+        """
+        For GUI backends, show the figure window and redraw.
+        For non-GUI backends, raise an exception, unless running headless (i.e.
+        on Linux with an unset DISPLAY); this exception is converted to a
+        warning in `.Figure.show`.
+        """
+        # This should be overridden in GUI backends.
+        if sys.platform == "linux" and not os.environ.get("DISPLAY"):
+            # We cannot check _get_running_interactive_framework() ==
+            # "headless" because that would also suppress the warning when
+            # $DISPLAY exists but is invalid, which is more likely an error and
+            # thus warrants a warning.
+            return
+        raise NonGuiException(
+            f"{type(self.canvas).__name__} is non-interactive, and thus cannot be "
+            f"shown")
+
+    def destroy(self):
+        pass
+
+    def full_screen_toggle(self):
+        pass
+
+    def resize(self, w, h):
+        """For GUI backends, resize the window (in physical pixels)."""
+
+    def get_window_title(self):
+        """Return the title text of the window containing the figure."""
+        return self._window_title
+
+    def set_window_title(self, title):
+        """
+        Set the title text of the window containing the figure.
+
+        Examples
+        --------
+        >>> fig = plt.figure()
+        >>> fig.canvas.manager.set_window_title('My figure')
+        """
+        # This attribute is not defined in __init__ (but __init__ calls this
+        # setter), as derived classes (real GUI managers) will store this
+        # information directly on the widget; only the base (non-GUI) manager
+        # class needs a specific attribute for it (so that filename escaping
+        # can be checked in the test suite).
+        self._window_title = title
+
+
+cursors = tools.cursors
+
+
+class _Mode(str, Enum):
+    NONE = ""
+    PAN = "pan/zoom"
+    ZOOM = "zoom rect"
+
+    def __str__(self):
+        return self.value
+
+    @property
+    def _navigate_mode(self):
+        return self.name if self is not _Mode.NONE else None
+
+
+class NavigationToolbar2:
+    """
+    Base class for the navigation cursor, version 2.
+
+    Backends must implement a canvas that handles connections for
+    'button_press_event' and 'button_release_event'.  See
+    :meth:`FigureCanvasBase.mpl_connect` for more information.
+
+    They must also define
+
+    :meth:`save_figure`
+        Save the current figure.
+
+    :meth:`draw_rubberband` (optional)
+        Draw the zoom to rect "rubberband" rectangle.
+
+    :meth:`set_message` (optional)
+        Display message.
+
+    :meth:`set_history_buttons` (optional)
+        You can change the history back / forward buttons to indicate disabled / enabled
+        state.
+
+    and override ``__init__`` to set up the toolbar -- without forgetting to
+    call the base-class init.  Typically, ``__init__`` needs to set up toolbar
+    buttons connected to the `home`, `back`, `forward`, `pan`, `zoom`, and
+    `save_figure` methods and using standard icons in the "images" subdirectory
+    of the data path.
+
+    That's it, we'll do the rest!
+    """
+
+    # list of toolitems to add to the toolbar, format is:
+    # (
+    #   text, # the text of the button (often not visible to users)
+    #   tooltip_text, # the tooltip shown on hover (where possible)
+    #   image_file, # name of the image for the button (without the extension)
+    #   name_of_method, # name of the method in NavigationToolbar2 to call
+    # )
+    toolitems = (
+        ('Home', 'Reset original view', 'home', 'home'),
+        ('Back', 'Back to previous view', 'back', 'back'),
+        ('Forward', 'Forward to next view', 'forward', 'forward'),
+        (None, None, None, None),
+        ('Pan',
+         'Left button pans, Right button zooms\n'
+         'x/y fixes axis, CTRL fixes aspect',
+         'move', 'pan'),
+        ('Zoom', 'Zoom to rectangle\nx/y fixes axis', 'zoom_to_rect', 'zoom'),
+        ('Subplots', 'Configure subplots', 'subplots', 'configure_subplots'),
+        (None, None, None, None),
+        ('Save', 'Save the figure', 'filesave', 'save_figure'),
+      )
+
+    UNKNOWN_SAVED_STATUS = object()
+
+    def __init__(self, canvas):
+        self.canvas = canvas
+        canvas.toolbar = self
+        self._nav_stack = cbook._Stack()
+        # This cursor will be set after the initial draw.
+        self._last_cursor = tools.Cursors.POINTER
+
+        self._id_press = self.canvas.mpl_connect(
+            'button_press_event', self._zoom_pan_handler)
+        self._id_release = self.canvas.mpl_connect(
+            'button_release_event', self._zoom_pan_handler)
+        self._id_drag = self.canvas.mpl_connect(
+            'motion_notify_event', self.mouse_move)
+        self._pan_info = None
+        self._zoom_info = None
+
+        self.mode = _Mode.NONE  # a mode string for the status bar
+        self.set_history_buttons()
+
+    def set_message(self, s):
+        """Display a message on toolbar or in status bar."""
+
+    def draw_rubberband(self, event, x0, y0, x1, y1):
+        """
+        Draw a rectangle rubberband to indicate zoom limits.
+
+        Note that it is not guaranteed that ``x0 <= x1`` and ``y0 <= y1``.
+        """
+
+    def remove_rubberband(self):
+        """Remove the rubberband."""
+
+    def home(self, *args):
+        """
+        Restore the original view.
+
+        For convenience of being directly connected as a GUI callback, which
+        often get passed additional parameters, this method accepts arbitrary
+        parameters, but does not use them.
+        """
+        self._nav_stack.home()
+        self.set_history_buttons()
+        self._update_view()
+
+    def back(self, *args):
+        """
+        Move back up the view lim stack.
+
+        For convenience of being directly connected as a GUI callback, which
+        often get passed additional parameters, this method accepts arbitrary
+        parameters, but does not use them.
+        """
+        self._nav_stack.back()
+        self.set_history_buttons()
+        self._update_view()
+
+    def forward(self, *args):
+        """
+        Move forward in the view lim stack.
+
+        For convenience of being directly connected as a GUI callback, which
+        often get passed additional parameters, this method accepts arbitrary
+        parameters, but does not use them.
+        """
+        self._nav_stack.forward()
+        self.set_history_buttons()
+        self._update_view()
+
+    def _update_cursor(self, event):
+        """
+        Update the cursor after a mouse move event or a tool (de)activation.
+        """
+        if self.mode and event.inaxes and event.inaxes.get_navigate():
+            if (self.mode == _Mode.ZOOM
+                    and self._last_cursor != tools.Cursors.SELECT_REGION):
+                self.canvas.set_cursor(tools.Cursors.SELECT_REGION)
+                self._last_cursor = tools.Cursors.SELECT_REGION
+            elif (self.mode == _Mode.PAN
+                  and self._last_cursor != tools.Cursors.MOVE):
+                self.canvas.set_cursor(tools.Cursors.MOVE)
+                self._last_cursor = tools.Cursors.MOVE
+        elif self._last_cursor != tools.Cursors.POINTER:
+            self.canvas.set_cursor(tools.Cursors.POINTER)
+            self._last_cursor = tools.Cursors.POINTER
+
+    @contextmanager
+    def _wait_cursor_for_draw_cm(self):
+        """
+        Set the cursor to a wait cursor when drawing the canvas.
+
+        In order to avoid constantly changing the cursor when the canvas
+        changes frequently, do nothing if this context was triggered during the
+        last second.  (Optimally we'd prefer only setting the wait cursor if
+        the *current* draw takes too long, but the current draw blocks the GUI
+        thread).
+        """
+        self._draw_time, last_draw_time = (
+            time.time(), getattr(self, "_draw_time", -np.inf))
+        if self._draw_time - last_draw_time > 1:
+            try:
+                self.canvas.set_cursor(tools.Cursors.WAIT)
+                yield
+            finally:
+                self.canvas.set_cursor(self._last_cursor)
+        else:
+            yield
+
+    @staticmethod
+    def _mouse_event_to_message(event):
+        if event.inaxes and event.inaxes.get_navigate():
+            try:
+                s = event.inaxes.format_coord(event.xdata, event.ydata)
+            except (ValueError, OverflowError):
+                pass
+            else:
+                s = s.rstrip()
+                artists = [a for a in event.inaxes._mouseover_set
+                           if a.contains(event)[0] and a.get_visible()]
+                if artists:
+                    a = cbook._topmost_artist(artists)
+                    if a is not event.inaxes.patch:
+                        data = a.get_cursor_data(event)
+                        if data is not None:
+                            data_str = a.format_cursor_data(data).rstrip()
+                            if data_str:
+                                s = s + '\n' + data_str
+                return s
+        return ""
+
+    def mouse_move(self, event):
+        self._update_cursor(event)
+        self.set_message(self._mouse_event_to_message(event))
+
+    def _zoom_pan_handler(self, event):
+        if self.mode == _Mode.PAN:
+            if event.name == "button_press_event":
+                self.press_pan(event)
+            elif event.name == "button_release_event":
+                self.release_pan(event)
+        if self.mode == _Mode.ZOOM:
+            if event.name == "button_press_event":
+                self.press_zoom(event)
+            elif event.name == "button_release_event":
+                self.release_zoom(event)
+
+    def _start_event_axes_interaction(self, event, *, method):
+
+        def _ax_filter(ax):
+            return (ax.in_axes(event) and
+                    ax.get_navigate() and
+                    getattr(ax, f"can_{method}")()
+                    )
+
+        def _capture_events(ax):
+            f = ax.get_forward_navigation_events()
+            if f == "auto":  # (capture = patch visibility)
+                f = not ax.patch.get_visible()
+            return not f
+
+        # get all relevant axes for the event
+        axes = list(filter(_ax_filter, self.canvas.figure.get_axes()))
+
+        if len(axes) == 0:
+            return []
+
+        if self._nav_stack() is None:
+            self.push_current()   # Set the home button to this view.
+
+        # group axes by zorder (reverse to trigger later axes first)
+        grps = dict()
+        for ax in reversed(axes):
+            grps.setdefault(ax.get_zorder(), []).append(ax)
+
+        axes_to_trigger = []
+        # go through zorders in reverse until we hit a capturing axes
+        for zorder in sorted(grps, reverse=True):
+            for ax in grps[zorder]:
+                axes_to_trigger.append(ax)
+                # NOTE: shared axes are automatically triggered, but twin-axes not!
+                axes_to_trigger.extend(ax._twinned_axes.get_siblings(ax))
+
+                if _capture_events(ax):
+                    break  # break if we hit a capturing axes
+            else:
+                # If the inner loop finished without an explicit break,
+                # (e.g. no capturing axes was found) continue the
+                # outer loop to the next zorder.
+                continue
+
+            # If the inner loop was terminated with an explicit break,
+            # terminate the outer loop as well.
+            break
+
+        # avoid duplicated triggers (but keep order of list)
+        axes_to_trigger = list(dict.fromkeys(axes_to_trigger))
+
+        return axes_to_trigger
+
+    def pan(self, *args):
+        """
+        Toggle the pan/zoom tool.
+
+        Pan with left button, zoom with right.
+        """
+        if not self.canvas.widgetlock.available(self):
+            self.set_message("pan unavailable")
+            return
+        if self.mode == _Mode.PAN:
+            self.mode = _Mode.NONE
+            self.canvas.widgetlock.release(self)
+        else:
+            self.mode = _Mode.PAN
+            self.canvas.widgetlock(self)
+        for a in self.canvas.figure.get_axes():
+            a.set_navigate_mode(self.mode._navigate_mode)
+
+    _PanInfo = namedtuple("_PanInfo", "button axes cid")
+
+    def press_pan(self, event):
+        """Callback for mouse button press in pan/zoom mode."""
+        if (event.button not in [MouseButton.LEFT, MouseButton.RIGHT]
+                or event.x is None or event.y is None):
+            return
+
+        axes = self._start_event_axes_interaction(event, method="pan")
+        if not axes:
+            return
+
+        # call "ax.start_pan(..)" on all relevant axes of an event
+        for ax in axes:
+            ax.start_pan(event.x, event.y, event.button)
+
+        self.canvas.mpl_disconnect(self._id_drag)
+        id_drag = self.canvas.mpl_connect("motion_notify_event", self.drag_pan)
+
+        self._pan_info = self._PanInfo(
+            button=event.button, axes=axes, cid=id_drag)
+
+    def drag_pan(self, event):
+        """Callback for dragging in pan/zoom mode."""
+        for ax in self._pan_info.axes:
+            # Using the recorded button at the press is safer than the current
+            # button, as multiple buttons can get pressed during motion.
+            ax.drag_pan(self._pan_info.button, event.key, event.x, event.y)
+        self.canvas.draw_idle()
+
+    def release_pan(self, event):
+        """Callback for mouse button release in pan/zoom mode."""
+        if self._pan_info is None:
+            return
+        self.canvas.mpl_disconnect(self._pan_info.cid)
+        self._id_drag = self.canvas.mpl_connect(
+            'motion_notify_event', self.mouse_move)
+        for ax in self._pan_info.axes:
+            ax.end_pan()
+        self.canvas.draw_idle()
+        self._pan_info = None
+        self.push_current()
+
+    def zoom(self, *args):
+        if not self.canvas.widgetlock.available(self):
+            self.set_message("zoom unavailable")
+            return
+        """Toggle zoom to rect mode."""
+        if self.mode == _Mode.ZOOM:
+            self.mode = _Mode.NONE
+            self.canvas.widgetlock.release(self)
+        else:
+            self.mode = _Mode.ZOOM
+            self.canvas.widgetlock(self)
+        for a in self.canvas.figure.get_axes():
+            a.set_navigate_mode(self.mode._navigate_mode)
+
+    _ZoomInfo = namedtuple("_ZoomInfo", "direction start_xy axes cid cbar")
+
+    def press_zoom(self, event):
+        """Callback for mouse button press in zoom to rect mode."""
+        if (event.button not in [MouseButton.LEFT, MouseButton.RIGHT]
+                or event.x is None or event.y is None):
+            return
+
+        axes = self._start_event_axes_interaction(event, method="zoom")
+        if not axes:
+            return
+
+        id_zoom = self.canvas.mpl_connect(
+            "motion_notify_event", self.drag_zoom)
+
+        # A colorbar is one-dimensional, so we extend the zoom rectangle out
+        # to the edge of the Axes bbox in the other dimension. To do that we
+        # store the orientation of the colorbar for later.
+        parent_ax = axes[0]
+        if hasattr(parent_ax, "_colorbar"):
+            cbar = parent_ax._colorbar.orientation
+        else:
+            cbar = None
+
+        self._zoom_info = self._ZoomInfo(
+            direction="in" if event.button == 1 else "out",
+            start_xy=(event.x, event.y), axes=axes, cid=id_zoom, cbar=cbar)
+
+    def drag_zoom(self, event):
+        """Callback for dragging in zoom mode."""
+        start_xy = self._zoom_info.start_xy
+        ax = self._zoom_info.axes[0]
+        (x1, y1), (x2, y2) = np.clip(
+            [start_xy, [event.x, event.y]], ax.bbox.min, ax.bbox.max)
+        key = event.key
+        # Force the key on colorbars to extend the short-axis bbox
+        if self._zoom_info.cbar == "horizontal":
+            key = "x"
+        elif self._zoom_info.cbar == "vertical":
+            key = "y"
+        if key == "x":
+            y1, y2 = ax.bbox.intervaly
+        elif key == "y":
+            x1, x2 = ax.bbox.intervalx
+
+        self.draw_rubberband(event, x1, y1, x2, y2)
+
+    def release_zoom(self, event):
+        """Callback for mouse button release in zoom to rect mode."""
+        if self._zoom_info is None:
+            return
+
+        # We don't check the event button here, so that zooms can be cancelled
+        # by (pressing and) releasing another mouse button.
+        self.canvas.mpl_disconnect(self._zoom_info.cid)
+        self.remove_rubberband()
+
+        start_x, start_y = self._zoom_info.start_xy
+        key = event.key
+        # Force the key on colorbars to ignore the zoom-cancel on the
+        # short-axis side
+        if self._zoom_info.cbar == "horizontal":
+            key = "x"
+        elif self._zoom_info.cbar == "vertical":
+            key = "y"
+        # Ignore single clicks: 5 pixels is a threshold that allows the user to
+        # "cancel" a zoom action by zooming by less than 5 pixels.
+        if ((abs(event.x - start_x) < 5 and key != "y") or
+                (abs(event.y - start_y) < 5 and key != "x")):
+            self.canvas.draw_idle()
+            self._zoom_info = None
+            return
+
+        for i, ax in enumerate(self._zoom_info.axes):
+            # Detect whether this Axes is twinned with an earlier Axes in the
+            # list of zoomed Axes, to avoid double zooming.
+            twinx = any(ax.get_shared_x_axes().joined(ax, prev)
+                        for prev in self._zoom_info.axes[:i])
+            twiny = any(ax.get_shared_y_axes().joined(ax, prev)
+                        for prev in self._zoom_info.axes[:i])
+            ax._set_view_from_bbox(
+                (start_x, start_y, event.x, event.y),
+                self._zoom_info.direction, key, twinx, twiny)
+
+        self.canvas.draw_idle()
+        self._zoom_info = None
+        self.push_current()
+
+    def push_current(self):
+        """Push the current view limits and position onto the stack."""
+        self._nav_stack.push(
+            WeakKeyDictionary(
+                {ax: (ax._get_view(),
+                      # Store both the original and modified positions.
+                      (ax.get_position(True).frozen(),
+                       ax.get_position().frozen()))
+                 for ax in self.canvas.figure.axes}))
+        self.set_history_buttons()
+
+    def _update_view(self):
+        """
+        Update the viewlim and position from the view and position stack for
+        each Axes.
+        """
+        nav_info = self._nav_stack()
+        if nav_info is None:
+            return
+        # Retrieve all items at once to avoid any risk of GC deleting an Axes
+        # while in the middle of the loop below.
+        items = list(nav_info.items())
+        for ax, (view, (pos_orig, pos_active)) in items:
+            ax._set_view(view)
+            # Restore both the original and modified positions
+            ax._set_position(pos_orig, 'original')
+            ax._set_position(pos_active, 'active')
+        self.canvas.draw_idle()
+
+    def configure_subplots(self, *args):
+        if hasattr(self, "subplot_tool"):
+            self.subplot_tool.figure.canvas.manager.show()
+            return
+        # This import needs to happen here due to circular imports.
+        from matplotlib.figure import Figure
+        with mpl.rc_context({"toolbar": "none"}):  # No navbar for the toolfig.
+            manager = type(self.canvas).new_manager(Figure(figsize=(6, 3)), -1)
+        manager.set_window_title("Subplot configuration tool")
+        tool_fig = manager.canvas.figure
+        tool_fig.subplots_adjust(top=0.9)
+        self.subplot_tool = widgets.SubplotTool(self.canvas.figure, tool_fig)
+        cid = self.canvas.mpl_connect(
+            "close_event", lambda e: manager.destroy())
+
+        def on_tool_fig_close(e):
+            self.canvas.mpl_disconnect(cid)
+            del self.subplot_tool
+
+        tool_fig.canvas.mpl_connect("close_event", on_tool_fig_close)
+        manager.show()
+        return self.subplot_tool
+
+    def save_figure(self, *args):
+        """
+        Save the current figure.
+
+        Backend implementations may choose to return
+        the absolute path of the saved file, if any, as
+        a string.
+
+        If no file is created then `None` is returned.
+
+        If the backend does not implement this functionality
+        then `NavigationToolbar2.UNKNOWN_SAVED_STATUS` is returned.
+
+        Returns
+        -------
+        str or `NavigationToolbar2.UNKNOWN_SAVED_STATUS` or `None`
+            The filepath of the saved figure.
+            Returns `None` if figure is not saved.
+            Returns `NavigationToolbar2.UNKNOWN_SAVED_STATUS` when
+            the backend does not provide the information.
+        """
+        raise NotImplementedError
+
+    def update(self):
+        """Reset the Axes stack."""
+        self._nav_stack.clear()
+        self.set_history_buttons()
+
+    def set_history_buttons(self):
+        """Enable or disable the back/forward button."""
+
+
+class ToolContainerBase:
+    """
+    Base class for all tool containers, e.g. toolbars.
+
+    Attributes
+    ----------
+    toolmanager : `.ToolManager`
+        The tools with which this `ToolContainer` wants to communicate.
+    """
+
+    _icon_extension = '.png'
+    """
+    Toolcontainer button icon image format extension
+
+    **String**: Image extension
+    """
+
+    def __init__(self, toolmanager):
+        self.toolmanager = toolmanager
+        toolmanager.toolmanager_connect(
+            'tool_message_event',
+            lambda event: self.set_message(event.message))
+        toolmanager.toolmanager_connect(
+            'tool_removed_event',
+            lambda event: self.remove_toolitem(event.tool.name))
+
+    def _tool_toggled_cbk(self, event):
+        """
+        Capture the 'tool_trigger_[name]'
+
+        This only gets used for toggled tools.
+        """
+        self.toggle_toolitem(event.tool.name, event.tool.toggled)
+
+    def add_tool(self, tool, group, position=-1):
+        """
+        Add a tool to this container.
+
+        Parameters
+        ----------
+        tool : tool_like
+            The tool to add, see `.ToolManager.get_tool`.
+        group : str
+            The name of the group to add this tool to.
+        position : int, default: -1
+            The position within the group to place this tool.
+        """
+        tool = self.toolmanager.get_tool(tool)
+        image = self._get_image_filename(tool)
+        toggle = getattr(tool, 'toggled', None) is not None
+        self.add_toolitem(tool.name, group, position,
+                          image, tool.description, toggle)
+        if toggle:
+            self.toolmanager.toolmanager_connect('tool_trigger_%s' % tool.name,
+                                                 self._tool_toggled_cbk)
+            # If initially toggled
+            if tool.toggled:
+                self.toggle_toolitem(tool.name, True)
+
+    def _get_image_filename(self, tool):
+        """Resolve a tool icon's filename."""
+        if not tool.image:
+            return None
+        if os.path.isabs(tool.image):
+            filename = tool.image
+        else:
+            if "image" in getattr(tool, "__dict__", {}):
+                raise ValueError("If 'tool.image' is an instance variable, "
+                                 "it must be an absolute path")
+            for cls in type(tool).__mro__:
+                if "image" in vars(cls):
+                    try:
+                        src = inspect.getfile(cls)
+                        break
+                    except (OSError, TypeError):
+                        raise ValueError("Failed to locate source file "
+                                         "where 'tool.image' is defined") from None
+            else:
+                raise ValueError("Failed to find parent class defining 'tool.image'")
+            filename = str(pathlib.Path(src).parent / tool.image)
+        for filename in [filename, filename + self._icon_extension]:
+            if os.path.isfile(filename):
+                return os.path.abspath(filename)
+        for fname in [  # Fallback; once deprecation elapses.
+            tool.image,
+            tool.image + self._icon_extension,
+            cbook._get_data_path("images", tool.image),
+            cbook._get_data_path("images", tool.image + self._icon_extension),
+        ]:
+            if os.path.isfile(fname):
+                _api.warn_deprecated(
+                    "3.9", message=f"Loading icon {tool.image!r} from the current "
+                    "directory or from Matplotlib's image directory.  This behavior "
+                    "is deprecated since %(since)s and will be removed in %(removal)s; "
+                    "Tool.image should be set to a path relative to the Tool's source "
+                    "file, or to an absolute path.")
+                return os.path.abspath(fname)
+
+    def trigger_tool(self, name):
+        """
+        Trigger the tool.
+
+        Parameters
+        ----------
+        name : str
+            Name (id) of the tool triggered from within the container.
+        """
+        self.toolmanager.trigger_tool(name, sender=self)
+
+    def add_toolitem(self, name, group, position, image, description, toggle):
+        """
+        A hook to add a toolitem to the container.
+
+        This hook must be implemented in each backend and contains the
+        backend-specific code to add an element to the toolbar.
+
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolContainerBase.add_tool`.
+
+        The callback associated with the button click event
+        must be *exactly* ``self.trigger_tool(name)``.
+
+        Parameters
+        ----------
+        name : str
+            Name of the tool to add, this gets used as the tool's ID and as the
+            default label of the buttons.
+        group : str
+            Name of the group that this tool belongs to.
+        position : int
+            Position of the tool within its group, if -1 it goes at the end.
+        image : str
+            Filename of the image for the button or `None`.
+        description : str
+            Description of the tool, used for the tooltips.
+        toggle : bool
+            * `True` : The button is a toggle (change the pressed/unpressed
+              state between consecutive clicks).
+            * `False` : The button is a normal button (returns to unpressed
+              state after release).
+        """
+        raise NotImplementedError
+
+    def toggle_toolitem(self, name, toggled):
+        """
+        A hook to toggle a toolitem without firing an event.
+
+        This hook must be implemented in each backend and contains the
+        backend-specific code to silently toggle a toolbar element.
+
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.trigger_tool` or `.ToolContainerBase.trigger_tool`
+            (which are equivalent).
+
+        Parameters
+        ----------
+        name : str
+            Id of the tool to toggle.
+        toggled : bool
+            Whether to set this tool as toggled or not.
+        """
+        raise NotImplementedError
+
+    def remove_toolitem(self, name):
+        """
+        A hook to remove a toolitem from the container.
+
+        This hook must be implemented in each backend and contains the
+        backend-specific code to remove an element from the toolbar; it is
+        called when `.ToolManager` emits a ``tool_removed_event``.
+
+        Because some tools are present only on the `.ToolManager` but not on
+        the `ToolContainer`, this method must be a no-op when called on a tool
+        absent from the container.
+
+        .. warning::
+            This is part of the backend implementation and should
+            not be called by end-users.  They should instead call
+            `.ToolManager.remove_tool`.
+
+        Parameters
+        ----------
+        name : str
+            Name of the tool to remove.
+        """
+        raise NotImplementedError
+
+    def set_message(self, s):
+        """
+        Display a message on the toolbar.
+
+        Parameters
+        ----------
+        s : str
+            Message text.
+        """
+        raise NotImplementedError
+
+
+class _Backend:
+    # A backend can be defined by using the following pattern:
+    #
+    # @_Backend.export
+    # class FooBackend(_Backend):
+    #     # override the attributes and methods documented below.
+
+    # `backend_version` may be overridden by the subclass.
+    backend_version = "unknown"
+
+    # The `FigureCanvas` class must be defined.
+    FigureCanvas = None
+
+    # For interactive backends, the `FigureManager` class must be overridden.
+    FigureManager = FigureManagerBase
+
+    # For interactive backends, `mainloop` should be a function taking no
+    # argument and starting the backend main loop.  It should be left as None
+    # for non-interactive backends.
+    mainloop = None
+
+    # The following methods will be automatically defined and exported, but
+    # can be overridden.
+
+    @classmethod
+    def new_figure_manager(cls, num, *args, **kwargs):
+        """Create a new figure manager instance."""
+        # This import needs to happen here due to circular imports.
+        from matplotlib.figure import Figure
+        fig_cls = kwargs.pop('FigureClass', Figure)
+        fig = fig_cls(*args, **kwargs)
+        return cls.new_figure_manager_given_figure(num, fig)
+
+    @classmethod
+    def new_figure_manager_given_figure(cls, num, figure):
+        """Create a new figure manager instance for the given figure."""
+        return cls.FigureCanvas.new_manager(figure, num)
+
+    @classmethod
+    def draw_if_interactive(cls):
+        manager_class = cls.FigureCanvas.manager_class
+        # Interactive backends reimplement start_main_loop or pyplot_show.
+        backend_is_interactive = (
+            manager_class.start_main_loop != FigureManagerBase.start_main_loop
+            or manager_class.pyplot_show != FigureManagerBase.pyplot_show)
+        if backend_is_interactive and is_interactive():
+            manager = Gcf.get_active()
+            if manager:
+                manager.canvas.draw_idle()
+
+    @classmethod
+    def show(cls, *, block=None):
+        """
+        Show all figures.
+
+        `show` blocks by calling `mainloop` if *block* is ``True``, or if it is
+        ``None`` and we are not in `interactive` mode and if IPython's
+        ``%matplotlib`` integration has not been activated.
+        """
+        managers = Gcf.get_all_fig_managers()
+        if not managers:
+            return
+        for manager in managers:
+            try:
+                manager.show()  # Emits a warning for non-interactive backend.
+            except NonGuiException as exc:
+                _api.warn_external(str(exc))
+        if cls.mainloop is None:
+            return
+        if block is None:
+            # Hack: Is IPython's %matplotlib integration activated?  If so,
+            # IPython's activate_matplotlib (>= 0.10) tacks a _needmain
+            # attribute onto pyplot.show (always set to False).
+            pyplot_show = getattr(sys.modules.get("matplotlib.pyplot"), "show", None)
+            ipython_pylab = hasattr(pyplot_show, "_needmain")
+            block = not ipython_pylab and not is_interactive()
+        if block:
+            cls.mainloop()
+
+    # This method is the one actually exporting the required methods.
+
+    @staticmethod
+    def export(cls):
+        for name in [
+                "backend_version",
+                "FigureCanvas",
+                "FigureManager",
+                "new_figure_manager",
+                "new_figure_manager_given_figure",
+                "draw_if_interactive",
+                "show",
+        ]:
+            setattr(sys.modules[cls.__module__], name, getattr(cls, name))
+
+        # For back-compatibility, generate a shim `Show` class.
+
+        class Show(ShowBase):
+            def mainloop(self):
+                return cls.mainloop()
+
+        setattr(sys.modules[cls.__module__], "Show", Show)
+        return cls
+
+
+class ShowBase(_Backend):
+    """
+    Simple base class to generate a ``show()`` function in backends.
+
+    Subclass must override ``mainloop()`` method.
+    """
+
+    def __call__(self, block=None):
+        return self.show(block=block)
diff --git a/lib/python3.12/site-packages/matplotlib/backend_managers.py b/lib/python3.12/site-packages/matplotlib/backend_managers.py
new file mode 100644
index 0000000000000000000000000000000000000000..76f15030bcc5e2c112b9aa72ca9cbf18334599e2
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/backend_managers.py
@@ -0,0 +1,387 @@
+from matplotlib import _api, backend_tools, cbook, widgets
+
+
+class ToolEvent:
+    """Event for tool manipulation (add/remove)."""
+    def __init__(self, name, sender, tool, data=None):
+        self.name = name
+        self.sender = sender
+        self.tool = tool
+        self.data = data
+
+
+class ToolTriggerEvent(ToolEvent):
+    """Event to inform that a tool has been triggered."""
+    def __init__(self, name, sender, tool, canvasevent=None, data=None):
+        super().__init__(name, sender, tool, data)
+        self.canvasevent = canvasevent
+
+
+class ToolManagerMessageEvent:
+    """
+    Event carrying messages from toolmanager.
+
+    Messages usually get displayed to the user by the toolbar.
+    """
+    def __init__(self, name, sender, message):
+        self.name = name
+        self.sender = sender
+        self.message = message
+
+
+class ToolManager:
+    """
+    Manager for actions triggered by user interactions (key press, toolbar
+    clicks, ...) on a Figure.
+
+    Attributes
+    ----------
+    figure : `.Figure`
+    keypresslock : `~matplotlib.widgets.LockDraw`
+        `.LockDraw` object to know if the `canvas` key_press_event is locked.
+    messagelock : `~matplotlib.widgets.LockDraw`
+        `.LockDraw` object to know if the message is available to write.
+    """
+
+    def __init__(self, figure=None):
+
+        self._key_press_handler_id = None
+
+        self._tools = {}
+        self._keys = {}
+        self._toggled = {}
+        self._callbacks = cbook.CallbackRegistry()
+
+        # to process keypress event
+        self.keypresslock = widgets.LockDraw()
+        self.messagelock = widgets.LockDraw()
+
+        self._figure = None
+        self.set_figure(figure)
+
+    @property
+    def canvas(self):
+        """Canvas managed by FigureManager."""
+        if not self._figure:
+            return None
+        return self._figure.canvas
+
+    @property
+    def figure(self):
+        """Figure that holds the canvas."""
+        return self._figure
+
+    @figure.setter
+    def figure(self, figure):
+        self.set_figure(figure)
+
+    def set_figure(self, figure, update_tools=True):
+        """
+        Bind the given figure to the tools.
+
+        Parameters
+        ----------
+        figure : `.Figure`
+        update_tools : bool, default: True
+            Force tools to update figure.
+        """
+        if self._key_press_handler_id:
+            self.canvas.mpl_disconnect(self._key_press_handler_id)
+        self._figure = figure
+        if figure:
+            self._key_press_handler_id = self.canvas.mpl_connect(
+                'key_press_event', self._key_press)
+        if update_tools:
+            for tool in self._tools.values():
+                tool.figure = figure
+
+    def toolmanager_connect(self, s, func):
+        """
+        Connect event with string *s* to *func*.
+
+        Parameters
+        ----------
+        s : str
+            The name of the event. The following events are recognized:
+
+            - 'tool_message_event'
+            - 'tool_removed_event'
+            - 'tool_added_event'
+
+            For every tool added a new event is created
+
+            - 'tool_trigger_TOOLNAME', where TOOLNAME is the id of the tool.
+
+        func : callable
+            Callback function for the toolmanager event with signature::
+
+                def func(event: ToolEvent) -> Any
+
+        Returns
+        -------
+        cid
+            The callback id for the connection. This can be used in
+            `.toolmanager_disconnect`.
+        """
+        return self._callbacks.connect(s, func)
+
+    def toolmanager_disconnect(self, cid):
+        """
+        Disconnect callback id *cid*.
+
+        Example usage::
+
+            cid = toolmanager.toolmanager_connect('tool_trigger_zoom', onpress)
+            #...later
+            toolmanager.toolmanager_disconnect(cid)
+        """
+        return self._callbacks.disconnect(cid)
+
+    def message_event(self, message, sender=None):
+        """Emit a `ToolManagerMessageEvent`."""
+        if sender is None:
+            sender = self
+
+        s = 'tool_message_event'
+        event = ToolManagerMessageEvent(s, sender, message)
+        self._callbacks.process(s, event)
+
+    @property
+    def active_toggle(self):
+        """Currently toggled tools."""
+        return self._toggled
+
+    def get_tool_keymap(self, name):
+        """
+        Return the keymap associated with the specified tool.
+
+        Parameters
+        ----------
+        name : str
+            Name of the Tool.
+
+        Returns
+        -------
+        list of str
+            List of keys associated with the tool.
+        """
+
+        keys = [k for k, i in self._keys.items() if i == name]
+        return keys
+
+    def _remove_keys(self, name):
+        for k in self.get_tool_keymap(name):
+            del self._keys[k]
+
+    def update_keymap(self, name, key):
+        """
+        Set the keymap to associate with the specified tool.
+
+        Parameters
+        ----------
+        name : str
+            Name of the Tool.
+        key : str or list of str
+            Keys to associate with the tool.
+        """
+        if name not in self._tools:
+            raise KeyError(f'{name!r} not in Tools')
+        self._remove_keys(name)
+        if isinstance(key, str):
+            key = [key]
+        for k in key:
+            if k in self._keys:
+                _api.warn_external(
+                    f'Key {k} changed from {self._keys[k]} to {name}')
+            self._keys[k] = name
+
+    def remove_tool(self, name):
+        """
+        Remove tool named *name*.
+
+        Parameters
+        ----------
+        name : str
+            Name of the tool.
+        """
+        tool = self.get_tool(name)
+        if getattr(tool, 'toggled', False):  # If it's a toggled toggle tool, untoggle
+            self.trigger_tool(tool, 'toolmanager')
+        self._remove_keys(name)
+        event = ToolEvent('tool_removed_event', self, tool)
+        self._callbacks.process(event.name, event)
+        del self._tools[name]
+
+    def add_tool(self, name, tool, *args, **kwargs):
+        """
+        Add *tool* to `ToolManager`.
+
+        If successful, adds a new event ``tool_trigger_{name}`` where
+        ``{name}`` is the *name* of the tool; the event is fired every time the
+        tool is triggered.
+
+        Parameters
+        ----------
+        name : str
+            Name of the tool, treated as the ID, has to be unique.
+        tool : type
+            Class of the tool to be added.  A subclass will be used
+            instead if one was registered for the current canvas class.
+        *args, **kwargs
+            Passed to the *tool*'s constructor.
+
+        See Also
+        --------
+        matplotlib.backend_tools.ToolBase : The base class for tools.
+        """
+
+        tool_cls = backend_tools._find_tool_class(type(self.canvas), tool)
+        if not tool_cls:
+            raise ValueError('Impossible to find class for %s' % str(tool))
+
+        if name in self._tools:
+            _api.warn_external('A "Tool class" with the same name already '
+                               'exists, not added')
+            return self._tools[name]
+
+        tool_obj = tool_cls(self, name, *args, **kwargs)
+        self._tools[name] = tool_obj
+
+        if tool_obj.default_keymap is not None:
+            self.update_keymap(name, tool_obj.default_keymap)
+
+        # For toggle tools init the radio_group in self._toggled
+        if isinstance(tool_obj, backend_tools.ToolToggleBase):
+            # None group is not mutually exclusive, a set is used to keep track
+            # of all toggled tools in this group
+            if tool_obj.radio_group is None:
+                self._toggled.setdefault(None, set())
+            else:
+                self._toggled.setdefault(tool_obj.radio_group, None)
+
+            # If initially toggled
+            if tool_obj.toggled:
+                self._handle_toggle(tool_obj, None, None)
+        tool_obj.set_figure(self.figure)
+
+        event = ToolEvent('tool_added_event', self, tool_obj)
+        self._callbacks.process(event.name, event)
+
+        return tool_obj
+
+    def _handle_toggle(self, tool, canvasevent, data):
+        """
+        Toggle tools, need to untoggle prior to using other Toggle tool.
+        Called from trigger_tool.
+
+        Parameters
+        ----------
+        tool : `.ToolBase`
+        canvasevent : Event
+            Original Canvas event or None.
+        data : object
+            Extra data to pass to the tool when triggering.
+        """
+
+        radio_group = tool.radio_group
+        # radio_group None is not mutually exclusive
+        # just keep track of toggled tools in this group
+        if radio_group is None:
+            if tool.name in self._toggled[None]:
+                self._toggled[None].remove(tool.name)
+            else:
+                self._toggled[None].add(tool.name)
+            return
+
+        # If the tool already has a toggled state, untoggle it
+        if self._toggled[radio_group] == tool.name:
+            toggled = None
+        # If no tool was toggled in the radio_group
+        # toggle it
+        elif self._toggled[radio_group] is None:
+            toggled = tool.name
+        # Other tool in the radio_group is toggled
+        else:
+            # Untoggle previously toggled tool
+            self.trigger_tool(self._toggled[radio_group],
+                              self,
+                              canvasevent,
+                              data)
+            toggled = tool.name
+
+        # Keep track of the toggled tool in the radio_group
+        self._toggled[radio_group] = toggled
+
+    def trigger_tool(self, name, sender=None, canvasevent=None, data=None):
+        """
+        Trigger a tool and emit the ``tool_trigger_{name}`` event.
+
+        Parameters
+        ----------
+        name : str
+            Name of the tool.
+        sender : object
+            Object that wishes to trigger the tool.
+        canvasevent : Event
+            Original Canvas event or None.
+        data : object
+            Extra data to pass to the tool when triggering.
+        """
+        tool = self.get_tool(name)
+        if tool is None:
+            return
+
+        if sender is None:
+            sender = self
+
+        if isinstance(tool, backend_tools.ToolToggleBase):
+            self._handle_toggle(tool, canvasevent, data)
+
+        tool.trigger(sender, canvasevent, data)  # Actually trigger Tool.
+
+        s = 'tool_trigger_%s' % name
+        event = ToolTriggerEvent(s, sender, tool, canvasevent, data)
+        self._callbacks.process(s, event)
+
+    def _key_press(self, event):
+        if event.key is None or self.keypresslock.locked():
+            return
+
+        name = self._keys.get(event.key, None)
+        if name is None:
+            return
+        self.trigger_tool(name, canvasevent=event)
+
+    @property
+    def tools(self):
+        """A dict mapping tool name -> controlled tool."""
+        return self._tools
+
+    def get_tool(self, name, warn=True):
+        """
+        Return the tool object with the given name.
+
+        For convenience, this passes tool objects through.
+
+        Parameters
+        ----------
+        name : str or `.ToolBase`
+            Name of the tool, or the tool itself.
+        warn : bool, default: True
+            Whether a warning should be emitted it no tool with the given name
+            exists.
+
+        Returns
+        -------
+        `.ToolBase` or None
+            The tool or None if no tool with the given name exists.
+        """
+        if (isinstance(name, backend_tools.ToolBase)
+                and name.name in self._tools):
+            return name
+        if name not in self._tools:
+            if warn:
+                _api.warn_external(
+                    f"ToolManager does not control tool {name!r}")
+            return None
+        return self._tools[name]
diff --git a/lib/python3.12/site-packages/matplotlib/backend_tools.py b/lib/python3.12/site-packages/matplotlib/backend_tools.py
new file mode 100644
index 0000000000000000000000000000000000000000..87ed794022a0eee732da01ac9627b84020c83013
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/backend_tools.py
@@ -0,0 +1,998 @@
+"""
+Abstract base classes define the primitives for Tools.
+These tools are used by `matplotlib.backend_managers.ToolManager`
+
+:class:`ToolBase`
+    Simple stateless tool
+
+:class:`ToolToggleBase`
+    Tool that has two states, only one Toggle tool can be
+    active at any given time for the same
+    `matplotlib.backend_managers.ToolManager`
+"""
+
+import enum
+import functools
+import re
+import time
+from types import SimpleNamespace
+import uuid
+from weakref import WeakKeyDictionary
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib._pylab_helpers import Gcf
+from matplotlib import _api, cbook
+
+
+class Cursors(enum.IntEnum):  # Must subclass int for the macOS backend.
+    """Backend-independent cursor types."""
+    POINTER = enum.auto()
+    HAND = enum.auto()
+    SELECT_REGION = enum.auto()
+    MOVE = enum.auto()
+    WAIT = enum.auto()
+    RESIZE_HORIZONTAL = enum.auto()
+    RESIZE_VERTICAL = enum.auto()
+cursors = Cursors  # Backcompat.
+
+
+# _tool_registry, _register_tool_class, and _find_tool_class implement a
+# mechanism through which ToolManager.add_tool can determine whether a subclass
+# of the requested tool class has been registered (either for the current
+# canvas class or for a parent class), in which case that tool subclass will be
+# instantiated instead.  This is the mechanism used e.g. to allow different
+# GUI backends to implement different specializations for ConfigureSubplots.
+
+
+_tool_registry = set()
+
+
+def _register_tool_class(canvas_cls, tool_cls=None):
+    """Decorator registering *tool_cls* as a tool class for *canvas_cls*."""
+    if tool_cls is None:
+        return functools.partial(_register_tool_class, canvas_cls)
+    _tool_registry.add((canvas_cls, tool_cls))
+    return tool_cls
+
+
+def _find_tool_class(canvas_cls, tool_cls):
+    """Find a subclass of *tool_cls* registered for *canvas_cls*."""
+    for canvas_parent in canvas_cls.__mro__:
+        for tool_child in _api.recursive_subclasses(tool_cls):
+            if (canvas_parent, tool_child) in _tool_registry:
+                return tool_child
+    return tool_cls
+
+
+# Views positions tool
+_views_positions = 'viewpos'
+
+
+class ToolBase:
+    """
+    Base tool class.
+
+    A base tool, only implements `trigger` method or no method at all.
+    The tool is instantiated by `matplotlib.backend_managers.ToolManager`.
+    """
+
+    default_keymap = None
+    """
+    Keymap to associate with this tool.
+
+    ``list[str]``: List of keys that will trigger this tool when a keypress
+    event is emitted on ``self.figure.canvas``.  Note that this attribute is
+    looked up on the instance, and can therefore be a property (this is used
+    e.g. by the built-in tools to load the rcParams at instantiation time).
+    """
+
+    description = None
+    """
+    Description of the Tool.
+
+    `str`: Tooltip used if the Tool is included in a Toolbar.
+    """
+
+    image = None
+    """
+    Icon filename.
+
+    ``str | None``: Filename of the Toolbar icon; either absolute, or relative to the
+    directory containing the Python source file where the ``Tool.image`` class attribute
+    is defined (in the latter case, this cannot be defined as an instance attribute).
+    In either case, the extension is optional; leaving it off lets individual backends
+    select the icon format they prefer.  If None, the *name* is used as a label in the
+    toolbar button.
+    """
+
+    def __init__(self, toolmanager, name):
+        self._name = name
+        self._toolmanager = toolmanager
+        self._figure = None
+
+    name = property(
+        lambda self: self._name,
+        doc="The tool id (str, must be unique among tools of a tool manager).")
+    toolmanager = property(
+        lambda self: self._toolmanager,
+        doc="The `.ToolManager` that controls this tool.")
+    canvas = property(
+        lambda self: self._figure.canvas if self._figure is not None else None,
+        doc="The canvas of the figure affected by this tool, or None.")
+
+    def set_figure(self, figure):
+        self._figure = figure
+
+    figure = property(
+        lambda self: self._figure,
+        # The setter must explicitly call self.set_figure so that subclasses can
+        # meaningfully override it.
+        lambda self, figure: self.set_figure(figure),
+        doc="The Figure affected by this tool, or None.")
+
+    def _make_classic_style_pseudo_toolbar(self):
+        """
+        Return a placeholder object with a single `canvas` attribute.
+
+        This is useful to reuse the implementations of tools already provided
+        by the classic Toolbars.
+        """
+        return SimpleNamespace(canvas=self.canvas)
+
+    def trigger(self, sender, event, data=None):
+        """
+        Called when this tool gets used.
+
+        This method is called by `.ToolManager.trigger_tool`.
+
+        Parameters
+        ----------
+        event : `.Event`
+            The canvas event that caused this tool to be called.
+        sender : object
+            Object that requested the tool to be triggered.
+        data : object
+            Extra data.
+        """
+        pass
+
+
+class ToolToggleBase(ToolBase):
+    """
+    Toggleable tool.
+
+    Every time it is triggered, it switches between enable and disable.
+
+    Parameters
+    ----------
+    ``*args``
+        Variable length argument to be used by the Tool.
+    ``**kwargs``
+        `toggled` if present and True, sets the initial state of the Tool
+        Arbitrary keyword arguments to be consumed by the Tool
+    """
+
+    radio_group = None
+    """
+    Attribute to group 'radio' like tools (mutually exclusive).
+
+    `str` that identifies the group or **None** if not belonging to a group.
+    """
+
+    cursor = None
+    """Cursor to use when the tool is active."""
+
+    default_toggled = False
+    """Default of toggled state."""
+
+    def __init__(self, *args, **kwargs):
+        self._toggled = kwargs.pop('toggled', self.default_toggled)
+        super().__init__(*args, **kwargs)
+
+    def trigger(self, sender, event, data=None):
+        """Calls `enable` or `disable` based on `toggled` value."""
+        if self._toggled:
+            self.disable(event)
+        else:
+            self.enable(event)
+        self._toggled = not self._toggled
+
+    def enable(self, event=None):
+        """
+        Enable the toggle tool.
+
+        `trigger` calls this method when `toggled` is False.
+        """
+        pass
+
+    def disable(self, event=None):
+        """
+        Disable the toggle tool.
+
+        `trigger` call this method when `toggled` is True.
+
+        This can happen in different circumstances.
+
+        * Click on the toolbar tool button.
+        * Call to `matplotlib.backend_managers.ToolManager.trigger_tool`.
+        * Another `ToolToggleBase` derived tool is triggered
+          (from the same `.ToolManager`).
+        """
+        pass
+
+    @property
+    def toggled(self):
+        """State of the toggled tool."""
+        return self._toggled
+
+    def set_figure(self, figure):
+        toggled = self.toggled
+        if toggled:
+            if self.figure:
+                self.trigger(self, None)
+            else:
+                # if no figure the internal state is not changed
+                # we change it here so next call to trigger will change it back
+                self._toggled = False
+        super().set_figure(figure)
+        if toggled:
+            if figure:
+                self.trigger(self, None)
+            else:
+                # if there is no figure, trigger won't change the internal
+                # state we change it back
+                self._toggled = True
+
+
+class ToolSetCursor(ToolBase):
+    """
+    Change to the current cursor while inaxes.
+
+    This tool, keeps track of all `ToolToggleBase` derived tools, and updates
+    the cursor when a tool gets triggered.
+    """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._id_drag = None
+        self._current_tool = None
+        self._default_cursor = cursors.POINTER
+        self._last_cursor = self._default_cursor
+        self.toolmanager.toolmanager_connect('tool_added_event',
+                                             self._add_tool_cbk)
+        for tool in self.toolmanager.tools.values():  # process current tools
+            self._add_tool_cbk(mpl.backend_managers.ToolEvent(
+                'tool_added_event', self.toolmanager, tool))
+
+    def set_figure(self, figure):
+        if self._id_drag:
+            self.canvas.mpl_disconnect(self._id_drag)
+        super().set_figure(figure)
+        if figure:
+            self._id_drag = self.canvas.mpl_connect(
+                'motion_notify_event', self._set_cursor_cbk)
+
+    def _add_tool_cbk(self, event):
+        """Process every newly added tool."""
+        if getattr(event.tool, 'cursor', None) is not None:
+            self.toolmanager.toolmanager_connect(
+                f'tool_trigger_{event.tool.name}', self._tool_trigger_cbk)
+
+    def _tool_trigger_cbk(self, event):
+        self._current_tool = event.tool if event.tool.toggled else None
+        self._set_cursor_cbk(event.canvasevent)
+
+    def _set_cursor_cbk(self, event):
+        if not event or not self.canvas:
+            return
+        if (self._current_tool and getattr(event, "inaxes", None)
+                and event.inaxes.get_navigate()):
+            if self._last_cursor != self._current_tool.cursor:
+                self.canvas.set_cursor(self._current_tool.cursor)
+                self._last_cursor = self._current_tool.cursor
+        elif self._last_cursor != self._default_cursor:
+            self.canvas.set_cursor(self._default_cursor)
+            self._last_cursor = self._default_cursor
+
+
+class ToolCursorPosition(ToolBase):
+    """
+    Send message with the current pointer position.
+
+    This tool runs in the background reporting the position of the cursor.
+    """
+    def __init__(self, *args, **kwargs):
+        self._id_drag = None
+        super().__init__(*args, **kwargs)
+
+    def set_figure(self, figure):
+        if self._id_drag:
+            self.canvas.mpl_disconnect(self._id_drag)
+        super().set_figure(figure)
+        if figure:
+            self._id_drag = self.canvas.mpl_connect(
+                'motion_notify_event', self.send_message)
+
+    def send_message(self, event):
+        """Call `matplotlib.backend_managers.ToolManager.message_event`."""
+        if self.toolmanager.messagelock.locked():
+            return
+
+        from matplotlib.backend_bases import NavigationToolbar2
+        message = NavigationToolbar2._mouse_event_to_message(event)
+        self.toolmanager.message_event(message, self)
+
+
+class RubberbandBase(ToolBase):
+    """Draw and remove a rubberband."""
+    def trigger(self, sender, event, data=None):
+        """Call `draw_rubberband` or `remove_rubberband` based on data."""
+        if not self.figure.canvas.widgetlock.available(sender):
+            return
+        if data is not None:
+            self.draw_rubberband(*data)
+        else:
+            self.remove_rubberband()
+
+    def draw_rubberband(self, *data):
+        """
+        Draw rubberband.
+
+        This method must get implemented per backend.
+        """
+        raise NotImplementedError
+
+    def remove_rubberband(self):
+        """
+        Remove rubberband.
+
+        This method should get implemented per backend.
+        """
+        pass
+
+
+class ToolQuit(ToolBase):
+    """Tool to call the figure manager destroy method."""
+
+    description = 'Quit the figure'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.quit'])
+
+    def trigger(self, sender, event, data=None):
+        Gcf.destroy_fig(self.figure)
+
+
+class ToolQuitAll(ToolBase):
+    """Tool to call the figure manager destroy method."""
+
+    description = 'Quit all figures'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.quit_all'])
+
+    def trigger(self, sender, event, data=None):
+        Gcf.destroy_all()
+
+
+class ToolGrid(ToolBase):
+    """Tool to toggle the major grids of the figure."""
+
+    description = 'Toggle major grids'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.grid'])
+
+    def trigger(self, sender, event, data=None):
+        sentinel = str(uuid.uuid4())
+        # Trigger grid switching by temporarily setting :rc:`keymap.grid`
+        # to a unique key and sending an appropriate event.
+        with (cbook._setattr_cm(event, key=sentinel),
+              mpl.rc_context({'keymap.grid': sentinel})):
+            mpl.backend_bases.key_press_handler(event, self.figure.canvas)
+
+
+class ToolMinorGrid(ToolBase):
+    """Tool to toggle the major and minor grids of the figure."""
+
+    description = 'Toggle major and minor grids'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.grid_minor'])
+
+    def trigger(self, sender, event, data=None):
+        sentinel = str(uuid.uuid4())
+        # Trigger grid switching by temporarily setting :rc:`keymap.grid_minor`
+        # to a unique key and sending an appropriate event.
+        with (cbook._setattr_cm(event, key=sentinel),
+              mpl.rc_context({'keymap.grid_minor': sentinel})):
+            mpl.backend_bases.key_press_handler(event, self.figure.canvas)
+
+
+class ToolFullScreen(ToolBase):
+    """Tool to toggle full screen."""
+
+    description = 'Toggle fullscreen mode'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.fullscreen'])
+
+    def trigger(self, sender, event, data=None):
+        self.figure.canvas.manager.full_screen_toggle()
+
+
+class AxisScaleBase(ToolToggleBase):
+    """Base Tool to toggle between linear and logarithmic."""
+
+    def trigger(self, sender, event, data=None):
+        if event.inaxes is None:
+            return
+        super().trigger(sender, event, data)
+
+    def enable(self, event=None):
+        self.set_scale(event.inaxes, 'log')
+        self.figure.canvas.draw_idle()
+
+    def disable(self, event=None):
+        self.set_scale(event.inaxes, 'linear')
+        self.figure.canvas.draw_idle()
+
+
+class ToolYScale(AxisScaleBase):
+    """Tool to toggle between linear and logarithmic scales on the Y axis."""
+
+    description = 'Toggle scale Y axis'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.yscale'])
+
+    def set_scale(self, ax, scale):
+        ax.set_yscale(scale)
+
+
+class ToolXScale(AxisScaleBase):
+    """Tool to toggle between linear and logarithmic scales on the X axis."""
+
+    description = 'Toggle scale X axis'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.xscale'])
+
+    def set_scale(self, ax, scale):
+        ax.set_xscale(scale)
+
+
+class ToolViewsPositions(ToolBase):
+    """
+    Auxiliary Tool to handle changes in views and positions.
+
+    Runs in the background and should get used by all the tools that
+    need to access the figure's history of views and positions, e.g.
+
+    * `ToolZoom`
+    * `ToolPan`
+    * `ToolHome`
+    * `ToolBack`
+    * `ToolForward`
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.views = WeakKeyDictionary()
+        self.positions = WeakKeyDictionary()
+        self.home_views = WeakKeyDictionary()
+        super().__init__(*args, **kwargs)
+
+    def add_figure(self, figure):
+        """Add the current figure to the stack of views and positions."""
+
+        if figure not in self.views:
+            self.views[figure] = cbook._Stack()
+            self.positions[figure] = cbook._Stack()
+            self.home_views[figure] = WeakKeyDictionary()
+            # Define Home
+            self.push_current(figure)
+            # Make sure we add a home view for new Axes as they're added
+            figure.add_axobserver(lambda fig: self.update_home_views(fig))
+
+    def clear(self, figure):
+        """Reset the Axes stack."""
+        if figure in self.views:
+            self.views[figure].clear()
+            self.positions[figure].clear()
+            self.home_views[figure].clear()
+            self.update_home_views()
+
+    def update_view(self):
+        """
+        Update the view limits and position for each Axes from the current
+        stack position. If any Axes are present in the figure that aren't in
+        the current stack position, use the home view limits for those Axes and
+        don't update *any* positions.
+        """
+
+        views = self.views[self.figure]()
+        if views is None:
+            return
+        pos = self.positions[self.figure]()
+        if pos is None:
+            return
+        home_views = self.home_views[self.figure]
+        all_axes = self.figure.get_axes()
+        for a in all_axes:
+            if a in views:
+                cur_view = views[a]
+            else:
+                cur_view = home_views[a]
+            a._set_view(cur_view)
+
+        if set(all_axes).issubset(pos):
+            for a in all_axes:
+                # Restore both the original and modified positions
+                a._set_position(pos[a][0], 'original')
+                a._set_position(pos[a][1], 'active')
+
+        self.figure.canvas.draw_idle()
+
+    def push_current(self, figure=None):
+        """
+        Push the current view limits and position onto their respective stacks.
+        """
+        if not figure:
+            figure = self.figure
+        views = WeakKeyDictionary()
+        pos = WeakKeyDictionary()
+        for a in figure.get_axes():
+            views[a] = a._get_view()
+            pos[a] = self._axes_pos(a)
+        self.views[figure].push(views)
+        self.positions[figure].push(pos)
+
+    def _axes_pos(self, ax):
+        """
+        Return the original and modified positions for the specified Axes.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            The `.Axes` to get the positions for.
+
+        Returns
+        -------
+        original_position, modified_position
+            A tuple of the original and modified positions.
+        """
+
+        return (ax.get_position(True).frozen(),
+                ax.get_position().frozen())
+
+    def update_home_views(self, figure=None):
+        """
+        Make sure that ``self.home_views`` has an entry for all Axes present
+        in the figure.
+        """
+
+        if not figure:
+            figure = self.figure
+        for a in figure.get_axes():
+            if a not in self.home_views[figure]:
+                self.home_views[figure][a] = a._get_view()
+
+    def home(self):
+        """Recall the first view and position from the stack."""
+        self.views[self.figure].home()
+        self.positions[self.figure].home()
+
+    def back(self):
+        """Back one step in the stack of views and positions."""
+        self.views[self.figure].back()
+        self.positions[self.figure].back()
+
+    def forward(self):
+        """Forward one step in the stack of views and positions."""
+        self.views[self.figure].forward()
+        self.positions[self.figure].forward()
+
+
+class ViewsPositionsBase(ToolBase):
+    """Base class for `ToolHome`, `ToolBack` and `ToolForward`."""
+
+    _on_trigger = None
+
+    def trigger(self, sender, event, data=None):
+        self.toolmanager.get_tool(_views_positions).add_figure(self.figure)
+        getattr(self.toolmanager.get_tool(_views_positions),
+                self._on_trigger)()
+        self.toolmanager.get_tool(_views_positions).update_view()
+
+
+class ToolHome(ViewsPositionsBase):
+    """Restore the original view limits."""
+
+    description = 'Reset original view'
+    image = 'mpl-data/images/home'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.home'])
+    _on_trigger = 'home'
+
+
+class ToolBack(ViewsPositionsBase):
+    """Move back up the view limits stack."""
+
+    description = 'Back to previous view'
+    image = 'mpl-data/images/back'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.back'])
+    _on_trigger = 'back'
+
+
+class ToolForward(ViewsPositionsBase):
+    """Move forward in the view lim stack."""
+
+    description = 'Forward to next view'
+    image = 'mpl-data/images/forward'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.forward'])
+    _on_trigger = 'forward'
+
+
+class ConfigureSubplotsBase(ToolBase):
+    """Base tool for the configuration of subplots."""
+
+    description = 'Configure subplots'
+    image = 'mpl-data/images/subplots'
+
+
+class SaveFigureBase(ToolBase):
+    """Base tool for figure saving."""
+
+    description = 'Save the figure'
+    image = 'mpl-data/images/filesave'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.save'])
+
+
+class ZoomPanBase(ToolToggleBase):
+    """Base class for `ToolZoom` and `ToolPan`."""
+    def __init__(self, *args):
+        super().__init__(*args)
+        self._button_pressed = None
+        self._xypress = None
+        self._idPress = None
+        self._idRelease = None
+        self._idScroll = None
+        self.base_scale = 2.
+        self.scrollthresh = .5  # .5 second scroll threshold
+        self.lastscroll = time.time()-self.scrollthresh
+
+    def enable(self, event=None):
+        """Connect press/release events and lock the canvas."""
+        self.figure.canvas.widgetlock(self)
+        self._idPress = self.figure.canvas.mpl_connect(
+            'button_press_event', self._press)
+        self._idRelease = self.figure.canvas.mpl_connect(
+            'button_release_event', self._release)
+        self._idScroll = self.figure.canvas.mpl_connect(
+            'scroll_event', self.scroll_zoom)
+
+    def disable(self, event=None):
+        """Release the canvas and disconnect press/release events."""
+        self._cancel_action()
+        self.figure.canvas.widgetlock.release(self)
+        self.figure.canvas.mpl_disconnect(self._idPress)
+        self.figure.canvas.mpl_disconnect(self._idRelease)
+        self.figure.canvas.mpl_disconnect(self._idScroll)
+
+    def trigger(self, sender, event, data=None):
+        self.toolmanager.get_tool(_views_positions).add_figure(self.figure)
+        super().trigger(sender, event, data)
+        new_navigate_mode = self.name.upper() if self.toggled else None
+        for ax in self.figure.axes:
+            ax.set_navigate_mode(new_navigate_mode)
+
+    def scroll_zoom(self, event):
+        # https://gist.github.com/tacaswell/3144287
+        if event.inaxes is None:
+            return
+
+        if event.button == 'up':
+            # deal with zoom in
+            scl = self.base_scale
+        elif event.button == 'down':
+            # deal with zoom out
+            scl = 1/self.base_scale
+        else:
+            # deal with something that should never happen
+            scl = 1
+
+        ax = event.inaxes
+        ax._set_view_from_bbox([event.x, event.y, scl])
+
+        # If last scroll was done within the timing threshold, delete the
+        # previous view
+        if (time.time()-self.lastscroll) < self.scrollthresh:
+            self.toolmanager.get_tool(_views_positions).back()
+
+        self.figure.canvas.draw_idle()  # force re-draw
+
+        self.lastscroll = time.time()
+        self.toolmanager.get_tool(_views_positions).push_current()
+
+
+class ToolZoom(ZoomPanBase):
+    """A Tool for zooming using a rectangle selector."""
+
+    description = 'Zoom to rectangle'
+    image = 'mpl-data/images/zoom_to_rect'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.zoom'])
+    cursor = cursors.SELECT_REGION
+    radio_group = 'default'
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        self._ids_zoom = []
+
+    def _cancel_action(self):
+        for zoom_id in self._ids_zoom:
+            self.figure.canvas.mpl_disconnect(zoom_id)
+        self.toolmanager.trigger_tool('rubberband', self)
+        self.figure.canvas.draw_idle()
+        self._xypress = None
+        self._button_pressed = None
+        self._ids_zoom = []
+        return
+
+    def _press(self, event):
+        """Callback for mouse button presses in zoom-to-rectangle mode."""
+
+        # If we're already in the middle of a zoom, pressing another
+        # button works to "cancel"
+        if self._ids_zoom:
+            self._cancel_action()
+
+        if event.button == 1:
+            self._button_pressed = 1
+        elif event.button == 3:
+            self._button_pressed = 3
+        else:
+            self._cancel_action()
+            return
+
+        x, y = event.x, event.y
+
+        self._xypress = []
+        for i, a in enumerate(self.figure.get_axes()):
+            if (x is not None and y is not None and a.in_axes(event) and
+                    a.get_navigate() and a.can_zoom()):
+                self._xypress.append((x, y, a, i, a._get_view()))
+
+        id1 = self.figure.canvas.mpl_connect(
+            'motion_notify_event', self._mouse_move)
+        id2 = self.figure.canvas.mpl_connect(
+            'key_press_event', self._switch_on_zoom_mode)
+        id3 = self.figure.canvas.mpl_connect(
+            'key_release_event', self._switch_off_zoom_mode)
+
+        self._ids_zoom = id1, id2, id3
+        self._zoom_mode = event.key
+
+    def _switch_on_zoom_mode(self, event):
+        self._zoom_mode = event.key
+        self._mouse_move(event)
+
+    def _switch_off_zoom_mode(self, event):
+        self._zoom_mode = None
+        self._mouse_move(event)
+
+    def _mouse_move(self, event):
+        """Callback for mouse moves in zoom-to-rectangle mode."""
+
+        if self._xypress:
+            x, y = event.x, event.y
+            lastx, lasty, a, ind, view = self._xypress[0]
+            (x1, y1), (x2, y2) = np.clip(
+                [[lastx, lasty], [x, y]], a.bbox.min, a.bbox.max)
+            if self._zoom_mode == "x":
+                y1, y2 = a.bbox.intervaly
+            elif self._zoom_mode == "y":
+                x1, x2 = a.bbox.intervalx
+            self.toolmanager.trigger_tool(
+                'rubberband', self, data=(x1, y1, x2, y2))
+
+    def _release(self, event):
+        """Callback for mouse button releases in zoom-to-rectangle mode."""
+
+        for zoom_id in self._ids_zoom:
+            self.figure.canvas.mpl_disconnect(zoom_id)
+        self._ids_zoom = []
+
+        if not self._xypress:
+            self._cancel_action()
+            return
+
+        done_ax = []
+
+        for cur_xypress in self._xypress:
+            x, y = event.x, event.y
+            lastx, lasty, a, _ind, view = cur_xypress
+            # ignore singular clicks - 5 pixels is a threshold
+            if abs(x - lastx) < 5 or abs(y - lasty) < 5:
+                self._cancel_action()
+                return
+
+            # detect twinx, twiny Axes and avoid double zooming
+            twinx = any(a.get_shared_x_axes().joined(a, a1) for a1 in done_ax)
+            twiny = any(a.get_shared_y_axes().joined(a, a1) for a1 in done_ax)
+            done_ax.append(a)
+
+            if self._button_pressed == 1:
+                direction = 'in'
+            elif self._button_pressed == 3:
+                direction = 'out'
+            else:
+                continue
+
+            a._set_view_from_bbox((lastx, lasty, x, y), direction,
+                                  self._zoom_mode, twinx, twiny)
+
+        self._zoom_mode = None
+        self.toolmanager.get_tool(_views_positions).push_current()
+        self._cancel_action()
+
+
+class ToolPan(ZoomPanBase):
+    """Pan Axes with left mouse, zoom with right."""
+
+    default_keymap = property(lambda self: mpl.rcParams['keymap.pan'])
+    description = 'Pan axes with left mouse, zoom with right'
+    image = 'mpl-data/images/move'
+    cursor = cursors.MOVE
+    radio_group = 'default'
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        self._id_drag = None
+
+    def _cancel_action(self):
+        self._button_pressed = None
+        self._xypress = []
+        self.figure.canvas.mpl_disconnect(self._id_drag)
+        self.toolmanager.messagelock.release(self)
+        self.figure.canvas.draw_idle()
+
+    def _press(self, event):
+        if event.button == 1:
+            self._button_pressed = 1
+        elif event.button == 3:
+            self._button_pressed = 3
+        else:
+            self._cancel_action()
+            return
+
+        x, y = event.x, event.y
+
+        self._xypress = []
+        for i, a in enumerate(self.figure.get_axes()):
+            if (x is not None and y is not None and a.in_axes(event) and
+                    a.get_navigate() and a.can_pan()):
+                a.start_pan(x, y, event.button)
+                self._xypress.append((a, i))
+                self.toolmanager.messagelock(self)
+                self._id_drag = self.figure.canvas.mpl_connect(
+                    'motion_notify_event', self._mouse_move)
+
+    def _release(self, event):
+        if self._button_pressed is None:
+            self._cancel_action()
+            return
+
+        self.figure.canvas.mpl_disconnect(self._id_drag)
+        self.toolmanager.messagelock.release(self)
+
+        for a, _ind in self._xypress:
+            a.end_pan()
+        if not self._xypress:
+            self._cancel_action()
+            return
+
+        self.toolmanager.get_tool(_views_positions).push_current()
+        self._cancel_action()
+
+    def _mouse_move(self, event):
+        for a, _ind in self._xypress:
+            # safer to use the recorded button at the _press than current
+            # button: # multiple button can get pressed during motion...
+            a.drag_pan(self._button_pressed, event.key, event.x, event.y)
+        self.toolmanager.canvas.draw_idle()
+
+
+class ToolHelpBase(ToolBase):
+    description = 'Print tool list, shortcuts and description'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.help'])
+    image = 'mpl-data/images/help'
+
+    @staticmethod
+    def format_shortcut(key_sequence):
+        """
+        Convert a shortcut string from the notation used in rc config to the
+        standard notation for displaying shortcuts, e.g. 'ctrl+a' -> 'Ctrl+A'.
+        """
+        return (key_sequence if len(key_sequence) == 1 else
+                re.sub(r"\+[A-Z]", r"+Shift\g<0>", key_sequence).title())
+
+    def _format_tool_keymap(self, name):
+        keymaps = self.toolmanager.get_tool_keymap(name)
+        return ", ".join(self.format_shortcut(keymap) for keymap in keymaps)
+
+    def _get_help_entries(self):
+        return [(name, self._format_tool_keymap(name), tool.description)
+                for name, tool in sorted(self.toolmanager.tools.items())
+                if tool.description]
+
+    def _get_help_text(self):
+        entries = self._get_help_entries()
+        entries = ["{}: {}\n\t{}".format(*entry) for entry in entries]
+        return "\n".join(entries)
+
+    def _get_help_html(self):
+        fmt = "<tr><td>{}</td><td>{}</td><td>{}</td></tr>"
+        rows = [fmt.format(
+            "<b>Action</b>", "<b>Shortcuts</b>", "<b>Description</b>")]
+        rows += [fmt.format(*row) for row in self._get_help_entries()]
+        return ("<style>td {padding: 0px 4px}</style>"
+                "<table><thead>" + rows[0] + "</thead>"
+                "<tbody>".join(rows[1:]) + "</tbody></table>")
+
+
+class ToolCopyToClipboardBase(ToolBase):
+    """Tool to copy the figure to the clipboard."""
+
+    description = 'Copy the canvas figure to clipboard'
+    default_keymap = property(lambda self: mpl.rcParams['keymap.copy'])
+
+    def trigger(self, *args, **kwargs):
+        message = "Copy tool is not available"
+        self.toolmanager.message_event(message, self)
+
+
+default_tools = {'home': ToolHome, 'back': ToolBack, 'forward': ToolForward,
+                 'zoom': ToolZoom, 'pan': ToolPan,
+                 'subplots': ConfigureSubplotsBase,
+                 'save': SaveFigureBase,
+                 'grid': ToolGrid,
+                 'grid_minor': ToolMinorGrid,
+                 'fullscreen': ToolFullScreen,
+                 'quit': ToolQuit,
+                 'quit_all': ToolQuitAll,
+                 'xscale': ToolXScale,
+                 'yscale': ToolYScale,
+                 'position': ToolCursorPosition,
+                 _views_positions: ToolViewsPositions,
+                 'cursor': ToolSetCursor,
+                 'rubberband': RubberbandBase,
+                 'help': ToolHelpBase,
+                 'copy': ToolCopyToClipboardBase,
+                 }
+
+default_toolbar_tools = [['navigation', ['home', 'back', 'forward']],
+                         ['zoompan', ['pan', 'zoom', 'subplots']],
+                         ['io', ['save', 'help']]]
+
+
+def add_tools_to_manager(toolmanager, tools=default_tools):
+    """
+    Add multiple tools to a `.ToolManager`.
+
+    Parameters
+    ----------
+    toolmanager : `.backend_managers.ToolManager`
+        Manager to which the tools are added.
+    tools : {str: class_like}, optional
+        The tools to add in a {name: tool} dict, see
+        `.backend_managers.ToolManager.add_tool` for more info.
+    """
+
+    for name, tool in tools.items():
+        toolmanager.add_tool(name, tool)
+
+
+def add_tools_to_container(container, tools=default_toolbar_tools):
+    """
+    Add multiple tools to the container.
+
+    Parameters
+    ----------
+    container : Container
+        `.backend_bases.ToolContainerBase` object that will get the tools
+        added.
+    tools : list, optional
+        List in the form ``[[group1, [tool1, tool2 ...]], [group2, [...]]]``
+        where the tools ``[tool1, tool2, ...]`` will display in group1.
+        See `.backend_bases.ToolContainerBase.add_tool` for details.
+    """
+
+    for group, grouptools in tools:
+        for position, tool in enumerate(grouptools):
+            container.add_tool(tool, group, position)
diff --git a/lib/python3.12/site-packages/matplotlib/backend_tools.pyi b/lib/python3.12/site-packages/matplotlib/backend_tools.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..32fe8c2f5a7982ce5e2b07a58ac142c645a9ce2b
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/backend_tools.pyi
@@ -0,0 +1,121 @@
+import enum
+from matplotlib import cbook
+from matplotlib.axes import Axes
+from matplotlib.backend_bases import ToolContainerBase, FigureCanvasBase
+from matplotlib.backend_managers import ToolManager, ToolEvent
+from matplotlib.figure import Figure
+from matplotlib.scale import ScaleBase
+
+from typing import Any, cast
+
+class Cursors(enum.IntEnum):
+    POINTER = cast(int, ...)
+    HAND = cast(int, ...)
+    SELECT_REGION = cast(int, ...)
+    MOVE = cast(int, ...)
+    WAIT = cast(int, ...)
+    RESIZE_HORIZONTAL = cast(int, ...)
+    RESIZE_VERTICAL = cast(int, ...)
+
+cursors = Cursors
+
+class ToolBase:
+    @property
+    def default_keymap(self) -> list[str] | None: ...
+    description: str | None
+    image: str | None
+    def __init__(self, toolmanager: ToolManager, name: str) -> None: ...
+    @property
+    def name(self) -> str: ...
+    @property
+    def toolmanager(self) -> ToolManager: ...
+    @property
+    def canvas(self) -> FigureCanvasBase | None: ...
+    @property
+    def figure(self) -> Figure | None: ...
+    @figure.setter
+    def figure(self, figure: Figure | None) -> None: ...
+    def set_figure(self, figure: Figure | None) -> None: ...
+    def trigger(self, sender: Any, event: ToolEvent, data: Any = ...) -> None: ...
+
+class ToolToggleBase(ToolBase):
+    radio_group: str | None
+    cursor: Cursors | None
+    default_toggled: bool
+    def __init__(self, *args, **kwargs) -> None: ...
+    def enable(self, event: ToolEvent | None = ...) -> None: ...
+    def disable(self, event: ToolEvent | None = ...) -> None: ...
+    @property
+    def toggled(self) -> bool: ...
+    def set_figure(self, figure: Figure | None) -> None: ...
+
+class ToolSetCursor(ToolBase): ...
+
+class ToolCursorPosition(ToolBase):
+    def send_message(self, event: ToolEvent) -> None: ...
+
+class RubberbandBase(ToolBase):
+    def draw_rubberband(self, *data) -> None: ...
+    def remove_rubberband(self) -> None: ...
+
+class ToolQuit(ToolBase): ...
+class ToolQuitAll(ToolBase): ...
+class ToolGrid(ToolBase): ...
+class ToolMinorGrid(ToolBase): ...
+class ToolFullScreen(ToolBase): ...
+
+class AxisScaleBase(ToolToggleBase):
+    def enable(self, event: ToolEvent | None = ...) -> None: ...
+    def disable(self, event: ToolEvent | None = ...) -> None: ...
+
+class ToolYScale(AxisScaleBase):
+    def set_scale(self, ax: Axes, scale: str | ScaleBase) -> None: ...
+
+class ToolXScale(AxisScaleBase):
+    def set_scale(self, ax, scale: str | ScaleBase) -> None: ...
+
+class ToolViewsPositions(ToolBase):
+    views: dict[Figure | Axes, cbook._Stack]
+    positions: dict[Figure | Axes, cbook._Stack]
+    home_views: dict[Figure, dict[Axes, tuple[float, float, float, float]]]
+    def add_figure(self, figure: Figure) -> None: ...
+    def clear(self, figure: Figure) -> None: ...
+    def update_view(self) -> None: ...
+    def push_current(self, figure: Figure | None = ...) -> None: ...
+    def update_home_views(self, figure: Figure | None = ...) -> None: ...
+    def home(self) -> None: ...
+    def back(self) -> None: ...
+    def forward(self) -> None: ...
+
+class ViewsPositionsBase(ToolBase): ...
+class ToolHome(ViewsPositionsBase): ...
+class ToolBack(ViewsPositionsBase): ...
+class ToolForward(ViewsPositionsBase): ...
+class ConfigureSubplotsBase(ToolBase): ...
+class SaveFigureBase(ToolBase): ...
+
+class ZoomPanBase(ToolToggleBase):
+    base_scale: float
+    scrollthresh: float
+    lastscroll: float
+    def __init__(self, *args) -> None: ...
+    def enable(self, event: ToolEvent | None = ...) -> None: ...
+    def disable(self, event: ToolEvent | None = ...) -> None: ...
+    def scroll_zoom(self, event: ToolEvent) -> None: ...
+
+class ToolZoom(ZoomPanBase): ...
+class ToolPan(ZoomPanBase): ...
+
+class ToolHelpBase(ToolBase):
+    @staticmethod
+    def format_shortcut(key_sequence: str) -> str: ...
+
+class ToolCopyToClipboardBase(ToolBase): ...
+
+default_tools: dict[str, ToolBase]
+default_toolbar_tools: list[list[str | list[str]]]
+
+def add_tools_to_manager(
+    toolmanager: ToolManager, tools: dict[str, type[ToolBase]] = ...
+) -> None: ...
+def add_tools_to_container(container: ToolContainerBase, tools: list[Any] = ...) -> None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/bezier.py b/lib/python3.12/site-packages/matplotlib/bezier.py
new file mode 100644
index 0000000000000000000000000000000000000000..42a6b478d729f3b2837e11e6767b84ac5972654d
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/bezier.py
@@ -0,0 +1,602 @@
+"""
+A module providing some utility functions regarding Bézier path manipulation.
+"""
+
+from functools import lru_cache
+import math
+import warnings
+
+import numpy as np
+
+from matplotlib import _api
+
+
+# same algorithm as 3.8's math.comb
+@np.vectorize
+@lru_cache(maxsize=128)
+def _comb(n, k):
+    if k > n:
+        return 0
+    k = min(k, n - k)
+    i = np.arange(1, k + 1)
+    return np.prod((n + 1 - i)/i).astype(int)
+
+
+class NonIntersectingPathException(ValueError):
+    pass
+
+
+# some functions
+
+
+def get_intersection(cx1, cy1, cos_t1, sin_t1,
+                     cx2, cy2, cos_t2, sin_t2):
+    """
+    Return the intersection between the line through (*cx1*, *cy1*) at angle
+    *t1* and the line through (*cx2*, *cy2*) at angle *t2*.
+    """
+
+    # line1 => sin_t1 * (x - cx1) - cos_t1 * (y - cy1) = 0.
+    # line1 => sin_t1 * x + cos_t1 * y = sin_t1*cx1 - cos_t1*cy1
+
+    line1_rhs = sin_t1 * cx1 - cos_t1 * cy1
+    line2_rhs = sin_t2 * cx2 - cos_t2 * cy2
+
+    # rhs matrix
+    a, b = sin_t1, -cos_t1
+    c, d = sin_t2, -cos_t2
+
+    ad_bc = a * d - b * c
+    if abs(ad_bc) < 1e-12:
+        raise ValueError("Given lines do not intersect. Please verify that "
+                         "the angles are not equal or differ by 180 degrees.")
+
+    # rhs_inverse
+    a_, b_ = d, -b
+    c_, d_ = -c, a
+    a_, b_, c_, d_ = (k / ad_bc for k in [a_, b_, c_, d_])
+
+    x = a_ * line1_rhs + b_ * line2_rhs
+    y = c_ * line1_rhs + d_ * line2_rhs
+
+    return x, y
+
+
+def get_normal_points(cx, cy, cos_t, sin_t, length):
+    """
+    For a line passing through (*cx*, *cy*) and having an angle *t*, return
+    locations of the two points located along its perpendicular line at the
+    distance of *length*.
+    """
+
+    if length == 0.:
+        return cx, cy, cx, cy
+
+    cos_t1, sin_t1 = sin_t, -cos_t
+    cos_t2, sin_t2 = -sin_t, cos_t
+
+    x1, y1 = length * cos_t1 + cx, length * sin_t1 + cy
+    x2, y2 = length * cos_t2 + cx, length * sin_t2 + cy
+
+    return x1, y1, x2, y2
+
+
+# BEZIER routines
+
+# subdividing bezier curve
+# http://www.cs.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/Bezier/bezier-sub.html
+
+
+def _de_casteljau1(beta, t):
+    next_beta = beta[:-1] * (1 - t) + beta[1:] * t
+    return next_beta
+
+
+def split_de_casteljau(beta, t):
+    """
+    Split a Bézier segment defined by its control points *beta* into two
+    separate segments divided at *t* and return their control points.
+    """
+    beta = np.asarray(beta)
+    beta_list = [beta]
+    while True:
+        beta = _de_casteljau1(beta, t)
+        beta_list.append(beta)
+        if len(beta) == 1:
+            break
+    left_beta = [beta[0] for beta in beta_list]
+    right_beta = [beta[-1] for beta in reversed(beta_list)]
+
+    return left_beta, right_beta
+
+
+def find_bezier_t_intersecting_with_closedpath(
+        bezier_point_at_t, inside_closedpath, t0=0., t1=1., tolerance=0.01):
+    """
+    Find the intersection of the Bézier curve with a closed path.
+
+    The intersection point *t* is approximated by two parameters *t0*, *t1*
+    such that *t0* <= *t* <= *t1*.
+
+    Search starts from *t0* and *t1* and uses a simple bisecting algorithm
+    therefore one of the end points must be inside the path while the other
+    doesn't. The search stops when the distance of the points parametrized by
+    *t0* and *t1* gets smaller than the given *tolerance*.
+
+    Parameters
+    ----------
+    bezier_point_at_t : callable
+        A function returning x, y coordinates of the Bézier at parameter *t*.
+        It must have the signature::
+
+            bezier_point_at_t(t: float) -> tuple[float, float]
+
+    inside_closedpath : callable
+        A function returning True if a given point (x, y) is inside the
+        closed path. It must have the signature::
+
+            inside_closedpath(point: tuple[float, float]) -> bool
+
+    t0, t1 : float
+        Start parameters for the search.
+
+    tolerance : float
+        Maximal allowed distance between the final points.
+
+    Returns
+    -------
+    t0, t1 : float
+        The Bézier path parameters.
+    """
+    start = bezier_point_at_t(t0)
+    end = bezier_point_at_t(t1)
+
+    start_inside = inside_closedpath(start)
+    end_inside = inside_closedpath(end)
+
+    if start_inside == end_inside and start != end:
+        raise NonIntersectingPathException(
+            "Both points are on the same side of the closed path")
+
+    while True:
+
+        # return if the distance is smaller than the tolerance
+        if np.hypot(start[0] - end[0], start[1] - end[1]) < tolerance:
+            return t0, t1
+
+        # calculate the middle point
+        middle_t = 0.5 * (t0 + t1)
+        middle = bezier_point_at_t(middle_t)
+        middle_inside = inside_closedpath(middle)
+
+        if start_inside ^ middle_inside:
+            t1 = middle_t
+            if end == middle:
+                # Edge case where infinite loop is possible
+                # Caused by large numbers relative to tolerance
+                return t0, t1
+            end = middle
+        else:
+            t0 = middle_t
+            if start == middle:
+                # Edge case where infinite loop is possible
+                # Caused by large numbers relative to tolerance
+                return t0, t1
+            start = middle
+            start_inside = middle_inside
+
+
+class BezierSegment:
+    """
+    A d-dimensional Bézier segment.
+
+    Parameters
+    ----------
+    control_points : (N, d) array
+        Location of the *N* control points.
+    """
+
+    def __init__(self, control_points):
+        self._cpoints = np.asarray(control_points)
+        self._N, self._d = self._cpoints.shape
+        self._orders = np.arange(self._N)
+        coeff = [math.factorial(self._N - 1)
+                 // (math.factorial(i) * math.factorial(self._N - 1 - i))
+                 for i in range(self._N)]
+        self._px = (self._cpoints.T * coeff).T
+
+    def __call__(self, t):
+        """
+        Evaluate the Bézier curve at point(s) *t* in [0, 1].
+
+        Parameters
+        ----------
+        t : (k,) array-like
+            Points at which to evaluate the curve.
+
+        Returns
+        -------
+        (k, d) array
+            Value of the curve for each point in *t*.
+        """
+        t = np.asarray(t)
+        return (np.power.outer(1 - t, self._orders[::-1])
+                * np.power.outer(t, self._orders)) @ self._px
+
+    def point_at_t(self, t):
+        """
+        Evaluate the curve at a single point, returning a tuple of *d* floats.
+        """
+        return tuple(self(t))
+
+    @property
+    def control_points(self):
+        """The control points of the curve."""
+        return self._cpoints
+
+    @property
+    def dimension(self):
+        """The dimension of the curve."""
+        return self._d
+
+    @property
+    def degree(self):
+        """Degree of the polynomial. One less the number of control points."""
+        return self._N - 1
+
+    @property
+    def polynomial_coefficients(self):
+        r"""
+        The polynomial coefficients of the Bézier curve.
+
+        .. warning:: Follows opposite convention from `numpy.polyval`.
+
+        Returns
+        -------
+        (n+1, d) array
+            Coefficients after expanding in polynomial basis, where :math:`n`
+            is the degree of the Bézier curve and :math:`d` its dimension.
+            These are the numbers (:math:`C_j`) such that the curve can be
+            written :math:`\sum_{j=0}^n C_j t^j`.
+
+        Notes
+        -----
+        The coefficients are calculated as
+
+        .. math::
+
+            {n \choose j} \sum_{i=0}^j (-1)^{i+j} {j \choose i} P_i
+
+        where :math:`P_i` are the control points of the curve.
+        """
+        n = self.degree
+        # matplotlib uses n <= 4. overflow plausible starting around n = 15.
+        if n > 10:
+            warnings.warn("Polynomial coefficients formula unstable for high "
+                          "order Bezier curves!", RuntimeWarning)
+        P = self.control_points
+        j = np.arange(n+1)[:, None]
+        i = np.arange(n+1)[None, :]  # _comb is non-zero for i <= j
+        prefactor = (-1)**(i + j) * _comb(j, i)  # j on axis 0, i on axis 1
+        return _comb(n, j) * prefactor @ P  # j on axis 0, self.dimension on 1
+
+    def axis_aligned_extrema(self):
+        """
+        Return the dimension and location of the curve's interior extrema.
+
+        The extrema are the points along the curve where one of its partial
+        derivatives is zero.
+
+        Returns
+        -------
+        dims : array of int
+            Index :math:`i` of the partial derivative which is zero at each
+            interior extrema.
+        dzeros : array of float
+            Of same size as dims. The :math:`t` such that :math:`d/dx_i B(t) =
+            0`
+        """
+        n = self.degree
+        if n <= 1:
+            return np.array([]), np.array([])
+        Cj = self.polynomial_coefficients
+        dCj = np.arange(1, n+1)[:, None] * Cj[1:]
+        dims = []
+        roots = []
+        for i, pi in enumerate(dCj.T):
+            r = np.roots(pi[::-1])
+            roots.append(r)
+            dims.append(np.full_like(r, i))
+        roots = np.concatenate(roots)
+        dims = np.concatenate(dims)
+        in_range = np.isreal(roots) & (roots >= 0) & (roots <= 1)
+        return dims[in_range], np.real(roots)[in_range]
+
+
+def split_bezier_intersecting_with_closedpath(
+        bezier, inside_closedpath, tolerance=0.01):
+    """
+    Split a Bézier curve into two at the intersection with a closed path.
+
+    Parameters
+    ----------
+    bezier : (N, 2) array-like
+        Control points of the Bézier segment. See `.BezierSegment`.
+    inside_closedpath : callable
+        A function returning True if a given point (x, y) is inside the
+        closed path. See also `.find_bezier_t_intersecting_with_closedpath`.
+    tolerance : float
+        The tolerance for the intersection. See also
+        `.find_bezier_t_intersecting_with_closedpath`.
+
+    Returns
+    -------
+    left, right
+        Lists of control points for the two Bézier segments.
+    """
+
+    bz = BezierSegment(bezier)
+    bezier_point_at_t = bz.point_at_t
+
+    t0, t1 = find_bezier_t_intersecting_with_closedpath(
+        bezier_point_at_t, inside_closedpath, tolerance=tolerance)
+
+    _left, _right = split_de_casteljau(bezier, (t0 + t1) / 2.)
+    return _left, _right
+
+
+# matplotlib specific
+
+
+def split_path_inout(path, inside, tolerance=0.01, reorder_inout=False):
+    """
+    Divide a path into two segments at the point where ``inside(x, y)`` becomes
+    False.
+    """
+    from .path import Path
+    path_iter = path.iter_segments()
+
+    ctl_points, command = next(path_iter)
+    begin_inside = inside(ctl_points[-2:])  # true if begin point is inside
+
+    ctl_points_old = ctl_points
+
+    iold = 0
+    i = 1
+
+    for ctl_points, command in path_iter:
+        iold = i
+        i += len(ctl_points) // 2
+        if inside(ctl_points[-2:]) != begin_inside:
+            bezier_path = np.concatenate([ctl_points_old[-2:], ctl_points])
+            break
+        ctl_points_old = ctl_points
+    else:
+        raise ValueError("The path does not intersect with the patch")
+
+    bp = bezier_path.reshape((-1, 2))
+    left, right = split_bezier_intersecting_with_closedpath(
+        bp, inside, tolerance)
+    if len(left) == 2:
+        codes_left = [Path.LINETO]
+        codes_right = [Path.MOVETO, Path.LINETO]
+    elif len(left) == 3:
+        codes_left = [Path.CURVE3, Path.CURVE3]
+        codes_right = [Path.MOVETO, Path.CURVE3, Path.CURVE3]
+    elif len(left) == 4:
+        codes_left = [Path.CURVE4, Path.CURVE4, Path.CURVE4]
+        codes_right = [Path.MOVETO, Path.CURVE4, Path.CURVE4, Path.CURVE4]
+    else:
+        raise AssertionError("This should never be reached")
+
+    verts_left = left[1:]
+    verts_right = right[:]
+
+    if path.codes is None:
+        path_in = Path(np.concatenate([path.vertices[:i], verts_left]))
+        path_out = Path(np.concatenate([verts_right, path.vertices[i:]]))
+
+    else:
+        path_in = Path(np.concatenate([path.vertices[:iold], verts_left]),
+                       np.concatenate([path.codes[:iold], codes_left]))
+
+        path_out = Path(np.concatenate([verts_right, path.vertices[i:]]),
+                        np.concatenate([codes_right, path.codes[i:]]))
+
+    if reorder_inout and not begin_inside:
+        path_in, path_out = path_out, path_in
+
+    return path_in, path_out
+
+
+def inside_circle(cx, cy, r):
+    """
+    Return a function that checks whether a point is in a circle with center
+    (*cx*, *cy*) and radius *r*.
+
+    The returned function has the signature::
+
+        f(xy: tuple[float, float]) -> bool
+    """
+    r2 = r ** 2
+
+    def _f(xy):
+        x, y = xy
+        return (x - cx) ** 2 + (y - cy) ** 2 < r2
+    return _f
+
+
+# quadratic Bezier lines
+
+def get_cos_sin(x0, y0, x1, y1):
+    dx, dy = x1 - x0, y1 - y0
+    d = (dx * dx + dy * dy) ** .5
+    # Account for divide by zero
+    if d == 0:
+        return 0.0, 0.0
+    return dx / d, dy / d
+
+
+def check_if_parallel(dx1, dy1, dx2, dy2, tolerance=1.e-5):
+    """
+    Check if two lines are parallel.
+
+    Parameters
+    ----------
+    dx1, dy1, dx2, dy2 : float
+        The gradients *dy*/*dx* of the two lines.
+    tolerance : float
+        The angular tolerance in radians up to which the lines are considered
+        parallel.
+
+    Returns
+    -------
+    is_parallel
+        - 1 if two lines are parallel in same direction.
+        - -1 if two lines are parallel in opposite direction.
+        - False otherwise.
+    """
+    theta1 = np.arctan2(dx1, dy1)
+    theta2 = np.arctan2(dx2, dy2)
+    dtheta = abs(theta1 - theta2)
+    if dtheta < tolerance:
+        return 1
+    elif abs(dtheta - np.pi) < tolerance:
+        return -1
+    else:
+        return False
+
+
+def get_parallels(bezier2, width):
+    """
+    Given the quadratic Bézier control points *bezier2*, returns
+    control points of quadratic Bézier lines roughly parallel to given
+    one separated by *width*.
+    """
+
+    # The parallel Bezier lines are constructed by following ways.
+    #  c1 and c2 are control points representing the start and end of the
+    #  Bezier line.
+    #  cm is the middle point
+
+    c1x, c1y = bezier2[0]
+    cmx, cmy = bezier2[1]
+    c2x, c2y = bezier2[2]
+
+    parallel_test = check_if_parallel(c1x - cmx, c1y - cmy,
+                                      cmx - c2x, cmy - c2y)
+
+    if parallel_test == -1:
+        _api.warn_external(
+            "Lines do not intersect. A straight line is used instead.")
+        cos_t1, sin_t1 = get_cos_sin(c1x, c1y, c2x, c2y)
+        cos_t2, sin_t2 = cos_t1, sin_t1
+    else:
+        # t1 and t2 is the angle between c1 and cm, cm, c2.  They are
+        # also an angle of the tangential line of the path at c1 and c2
+        cos_t1, sin_t1 = get_cos_sin(c1x, c1y, cmx, cmy)
+        cos_t2, sin_t2 = get_cos_sin(cmx, cmy, c2x, c2y)
+
+    # find c1_left, c1_right which are located along the lines
+    # through c1 and perpendicular to the tangential lines of the
+    # Bezier path at a distance of width. Same thing for c2_left and
+    # c2_right with respect to c2.
+    c1x_left, c1y_left, c1x_right, c1y_right = (
+        get_normal_points(c1x, c1y, cos_t1, sin_t1, width)
+    )
+    c2x_left, c2y_left, c2x_right, c2y_right = (
+        get_normal_points(c2x, c2y, cos_t2, sin_t2, width)
+    )
+
+    # find cm_left which is the intersecting point of a line through
+    # c1_left with angle t1 and a line through c2_left with angle
+    # t2. Same with cm_right.
+    try:
+        cmx_left, cmy_left = get_intersection(c1x_left, c1y_left, cos_t1,
+                                              sin_t1, c2x_left, c2y_left,
+                                              cos_t2, sin_t2)
+        cmx_right, cmy_right = get_intersection(c1x_right, c1y_right, cos_t1,
+                                                sin_t1, c2x_right, c2y_right,
+                                                cos_t2, sin_t2)
+    except ValueError:
+        # Special case straight lines, i.e., angle between two lines is
+        # less than the threshold used by get_intersection (we don't use
+        # check_if_parallel as the threshold is not the same).
+        cmx_left, cmy_left = (
+            0.5 * (c1x_left + c2x_left), 0.5 * (c1y_left + c2y_left)
+        )
+        cmx_right, cmy_right = (
+            0.5 * (c1x_right + c2x_right), 0.5 * (c1y_right + c2y_right)
+        )
+
+    # the parallel Bezier lines are created with control points of
+    # [c1_left, cm_left, c2_left] and [c1_right, cm_right, c2_right]
+    path_left = [(c1x_left, c1y_left),
+                 (cmx_left, cmy_left),
+                 (c2x_left, c2y_left)]
+    path_right = [(c1x_right, c1y_right),
+                  (cmx_right, cmy_right),
+                  (c2x_right, c2y_right)]
+
+    return path_left, path_right
+
+
+def find_control_points(c1x, c1y, mmx, mmy, c2x, c2y):
+    """
+    Find control points of the Bézier curve passing through (*c1x*, *c1y*),
+    (*mmx*, *mmy*), and (*c2x*, *c2y*), at parametric values 0, 0.5, and 1.
+    """
+    cmx = .5 * (4 * mmx - (c1x + c2x))
+    cmy = .5 * (4 * mmy - (c1y + c2y))
+    return [(c1x, c1y), (cmx, cmy), (c2x, c2y)]
+
+
+def make_wedged_bezier2(bezier2, width, w1=1., wm=0.5, w2=0.):
+    """
+    Being similar to `get_parallels`, returns control points of two quadratic
+    Bézier lines having a width roughly parallel to given one separated by
+    *width*.
+    """
+
+    # c1, cm, c2
+    c1x, c1y = bezier2[0]
+    cmx, cmy = bezier2[1]
+    c3x, c3y = bezier2[2]
+
+    # t1 and t2 is the angle between c1 and cm, cm, c3.
+    # They are also an angle of the tangential line of the path at c1 and c3
+    cos_t1, sin_t1 = get_cos_sin(c1x, c1y, cmx, cmy)
+    cos_t2, sin_t2 = get_cos_sin(cmx, cmy, c3x, c3y)
+
+    # find c1_left, c1_right which are located along the lines
+    # through c1 and perpendicular to the tangential lines of the
+    # Bezier path at a distance of width. Same thing for c3_left and
+    # c3_right with respect to c3.
+    c1x_left, c1y_left, c1x_right, c1y_right = (
+        get_normal_points(c1x, c1y, cos_t1, sin_t1, width * w1)
+    )
+    c3x_left, c3y_left, c3x_right, c3y_right = (
+        get_normal_points(c3x, c3y, cos_t2, sin_t2, width * w2)
+    )
+
+    # find c12, c23 and c123 which are middle points of c1-cm, cm-c3 and
+    # c12-c23
+    c12x, c12y = (c1x + cmx) * .5, (c1y + cmy) * .5
+    c23x, c23y = (cmx + c3x) * .5, (cmy + c3y) * .5
+    c123x, c123y = (c12x + c23x) * .5, (c12y + c23y) * .5
+
+    # tangential angle of c123 (angle between c12 and c23)
+    cos_t123, sin_t123 = get_cos_sin(c12x, c12y, c23x, c23y)
+
+    c123x_left, c123y_left, c123x_right, c123y_right = (
+        get_normal_points(c123x, c123y, cos_t123, sin_t123, width * wm)
+    )
+
+    path_left = find_control_points(c1x_left, c1y_left,
+                                    c123x_left, c123y_left,
+                                    c3x_left, c3y_left)
+    path_right = find_control_points(c1x_right, c1y_right,
+                                     c123x_right, c123y_right,
+                                     c3x_right, c3y_right)
+
+    return path_left, path_right
diff --git a/lib/python3.12/site-packages/matplotlib/bezier.pyi b/lib/python3.12/site-packages/matplotlib/bezier.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..ad82b873affd3902290347be2fae3a3b754f35da
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/bezier.pyi
@@ -0,0 +1,74 @@
+from collections.abc import Callable
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .path import Path
+
+class NonIntersectingPathException(ValueError): ...
+
+def get_intersection(
+    cx1: float,
+    cy1: float,
+    cos_t1: float,
+    sin_t1: float,
+    cx2: float,
+    cy2: float,
+    cos_t2: float,
+    sin_t2: float,
+) -> tuple[float, float]: ...
+def get_normal_points(
+    cx: float, cy: float, cos_t: float, sin_t: float, length: float
+) -> tuple[float, float, float, float]: ...
+def split_de_casteljau(beta: ArrayLike, t: float) -> tuple[np.ndarray, np.ndarray]: ...
+def find_bezier_t_intersecting_with_closedpath(
+    bezier_point_at_t: Callable[[float], tuple[float, float]],
+    inside_closedpath: Callable[[tuple[float, float]], bool],
+    t0: float = ...,
+    t1: float = ...,
+    tolerance: float = ...,
+) -> tuple[float, float]: ...
+
+# TODO make generic over d, the dimension? ndarraydim
+class BezierSegment:
+    def __init__(self, control_points: ArrayLike) -> None: ...
+    def __call__(self, t: ArrayLike) -> np.ndarray: ...
+    def point_at_t(self, t: float) -> tuple[float, ...]: ...
+    @property
+    def control_points(self) -> np.ndarray: ...
+    @property
+    def dimension(self) -> int: ...
+    @property
+    def degree(self) -> int: ...
+    @property
+    def polynomial_coefficients(self) -> np.ndarray: ...
+    def axis_aligned_extrema(self) -> tuple[np.ndarray, np.ndarray]: ...
+
+def split_bezier_intersecting_with_closedpath(
+    bezier: ArrayLike,
+    inside_closedpath: Callable[[tuple[float, float]], bool],
+    tolerance: float = ...,
+) -> tuple[np.ndarray, np.ndarray]: ...
+def split_path_inout(
+    path: Path,
+    inside: Callable[[tuple[float, float]], bool],
+    tolerance: float = ...,
+    reorder_inout: bool = ...,
+) -> tuple[Path, Path]: ...
+def inside_circle(
+    cx: float, cy: float, r: float
+) -> Callable[[tuple[float, float]], bool]: ...
+def get_cos_sin(x0: float, y0: float, x1: float, y1: float) -> tuple[float, float]: ...
+def check_if_parallel(
+    dx1: float, dy1: float, dx2: float, dy2: float, tolerance: float = ...
+) -> Literal[-1, False, 1]: ...
+def get_parallels(
+    bezier2: ArrayLike, width: float
+) -> tuple[list[tuple[float, float]], list[tuple[float, float]]]: ...
+def find_control_points(
+    c1x: float, c1y: float, mmx: float, mmy: float, c2x: float, c2y: float
+) -> list[tuple[float, float]]: ...
+def make_wedged_bezier2(
+    bezier2: ArrayLike, width: float, w1: float = ..., wm: float = ..., w2: float = ...
+) -> tuple[list[tuple[float, float]], list[tuple[float, float]]]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/cbook.pyi b/lib/python3.12/site-packages/matplotlib/cbook.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..cc6b4e8f4e1963922a75a140ff127d9bb5ead58c
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/cbook.pyi
@@ -0,0 +1,173 @@
+import collections.abc
+from collections.abc import Callable, Collection, Generator, Iterable, Iterator
+import contextlib
+import os
+from pathlib import Path
+
+from matplotlib.artist import Artist
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from typing import (
+    Any,
+    Generic,
+    IO,
+    Literal,
+    TypeVar,
+    overload,
+)
+
+_T = TypeVar("_T")
+
+def _get_running_interactive_framework() -> str | None: ...
+
+class CallbackRegistry:
+    exception_handler: Callable[[Exception], Any]
+    callbacks: dict[Any, dict[int, Any]]
+    def __init__(
+        self,
+        exception_handler: Callable[[Exception], Any] | None = ...,
+        *,
+        signals: Iterable[Any] | None = ...,
+    ) -> None: ...
+    def connect(self, signal: Any, func: Callable) -> int: ...
+    def disconnect(self, cid: int) -> None: ...
+    def process(self, s: Any, *args, **kwargs) -> None: ...
+    def blocked(
+        self, *, signal: Any | None = ...
+    ) -> contextlib.AbstractContextManager[None]: ...
+
+class silent_list(list[_T]):
+    type: str | None
+    def __init__(self, type: str | None, seq: Iterable[_T] | None = ...) -> None: ...
+
+def strip_math(s: str) -> str: ...
+def is_writable_file_like(obj: Any) -> bool: ...
+def file_requires_unicode(x: Any) -> bool: ...
+@overload
+def to_filehandle(
+    fname: str | os.PathLike | IO,
+    flag: str = ...,
+    return_opened: Literal[False] = ...,
+    encoding: str | None = ...,
+) -> IO: ...
+@overload
+def to_filehandle(
+    fname: str | os.PathLike | IO,
+    flag: str,
+    return_opened: Literal[True],
+    encoding: str | None = ...,
+) -> tuple[IO, bool]: ...
+@overload
+def to_filehandle(
+    fname: str | os.PathLike | IO,
+    *,  # if flag given, will match previous sig
+    return_opened: Literal[True],
+    encoding: str | None = ...,
+) -> tuple[IO, bool]: ...
+def open_file_cm(
+    path_or_file: str | os.PathLike | IO,
+    mode: str = ...,
+    encoding: str | None = ...,
+) -> contextlib.AbstractContextManager[IO]: ...
+def is_scalar_or_string(val: Any) -> bool: ...
+@overload
+def get_sample_data(
+    fname: str | os.PathLike, asfileobj: Literal[True] = ...
+) -> np.ndarray | IO: ...
+@overload
+def get_sample_data(fname: str | os.PathLike, asfileobj: Literal[False]) -> str: ...
+def _get_data_path(*args: Path | str) -> Path: ...
+def flatten(
+    seq: Iterable[Any], scalarp: Callable[[Any], bool] = ...
+) -> Generator[Any, None, None]: ...
+
+class _Stack(Generic[_T]):
+    def __init__(self) -> None: ...
+    def clear(self) -> None: ...
+    def __call__(self) -> _T: ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, ind: int) -> _T: ...
+    def forward(self) -> _T: ...
+    def back(self) -> _T: ...
+    def push(self, o: _T) -> _T: ...
+    def home(self) -> _T: ...
+
+def safe_masked_invalid(x: ArrayLike, copy: bool = ...) -> np.ndarray: ...
+def print_cycles(
+    objects: Iterable[Any], outstream: IO = ..., show_progress: bool = ...
+) -> None: ...
+
+class Grouper(Generic[_T]):
+    def __init__(self, init: Iterable[_T] = ...) -> None: ...
+    def __contains__(self, item: _T) -> bool: ...
+    def join(self, a: _T, *args: _T) -> None: ...
+    def joined(self, a: _T, b: _T) -> bool: ...
+    def remove(self, a: _T) -> None: ...
+    def __iter__(self) -> Iterator[list[_T]]: ...
+    def get_siblings(self, a: _T) -> list[_T]: ...
+
+class GrouperView(Generic[_T]):
+    def __init__(self, grouper: Grouper[_T]) -> None: ...
+    def __contains__(self, item: _T) -> bool: ...
+    def __iter__(self) -> Iterator[list[_T]]: ...
+    def joined(self, a: _T, b: _T) -> bool: ...
+    def get_siblings(self, a: _T) -> list[_T]: ...
+
+def simple_linear_interpolation(a: ArrayLike, steps: int) -> np.ndarray: ...
+def delete_masked_points(*args): ...
+def _broadcast_with_masks(*args: ArrayLike, compress: bool = ...) -> list[ArrayLike]: ...
+def boxplot_stats(
+    X: ArrayLike,
+    whis: float | tuple[float, float] = ...,
+    bootstrap: int | None = ...,
+    labels: ArrayLike | None = ...,
+    autorange: bool = ...,
+) -> list[dict[str, Any]]: ...
+
+ls_mapper: dict[str, str]
+ls_mapper_r: dict[str, str]
+
+def contiguous_regions(mask: ArrayLike) -> list[np.ndarray]: ...
+def is_math_text(s: str) -> bool: ...
+def violin_stats(
+    X: ArrayLike, method: Callable, points: int = ..., quantiles: ArrayLike | None = ...
+) -> list[dict[str, Any]]: ...
+def pts_to_prestep(x: ArrayLike, *args: ArrayLike) -> np.ndarray: ...
+def pts_to_poststep(x: ArrayLike, *args: ArrayLike) -> np.ndarray: ...
+def pts_to_midstep(x: np.ndarray, *args: np.ndarray) -> np.ndarray: ...
+
+STEP_LOOKUP_MAP: dict[str, Callable]
+
+def index_of(y: float | ArrayLike) -> tuple[np.ndarray, np.ndarray]: ...
+def safe_first_element(obj: Collection[_T]) -> _T: ...
+def sanitize_sequence(data): ...
+def normalize_kwargs(
+    kw: dict[str, Any],
+    alias_mapping: dict[str, list[str]] | type[Artist] | Artist | None = ...,
+) -> dict[str, Any]: ...
+def _lock_path(path: str | os.PathLike) -> contextlib.AbstractContextManager[None]: ...
+def _str_equal(obj: Any, s: str) -> bool: ...
+def _str_lower_equal(obj: Any, s: str) -> bool: ...
+def _array_perimeter(arr: np.ndarray) -> np.ndarray: ...
+def _unfold(arr: np.ndarray, axis: int, size: int, step: int) -> np.ndarray: ...
+def _array_patch_perimeters(x: np.ndarray, rstride: int, cstride: int) -> np.ndarray: ...
+def _setattr_cm(obj: Any, **kwargs) -> contextlib.AbstractContextManager[None]: ...
+
+class _OrderedSet(collections.abc.MutableSet):
+    def __init__(self) -> None: ...
+    def __contains__(self, key) -> bool: ...
+    def __iter__(self): ...
+    def __len__(self) -> int: ...
+    def add(self, key) -> None: ...
+    def discard(self, key) -> None: ...
+
+def _setup_new_guiapp() -> None: ...
+def _format_approx(number: float, precision: int) -> str: ...
+def _g_sig_digits(value: float, delta: float) -> int: ...
+def _unikey_or_keysym_to_mplkey(unikey: str, keysym: str) -> str: ...
+def _is_torch_array(x: Any) -> bool: ...
+def _is_jax_array(x: Any) -> bool: ...
+def _unpack_to_numpy(x: Any) -> Any: ...
+def _auto_format_str(fmt: str, value: Any) -> str: ...
diff --git a/lib/python3.12/site-packages/matplotlib/cm.py b/lib/python3.12/site-packages/matplotlib/cm.py
new file mode 100644
index 0000000000000000000000000000000000000000..0c11527bc2b925d57cdd7198a10c13118cfe9d16
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/cm.py
@@ -0,0 +1,310 @@
+"""
+Builtin colormaps, colormap handling utilities, and the `ScalarMappable` mixin.
+
+.. seealso::
+
+  :doc:`/gallery/color/colormap_reference` for a list of builtin colormaps.
+
+  :ref:`colormap-manipulation` for examples of how to make
+  colormaps.
+
+  :ref:`colormaps` an in-depth discussion of choosing
+  colormaps.
+
+  :ref:`colormapnorms` for more details about data normalization.
+"""
+
+from collections.abc import Mapping
+
+import matplotlib as mpl
+from matplotlib import _api, colors
+# TODO make this warn on access
+from matplotlib.colorizer import _ScalarMappable as ScalarMappable  # noqa
+from matplotlib._cm import datad
+from matplotlib._cm_listed import cmaps as cmaps_listed
+from matplotlib._cm_multivar import cmap_families as multivar_cmaps
+from matplotlib._cm_bivar import cmaps as bivar_cmaps
+
+
+_LUTSIZE = mpl.rcParams['image.lut']
+
+
+def _gen_cmap_registry():
+    """
+    Generate a dict mapping standard colormap names to standard colormaps, as
+    well as the reversed colormaps.
+    """
+    cmap_d = {**cmaps_listed}
+    for name, spec in datad.items():
+        cmap_d[name] = (  # Precache the cmaps at a fixed lutsize..
+            colors.LinearSegmentedColormap(name, spec, _LUTSIZE)
+            if 'red' in spec else
+            colors.ListedColormap(spec['listed'], name)
+            if 'listed' in spec else
+            colors.LinearSegmentedColormap.from_list(name, spec, _LUTSIZE))
+
+    # Register colormap aliases for gray and grey.
+    aliases = {
+        # alias -> original name
+        'grey': 'gray',
+        'gist_grey': 'gist_gray',
+        'gist_yerg': 'gist_yarg',
+        'Grays': 'Greys',
+    }
+    for alias, original_name in aliases.items():
+        cmap = cmap_d[original_name].copy()
+        cmap.name = alias
+        cmap_d[alias] = cmap
+
+    # Generate reversed cmaps.
+    for cmap in list(cmap_d.values()):
+        rmap = cmap.reversed()
+        cmap_d[rmap.name] = rmap
+    return cmap_d
+
+
+class ColormapRegistry(Mapping):
+    r"""
+    Container for colormaps that are known to Matplotlib by name.
+
+    The universal registry instance is `matplotlib.colormaps`. There should be
+    no need for users to instantiate `.ColormapRegistry` themselves.
+
+    Read access uses a dict-like interface mapping names to `.Colormap`\s::
+
+        import matplotlib as mpl
+        cmap = mpl.colormaps['viridis']
+
+    Returned `.Colormap`\s are copies, so that their modification does not
+    change the global definition of the colormap.
+
+    Additional colormaps can be added via `.ColormapRegistry.register`::
+
+        mpl.colormaps.register(my_colormap)
+
+    To get a list of all registered colormaps, you can do::
+
+        from matplotlib import colormaps
+        list(colormaps)
+    """
+    def __init__(self, cmaps):
+        self._cmaps = cmaps
+        self._builtin_cmaps = tuple(cmaps)
+
+    def __getitem__(self, item):
+        try:
+            return self._cmaps[item].copy()
+        except KeyError:
+            raise KeyError(f"{item!r} is not a known colormap name") from None
+
+    def __iter__(self):
+        return iter(self._cmaps)
+
+    def __len__(self):
+        return len(self._cmaps)
+
+    def __str__(self):
+        return ('ColormapRegistry; available colormaps:\n' +
+                ', '.join(f"'{name}'" for name in self))
+
+    def __call__(self):
+        """
+        Return a list of the registered colormap names.
+
+        This exists only for backward-compatibility in `.pyplot` which had a
+        ``plt.colormaps()`` method. The recommended way to get this list is
+        now ``list(colormaps)``.
+        """
+        return list(self)
+
+    def register(self, cmap, *, name=None, force=False):
+        """
+        Register a new colormap.
+
+        The colormap name can then be used as a string argument to any ``cmap``
+        parameter in Matplotlib. It is also available in ``pyplot.get_cmap``.
+
+        The colormap registry stores a copy of the given colormap, so that
+        future changes to the original colormap instance do not affect the
+        registered colormap. Think of this as the registry taking a snapshot
+        of the colormap at registration.
+
+        Parameters
+        ----------
+        cmap : matplotlib.colors.Colormap
+            The colormap to register.
+
+        name : str, optional
+            The name for the colormap. If not given, ``cmap.name`` is used.
+
+        force : bool, default: False
+            If False, a ValueError is raised if trying to overwrite an already
+            registered name. True supports overwriting registered colormaps
+            other than the builtin colormaps.
+        """
+        _api.check_isinstance(colors.Colormap, cmap=cmap)
+
+        name = name or cmap.name
+        if name in self:
+            if not force:
+                # don't allow registering an already existing cmap
+                # unless explicitly asked to
+                raise ValueError(
+                    f'A colormap named "{name}" is already registered.')
+            elif name in self._builtin_cmaps:
+                # We don't allow overriding a builtin.
+                raise ValueError("Re-registering the builtin cmap "
+                                 f"{name!r} is not allowed.")
+
+            # Warn that we are updating an already existing colormap
+            _api.warn_external(f"Overwriting the cmap {name!r} "
+                               "that was already in the registry.")
+
+        self._cmaps[name] = cmap.copy()
+        # Someone may set the extremes of a builtin colormap and want to register it
+        # with a different name for future lookups. The object would still have the
+        # builtin name, so we should update it to the registered name
+        if self._cmaps[name].name != name:
+            self._cmaps[name].name = name
+
+    def unregister(self, name):
+        """
+        Remove a colormap from the registry.
+
+        You cannot remove built-in colormaps.
+
+        If the named colormap is not registered, returns with no error, raises
+        if you try to de-register a default colormap.
+
+        .. warning::
+
+            Colormap names are currently a shared namespace that may be used
+            by multiple packages. Use `unregister` only if you know you
+            have registered that name before. In particular, do not
+            unregister just in case to clean the name before registering a
+            new colormap.
+
+        Parameters
+        ----------
+        name : str
+            The name of the colormap to be removed.
+
+        Raises
+        ------
+        ValueError
+            If you try to remove a default built-in colormap.
+        """
+        if name in self._builtin_cmaps:
+            raise ValueError(f"cannot unregister {name!r} which is a builtin "
+                             "colormap.")
+        self._cmaps.pop(name, None)
+
+    def get_cmap(self, cmap):
+        """
+        Return a color map specified through *cmap*.
+
+        Parameters
+        ----------
+        cmap : str or `~matplotlib.colors.Colormap` or None
+
+            - if a `.Colormap`, return it
+            - if a string, look it up in ``mpl.colormaps``
+            - if None, return the Colormap defined in :rc:`image.cmap`
+
+        Returns
+        -------
+        Colormap
+        """
+        # get the default color map
+        if cmap is None:
+            return self[mpl.rcParams["image.cmap"]]
+
+        # if the user passed in a Colormap, simply return it
+        if isinstance(cmap, colors.Colormap):
+            return cmap
+        if isinstance(cmap, str):
+            _api.check_in_list(sorted(_colormaps), cmap=cmap)
+            # otherwise, it must be a string so look it up
+            return self[cmap]
+        raise TypeError(
+            'get_cmap expects None or an instance of a str or Colormap . ' +
+            f'you passed {cmap!r} of type {type(cmap)}'
+        )
+
+
+# public access to the colormaps should be via `matplotlib.colormaps`. For now,
+# we still create the registry here, but that should stay an implementation
+# detail.
+_colormaps = ColormapRegistry(_gen_cmap_registry())
+globals().update(_colormaps)
+
+_multivar_colormaps = ColormapRegistry(multivar_cmaps)
+
+_bivar_colormaps = ColormapRegistry(bivar_cmaps)
+
+
+# This is an exact copy of pyplot.get_cmap(). It was removed in 3.9, but apparently
+# caused more user trouble than expected. Re-added for 3.9.1 and extended the
+# deprecation period for two additional minor releases.
+@_api.deprecated(
+    '3.7',
+    removal='3.11',
+    alternative="``matplotlib.colormaps[name]`` or ``matplotlib.colormaps.get_cmap()``"
+                " or ``pyplot.get_cmap()``"
+    )
+def get_cmap(name=None, lut=None):
+    """
+    Get a colormap instance, defaulting to rc values if *name* is None.
+
+    Parameters
+    ----------
+    name : `~matplotlib.colors.Colormap` or str or None, default: None
+        If a `.Colormap` instance, it will be returned. Otherwise, the name of
+        a colormap known to Matplotlib, which will be resampled by *lut*. The
+        default, None, means :rc:`image.cmap`.
+    lut : int or None, default: None
+        If *name* is not already a Colormap instance and *lut* is not None, the
+        colormap will be resampled to have *lut* entries in the lookup table.
+
+    Returns
+    -------
+    Colormap
+    """
+    if name is None:
+        name = mpl.rcParams['image.cmap']
+    if isinstance(name, colors.Colormap):
+        return name
+    _api.check_in_list(sorted(_colormaps), name=name)
+    if lut is None:
+        return _colormaps[name]
+    else:
+        return _colormaps[name].resampled(lut)
+
+
+def _ensure_cmap(cmap):
+    """
+    Ensure that we have a `.Colormap` object.
+
+    For internal use to preserve type stability of errors.
+
+    Parameters
+    ----------
+    cmap : None, str, Colormap
+
+        - if a `Colormap`, return it
+        - if a string, look it up in mpl.colormaps
+        - if None, look up the default color map in mpl.colormaps
+
+    Returns
+    -------
+    Colormap
+
+    """
+    if isinstance(cmap, colors.Colormap):
+        return cmap
+    cmap_name = cmap if cmap is not None else mpl.rcParams["image.cmap"]
+    # use check_in_list to ensure type stability of the exception raised by
+    # the internal usage of this (ValueError vs KeyError)
+    if cmap_name not in _colormaps:
+        _api.check_in_list(sorted(_colormaps), cmap=cmap_name)
+    return mpl.colormaps[cmap_name]
diff --git a/lib/python3.12/site-packages/matplotlib/collections.py b/lib/python3.12/site-packages/matplotlib/collections.py
new file mode 100644
index 0000000000000000000000000000000000000000..9bc25913ee0e18c77be987d5c6b2afc602155557
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/collections.py
@@ -0,0 +1,2573 @@
+"""
+Classes for the efficient drawing of large collections of objects that
+share most properties, e.g., a large number of line segments or
+polygons.
+
+The classes are not meant to be as flexible as their single element
+counterparts (e.g., you may not be able to select all line styles) but
+they are meant to be fast for common use cases (e.g., a large set of solid
+line segments).
+"""
+
+import itertools
+import functools
+import math
+from numbers import Number, Real
+import warnings
+
+import numpy as np
+
+import matplotlib as mpl
+from . import (_api, _path, artist, cbook, colorizer as mcolorizer, colors as mcolors,
+               _docstring, hatch as mhatch, lines as mlines, path as mpath, transforms)
+from ._enums import JoinStyle, CapStyle
+
+
+# "color" is excluded; it is a compound setter, and its docstring differs
+# in LineCollection.
+@_api.define_aliases({
+    "antialiased": ["antialiaseds", "aa"],
+    "edgecolor": ["edgecolors", "ec"],
+    "facecolor": ["facecolors", "fc"],
+    "linestyle": ["linestyles", "dashes", "ls"],
+    "linewidth": ["linewidths", "lw"],
+    "offset_transform": ["transOffset"],
+})
+class Collection(mcolorizer.ColorizingArtist):
+    r"""
+    Base class for Collections. Must be subclassed to be usable.
+
+    A Collection represents a sequence of `.Patch`\es that can be drawn
+    more efficiently together than individually. For example, when a single
+    path is being drawn repeatedly at different offsets, the renderer can
+    typically execute a ``draw_marker()`` call much more efficiently than a
+    series of repeated calls to ``draw_path()`` with the offsets put in
+    one-by-one.
+
+    Most properties of a collection can be configured per-element. Therefore,
+    Collections have "plural" versions of many of the properties of a `.Patch`
+    (e.g. `.Collection.get_paths` instead of `.Patch.get_path`). Exceptions are
+    the *zorder*, *hatch*, *pickradius*, *capstyle* and *joinstyle* properties,
+    which can only be set globally for the whole collection.
+
+    Besides these exceptions, all properties can be specified as single values
+    (applying to all elements) or sequences of values. The property of the
+    ``i``\th element of the collection is::
+
+      prop[i % len(prop)]
+
+    Each Collection can optionally be used as its own `.ScalarMappable` by
+    passing the *norm* and *cmap* parameters to its constructor. If the
+    Collection's `.ScalarMappable` matrix ``_A`` has been set (via a call
+    to `.Collection.set_array`), then at draw time this internal scalar
+    mappable will be used to set the ``facecolors`` and ``edgecolors``,
+    ignoring those that were manually passed in.
+    """
+    #: Either a list of 3x3 arrays or an Nx3x3 array (representing N
+    #: transforms), suitable for the `all_transforms` argument to
+    #: `~matplotlib.backend_bases.RendererBase.draw_path_collection`;
+    #: each 3x3 array is used to initialize an
+    #: `~matplotlib.transforms.Affine2D` object.
+    #: Each kind of collection defines this based on its arguments.
+    _transforms = np.empty((0, 3, 3))
+
+    # Whether to draw an edge by default.  Set on a
+    # subclass-by-subclass basis.
+    _edge_default = False
+
+    @_docstring.interpd
+    def __init__(self, *,
+                 edgecolors=None,
+                 facecolors=None,
+                 linewidths=None,
+                 linestyles='solid',
+                 capstyle=None,
+                 joinstyle=None,
+                 antialiaseds=None,
+                 offsets=None,
+                 offset_transform=None,
+                 norm=None,  # optional for ScalarMappable
+                 cmap=None,  # ditto
+                 colorizer=None,
+                 pickradius=5.0,
+                 hatch=None,
+                 urls=None,
+                 zorder=1,
+                 **kwargs
+                 ):
+        """
+        Parameters
+        ----------
+        edgecolors : :mpltype:`color` or list of colors, default: :rc:`patch.edgecolor`
+            Edge color for each patch making up the collection. The special
+            value 'face' can be passed to make the edgecolor match the
+            facecolor.
+        facecolors : :mpltype:`color` or list of colors, default: :rc:`patch.facecolor`
+            Face color for each patch making up the collection.
+        linewidths : float or list of floats, default: :rc:`patch.linewidth`
+            Line width for each patch making up the collection.
+        linestyles : str or tuple or list thereof, default: 'solid'
+            Valid strings are ['solid', 'dashed', 'dashdot', 'dotted', '-',
+            '--', '-.', ':']. Dash tuples should be of the form::
+
+                (offset, onoffseq),
+
+            where *onoffseq* is an even length tuple of on and off ink lengths
+            in points. For examples, see
+            :doc:`/gallery/lines_bars_and_markers/linestyles`.
+        capstyle : `.CapStyle`-like, default: 'butt'
+            Style to use for capping lines for all paths in the collection.
+            Allowed values are %(CapStyle)s.
+        joinstyle : `.JoinStyle`-like, default: 'round'
+            Style to use for joining lines for all paths in the collection.
+            Allowed values are %(JoinStyle)s.
+        antialiaseds : bool or list of bool, default: :rc:`patch.antialiased`
+            Whether each patch in the collection should be drawn with
+            antialiasing.
+        offsets : (float, float) or list thereof, default: (0, 0)
+            A vector by which to translate each patch after rendering (default
+            is no translation). The translation is performed in screen (pixel)
+            coordinates (i.e. after the Artist's transform is applied).
+        offset_transform : `~.Transform`, default: `.IdentityTransform`
+            A single transform which will be applied to each *offsets* vector
+            before it is used.
+        cmap, norm
+            Data normalization and colormapping parameters. See
+            `.ScalarMappable` for a detailed description.
+        hatch : str, optional
+            Hatching pattern to use in filled paths, if any. Valid strings are
+            ['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*']. See
+            :doc:`/gallery/shapes_and_collections/hatch_style_reference` for
+            the meaning of each hatch type.
+        pickradius : float, default: 5.0
+            If ``pickradius <= 0``, then `.Collection.contains` will return
+            ``True`` whenever the test point is inside of one of the polygons
+            formed by the control points of a Path in the Collection. On the
+            other hand, if it is greater than 0, then we instead check if the
+            test point is contained in a stroke of width ``2*pickradius``
+            following any of the Paths in the Collection.
+        urls : list of str, default: None
+            A URL for each patch to link to once drawn. Currently only works
+            for the SVG backend. See :doc:`/gallery/misc/hyperlinks_sgskip` for
+            examples.
+        zorder : float, default: 1
+            The drawing order, shared by all Patches in the Collection. See
+            :doc:`/gallery/misc/zorder_demo` for all defaults and examples.
+        **kwargs
+            Remaining keyword arguments will be used to set properties as
+            ``Collection.set_{key}(val)`` for each key-value pair in *kwargs*.
+        """
+
+        super().__init__(self._get_colorizer(cmap, norm, colorizer))
+        # list of un-scaled dash patterns
+        # this is needed scaling the dash pattern by linewidth
+        self._us_linestyles = [(0, None)]
+        # list of dash patterns
+        self._linestyles = [(0, None)]
+        # list of unbroadcast/scaled linewidths
+        self._us_lw = [0]
+        self._linewidths = [0]
+
+        self._gapcolor = None  # Currently only used by LineCollection.
+
+        # Flags set by _set_mappable_flags: are colors from mapping an array?
+        self._face_is_mapped = None
+        self._edge_is_mapped = None
+        self._mapped_colors = None  # calculated in update_scalarmappable
+        self._hatch_color = mcolors.to_rgba(mpl.rcParams['hatch.color'])
+        self._hatch_linewidth = mpl.rcParams['hatch.linewidth']
+        self.set_facecolor(facecolors)
+        self.set_edgecolor(edgecolors)
+        self.set_linewidth(linewidths)
+        self.set_linestyle(linestyles)
+        self.set_antialiased(antialiaseds)
+        self.set_pickradius(pickradius)
+        self.set_urls(urls)
+        self.set_hatch(hatch)
+        self.set_zorder(zorder)
+
+        if capstyle:
+            self.set_capstyle(capstyle)
+        else:
+            self._capstyle = None
+
+        if joinstyle:
+            self.set_joinstyle(joinstyle)
+        else:
+            self._joinstyle = None
+
+        if offsets is not None:
+            offsets = np.asanyarray(offsets, float)
+            # Broadcast (2,) -> (1, 2) but nothing else.
+            if offsets.shape == (2,):
+                offsets = offsets[None, :]
+
+        self._offsets = offsets
+        self._offset_transform = offset_transform
+
+        self._path_effects = None
+        self._internal_update(kwargs)
+        self._paths = None
+
+    def get_paths(self):
+        return self._paths
+
+    def set_paths(self, paths):
+        self._paths = paths
+        self.stale = True
+
+    def get_transforms(self):
+        return self._transforms
+
+    def get_offset_transform(self):
+        """Return the `.Transform` instance used by this artist offset."""
+        if self._offset_transform is None:
+            self._offset_transform = transforms.IdentityTransform()
+        elif (not isinstance(self._offset_transform, transforms.Transform)
+              and hasattr(self._offset_transform, '_as_mpl_transform')):
+            self._offset_transform = \
+                self._offset_transform._as_mpl_transform(self.axes)
+        return self._offset_transform
+
+    def set_offset_transform(self, offset_transform):
+        """
+        Set the artist offset transform.
+
+        Parameters
+        ----------
+        offset_transform : `.Transform`
+        """
+        self._offset_transform = offset_transform
+
+    def get_datalim(self, transData):
+        # Calculate the data limits and return them as a `.Bbox`.
+        #
+        # This operation depends on the transforms for the data in the
+        # collection and whether the collection has offsets:
+        #
+        # 1. offsets = None, transform child of transData: use the paths for
+        # the automatic limits (i.e. for LineCollection in streamline).
+        # 2. offsets != None: offset_transform is child of transData:
+        #
+        #    a. transform is child of transData: use the path + offset for
+        #       limits (i.e for bar).
+        #    b. transform is not a child of transData: just use the offsets
+        #       for the limits (i.e. for scatter)
+        #
+        # 3. otherwise return a null Bbox.
+
+        transform = self.get_transform()
+        offset_trf = self.get_offset_transform()
+        if not (isinstance(offset_trf, transforms.IdentityTransform)
+                or offset_trf.contains_branch(transData)):
+            # if the offsets are in some coords other than data,
+            # then don't use them for autoscaling.
+            return transforms.Bbox.null()
+
+        paths = self.get_paths()
+        if not len(paths):
+            # No paths to transform
+            return transforms.Bbox.null()
+
+        if not transform.is_affine:
+            paths = [transform.transform_path_non_affine(p) for p in paths]
+            # Don't convert transform to transform.get_affine() here because
+            # we may have transform.contains_branch(transData) but not
+            # transforms.get_affine().contains_branch(transData).  But later,
+            # be careful to only apply the affine part that remains.
+
+        offsets = self.get_offsets()
+
+        if any(transform.contains_branch_seperately(transData)):
+            # collections that are just in data units (like quiver)
+            # can properly have the axes limits set by their shape +
+            # offset.  LineCollections that have no offsets can
+            # also use this algorithm (like streamplot).
+            if isinstance(offsets, np.ma.MaskedArray):
+                offsets = offsets.filled(np.nan)
+                # get_path_collection_extents handles nan but not masked arrays
+            return mpath.get_path_collection_extents(
+                transform.get_affine() - transData, paths,
+                self.get_transforms(),
+                offset_trf.transform_non_affine(offsets),
+                offset_trf.get_affine().frozen())
+
+        # NOTE: None is the default case where no offsets were passed in
+        if self._offsets is not None:
+            # this is for collections that have their paths (shapes)
+            # in physical, axes-relative, or figure-relative units
+            # (i.e. like scatter). We can't uniquely set limits based on
+            # those shapes, so we just set the limits based on their
+            # location.
+            offsets = (offset_trf - transData).transform(offsets)
+            # note A-B means A B^{-1}
+            offsets = np.ma.masked_invalid(offsets)
+            if not offsets.mask.all():
+                bbox = transforms.Bbox.null()
+                bbox.update_from_data_xy(offsets)
+                return bbox
+        return transforms.Bbox.null()
+
+    def get_window_extent(self, renderer=None):
+        # TODO: check to ensure that this does not fail for
+        # cases other than scatter plot legend
+        return self.get_datalim(transforms.IdentityTransform())
+
+    def _prepare_points(self):
+        # Helper for drawing and hit testing.
+
+        transform = self.get_transform()
+        offset_trf = self.get_offset_transform()
+        offsets = self.get_offsets()
+        paths = self.get_paths()
+
+        if self.have_units():
+            paths = []
+            for path in self.get_paths():
+                vertices = path.vertices
+                xs, ys = vertices[:, 0], vertices[:, 1]
+                xs = self.convert_xunits(xs)
+                ys = self.convert_yunits(ys)
+                paths.append(mpath.Path(np.column_stack([xs, ys]), path.codes))
+            xs = self.convert_xunits(offsets[:, 0])
+            ys = self.convert_yunits(offsets[:, 1])
+            offsets = np.ma.column_stack([xs, ys])
+
+        if not transform.is_affine:
+            paths = [transform.transform_path_non_affine(path)
+                     for path in paths]
+            transform = transform.get_affine()
+        if not offset_trf.is_affine:
+            offsets = offset_trf.transform_non_affine(offsets)
+            # This might have changed an ndarray into a masked array.
+            offset_trf = offset_trf.get_affine()
+
+        if isinstance(offsets, np.ma.MaskedArray):
+            offsets = offsets.filled(np.nan)
+            # Changing from a masked array to nan-filled ndarray
+            # is probably most efficient at this point.
+
+        return transform, offset_trf, offsets, paths
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        if not self.get_visible():
+            return
+        renderer.open_group(self.__class__.__name__, self.get_gid())
+
+        self.update_scalarmappable()
+
+        transform, offset_trf, offsets, paths = self._prepare_points()
+
+        gc = renderer.new_gc()
+        self._set_gc_clip(gc)
+        gc.set_snap(self.get_snap())
+
+        if self._hatch:
+            gc.set_hatch(self._hatch)
+            gc.set_hatch_color(self._hatch_color)
+            gc.set_hatch_linewidth(self._hatch_linewidth)
+
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
+
+        if self.get_path_effects():
+            from matplotlib.patheffects import PathEffectRenderer
+            renderer = PathEffectRenderer(self.get_path_effects(), renderer)
+
+        # If the collection is made up of a single shape/color/stroke,
+        # it can be rendered once and blitted multiple times, using
+        # `draw_markers` rather than `draw_path_collection`.  This is
+        # *much* faster for Agg, and results in smaller file sizes in
+        # PDF/SVG/PS.
+
+        trans = self.get_transforms()
+        facecolors = self.get_facecolor()
+        edgecolors = self.get_edgecolor()
+        do_single_path_optimization = False
+        if (len(paths) == 1 and len(trans) <= 1 and
+                len(facecolors) == 1 and len(edgecolors) == 1 and
+                len(self._linewidths) == 1 and
+                all(ls[1] is None for ls in self._linestyles) and
+                len(self._antialiaseds) == 1 and len(self._urls) == 1 and
+                self.get_hatch() is None):
+            if len(trans):
+                combined_transform = transforms.Affine2D(trans[0]) + transform
+            else:
+                combined_transform = transform
+            extents = paths[0].get_extents(combined_transform)
+            if (extents.width < self.get_figure(root=True).bbox.width
+                    and extents.height < self.get_figure(root=True).bbox.height):
+                do_single_path_optimization = True
+
+        if self._joinstyle:
+            gc.set_joinstyle(self._joinstyle)
+
+        if self._capstyle:
+            gc.set_capstyle(self._capstyle)
+
+        if do_single_path_optimization:
+            gc.set_foreground(tuple(edgecolors[0]))
+            gc.set_linewidth(self._linewidths[0])
+            gc.set_dashes(*self._linestyles[0])
+            gc.set_antialiased(self._antialiaseds[0])
+            gc.set_url(self._urls[0])
+            renderer.draw_markers(
+                gc, paths[0], combined_transform.frozen(),
+                mpath.Path(offsets), offset_trf, tuple(facecolors[0]))
+        else:
+            if self._gapcolor is not None:
+                # First draw paths within the gaps.
+                ipaths, ilinestyles = self._get_inverse_paths_linestyles()
+                renderer.draw_path_collection(
+                    gc, transform.frozen(), ipaths,
+                    self.get_transforms(), offsets, offset_trf,
+                    [mcolors.to_rgba("none")], self._gapcolor,
+                    self._linewidths, ilinestyles,
+                    self._antialiaseds, self._urls,
+                    "screen")
+
+            renderer.draw_path_collection(
+                gc, transform.frozen(), paths,
+                self.get_transforms(), offsets, offset_trf,
+                self.get_facecolor(), self.get_edgecolor(),
+                self._linewidths, self._linestyles,
+                self._antialiaseds, self._urls,
+                "screen")  # offset_position, kept for backcompat.
+
+        gc.restore()
+        renderer.close_group(self.__class__.__name__)
+        self.stale = False
+
+    def set_pickradius(self, pickradius):
+        """
+        Set the pick radius used for containment tests.
+
+        Parameters
+        ----------
+        pickradius : float
+            Pick radius, in points.
+        """
+        if not isinstance(pickradius, Real):
+            raise ValueError(
+                f"pickradius must be a real-valued number, not {pickradius!r}")
+        self._pickradius = pickradius
+
+    def get_pickradius(self):
+        return self._pickradius
+
+    def contains(self, mouseevent):
+        """
+        Test whether the mouse event occurred in the collection.
+
+        Returns ``bool, dict(ind=itemlist)``, where every item in itemlist
+        contains the event.
+        """
+        if self._different_canvas(mouseevent) or not self.get_visible():
+            return False, {}
+        pickradius = (
+            float(self._picker)
+            if isinstance(self._picker, Number) and
+               self._picker is not True  # the bool, not just nonzero or 1
+            else self._pickradius)
+        if self.axes:
+            self.axes._unstale_viewLim()
+        transform, offset_trf, offsets, paths = self._prepare_points()
+        # Tests if the point is contained on one of the polygons formed
+        # by the control points of each of the paths. A point is considered
+        # "on" a path if it would lie within a stroke of width 2*pickradius
+        # following the path. If pickradius <= 0, then we instead simply check
+        # if the point is *inside* of the path instead.
+        ind = _path.point_in_path_collection(
+            mouseevent.x, mouseevent.y, pickradius,
+            transform.frozen(), paths, self.get_transforms(),
+            offsets, offset_trf, pickradius <= 0)
+        return len(ind) > 0, dict(ind=ind)
+
+    def set_urls(self, urls):
+        """
+        Parameters
+        ----------
+        urls : list of str or None
+
+        Notes
+        -----
+        URLs are currently only implemented by the SVG backend. They are
+        ignored by all other backends.
+        """
+        self._urls = urls if urls is not None else [None]
+        self.stale = True
+
+    def get_urls(self):
+        """
+        Return a list of URLs, one for each element of the collection.
+
+        The list contains *None* for elements without a URL. See
+        :doc:`/gallery/misc/hyperlinks_sgskip` for an example.
+        """
+        return self._urls
+
+    def set_hatch(self, hatch):
+        r"""
+        Set the hatching pattern
+
+        *hatch* can be one of::
+
+          /   - diagonal hatching
+          \   - back diagonal
+          |   - vertical
+          -   - horizontal
+          +   - crossed
+          x   - crossed diagonal
+          o   - small circle
+          O   - large circle
+          .   - dots
+          *   - stars
+
+        Letters can be combined, in which case all the specified
+        hatchings are done.  If same letter repeats, it increases the
+        density of hatching of that pattern.
+
+        Unlike other properties such as linewidth and colors, hatching
+        can only be specified for the collection as a whole, not separately
+        for each member.
+
+        Parameters
+        ----------
+        hatch : {'/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
+        """
+        # Use validate_hatch(list) after deprecation.
+        mhatch._validate_hatch_pattern(hatch)
+        self._hatch = hatch
+        self.stale = True
+
+    def get_hatch(self):
+        """Return the current hatching pattern."""
+        return self._hatch
+
+    def set_hatch_linewidth(self, lw):
+        """Set the hatch linewidth."""
+        self._hatch_linewidth = lw
+
+    def get_hatch_linewidth(self):
+        """Return the hatch linewidth."""
+        return self._hatch_linewidth
+
+    def set_offsets(self, offsets):
+        """
+        Set the offsets for the collection.
+
+        Parameters
+        ----------
+        offsets : (N, 2) or (2,) array-like
+        """
+        offsets = np.asanyarray(offsets)
+        if offsets.shape == (2,):  # Broadcast (2,) -> (1, 2) but nothing else.
+            offsets = offsets[None, :]
+        cstack = (np.ma.column_stack if isinstance(offsets, np.ma.MaskedArray)
+                  else np.column_stack)
+        self._offsets = cstack(
+            (np.asanyarray(self.convert_xunits(offsets[:, 0]), float),
+             np.asanyarray(self.convert_yunits(offsets[:, 1]), float)))
+        self.stale = True
+
+    def get_offsets(self):
+        """Return the offsets for the collection."""
+        # Default to zeros in the no-offset (None) case
+        return np.zeros((1, 2)) if self._offsets is None else self._offsets
+
+    def _get_default_linewidth(self):
+        # This may be overridden in a subclass.
+        return mpl.rcParams['patch.linewidth']  # validated as float
+
+    def set_linewidth(self, lw):
+        """
+        Set the linewidth(s) for the collection.  *lw* can be a scalar
+        or a sequence; if it is a sequence the patches will cycle
+        through the sequence
+
+        Parameters
+        ----------
+        lw : float or list of floats
+        """
+        if lw is None:
+            lw = self._get_default_linewidth()
+        # get the un-scaled/broadcast lw
+        self._us_lw = np.atleast_1d(lw)
+
+        # scale all of the dash patterns.
+        self._linewidths, self._linestyles = self._bcast_lwls(
+            self._us_lw, self._us_linestyles)
+        self.stale = True
+
+    def set_linestyle(self, ls):
+        """
+        Set the linestyle(s) for the collection.
+
+        ===========================   =================
+        linestyle                     description
+        ===========================   =================
+        ``'-'`` or ``'solid'``        solid line
+        ``'--'`` or  ``'dashed'``     dashed line
+        ``'-.'`` or  ``'dashdot'``    dash-dotted line
+        ``':'`` or ``'dotted'``       dotted line
+        ===========================   =================
+
+        Alternatively a dash tuple of the following form can be provided::
+
+            (offset, onoffseq),
+
+        where ``onoffseq`` is an even length tuple of on and off ink in points.
+
+        Parameters
+        ----------
+        ls : str or tuple or list thereof
+            Valid values for individual linestyles include {'-', '--', '-.',
+            ':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a
+            complete description.
+        """
+        # get the list of raw 'unscaled' dash patterns
+        self._us_linestyles = mlines._get_dash_patterns(ls)
+
+        # broadcast and scale the lw and dash patterns
+        self._linewidths, self._linestyles = self._bcast_lwls(
+            self._us_lw, self._us_linestyles)
+
+    @_docstring.interpd
+    def set_capstyle(self, cs):
+        """
+        Set the `.CapStyle` for the collection (for all its elements).
+
+        Parameters
+        ----------
+        cs : `.CapStyle` or %(CapStyle)s
+        """
+        self._capstyle = CapStyle(cs)
+
+    @_docstring.interpd
+    def get_capstyle(self):
+        """
+        Return the cap style for the collection (for all its elements).
+
+        Returns
+        -------
+        %(CapStyle)s or None
+        """
+        return self._capstyle.name if self._capstyle else None
+
+    @_docstring.interpd
+    def set_joinstyle(self, js):
+        """
+        Set the `.JoinStyle` for the collection (for all its elements).
+
+        Parameters
+        ----------
+        js : `.JoinStyle` or %(JoinStyle)s
+        """
+        self._joinstyle = JoinStyle(js)
+
+    @_docstring.interpd
+    def get_joinstyle(self):
+        """
+        Return the join style for the collection (for all its elements).
+
+        Returns
+        -------
+        %(JoinStyle)s or None
+        """
+        return self._joinstyle.name if self._joinstyle else None
+
+    @staticmethod
+    def _bcast_lwls(linewidths, dashes):
+        """
+        Internal helper function to broadcast + scale ls/lw
+
+        In the collection drawing code, the linewidth and linestyle are cycled
+        through as circular buffers (via ``v[i % len(v)]``).  Thus, if we are
+        going to scale the dash pattern at set time (not draw time) we need to
+        do the broadcasting now and expand both lists to be the same length.
+
+        Parameters
+        ----------
+        linewidths : list
+            line widths of collection
+        dashes : list
+            dash specification (offset, (dash pattern tuple))
+
+        Returns
+        -------
+        linewidths, dashes : list
+            Will be the same length, dashes are scaled by paired linewidth
+        """
+        if mpl.rcParams['_internal.classic_mode']:
+            return linewidths, dashes
+        # make sure they are the same length so we can zip them
+        if len(dashes) != len(linewidths):
+            l_dashes = len(dashes)
+            l_lw = len(linewidths)
+            gcd = math.gcd(l_dashes, l_lw)
+            dashes = list(dashes) * (l_lw // gcd)
+            linewidths = list(linewidths) * (l_dashes // gcd)
+
+        # scale the dash patterns
+        dashes = [mlines._scale_dashes(o, d, lw)
+                  for (o, d), lw in zip(dashes, linewidths)]
+
+        return linewidths, dashes
+
+    def get_antialiased(self):
+        """
+        Get the antialiasing state for rendering.
+
+        Returns
+        -------
+        array of bools
+        """
+        return self._antialiaseds
+
+    def set_antialiased(self, aa):
+        """
+        Set the antialiasing state for rendering.
+
+        Parameters
+        ----------
+        aa : bool or list of bools
+        """
+        if aa is None:
+            aa = self._get_default_antialiased()
+        self._antialiaseds = np.atleast_1d(np.asarray(aa, bool))
+        self.stale = True
+
+    def _get_default_antialiased(self):
+        # This may be overridden in a subclass.
+        return mpl.rcParams['patch.antialiased']
+
+    def set_color(self, c):
+        """
+        Set both the edgecolor and the facecolor.
+
+        Parameters
+        ----------
+        c : :mpltype:`color` or list of RGBA tuples
+
+        See Also
+        --------
+        Collection.set_facecolor, Collection.set_edgecolor
+            For setting the edge or face color individually.
+        """
+        self.set_facecolor(c)
+        self.set_edgecolor(c)
+
+    def _get_default_facecolor(self):
+        # This may be overridden in a subclass.
+        return mpl.rcParams['patch.facecolor']
+
+    def _set_facecolor(self, c):
+        if c is None:
+            c = self._get_default_facecolor()
+
+        self._facecolors = mcolors.to_rgba_array(c, self._alpha)
+        self.stale = True
+
+    def set_facecolor(self, c):
+        """
+        Set the facecolor(s) of the collection. *c* can be a color (all patches
+        have same color), or a sequence of colors; if it is a sequence the
+        patches will cycle through the sequence.
+
+        If *c* is 'none', the patch will not be filled.
+
+        Parameters
+        ----------
+        c : :mpltype:`color` or list of :mpltype:`color`
+        """
+        if isinstance(c, str) and c.lower() in ("none", "face"):
+            c = c.lower()
+        self._original_facecolor = c
+        self._set_facecolor(c)
+
+    def get_facecolor(self):
+        return self._facecolors
+
+    def get_edgecolor(self):
+        if cbook._str_equal(self._edgecolors, 'face'):
+            return self.get_facecolor()
+        else:
+            return self._edgecolors
+
+    def _get_default_edgecolor(self):
+        # This may be overridden in a subclass.
+        return mpl.rcParams['patch.edgecolor']
+
+    def _set_edgecolor(self, c):
+        set_hatch_color = True
+        if c is None:
+            if (mpl.rcParams['patch.force_edgecolor']
+                    or self._edge_default
+                    or cbook._str_equal(self._original_facecolor, 'none')):
+                c = self._get_default_edgecolor()
+            else:
+                c = 'none'
+                set_hatch_color = False
+        if cbook._str_lower_equal(c, 'face'):
+            self._edgecolors = 'face'
+            self.stale = True
+            return
+        self._edgecolors = mcolors.to_rgba_array(c, self._alpha)
+        if set_hatch_color and len(self._edgecolors):
+            self._hatch_color = tuple(self._edgecolors[0])
+        self.stale = True
+
+    def set_edgecolor(self, c):
+        """
+        Set the edgecolor(s) of the collection.
+
+        Parameters
+        ----------
+        c : :mpltype:`color` or list of :mpltype:`color` or 'face'
+            The collection edgecolor(s).  If a sequence, the patches cycle
+            through it.  If 'face', match the facecolor.
+        """
+        # We pass through a default value for use in LineCollection.
+        # This allows us to maintain None as the default indicator in
+        # _original_edgecolor.
+        if isinstance(c, str) and c.lower() in ("none", "face"):
+            c = c.lower()
+        self._original_edgecolor = c
+        self._set_edgecolor(c)
+
+    def set_alpha(self, alpha):
+        """
+        Set the transparency of the collection.
+
+        Parameters
+        ----------
+        alpha : float or array of float or None
+            If not None, *alpha* values must be between 0 and 1, inclusive.
+            If an array is provided, its length must match the number of
+            elements in the collection.  Masked values and nans are not
+            supported.
+        """
+        artist.Artist._set_alpha_for_array(self, alpha)
+        self._set_facecolor(self._original_facecolor)
+        self._set_edgecolor(self._original_edgecolor)
+
+    set_alpha.__doc__ = artist.Artist._set_alpha_for_array.__doc__
+
+    def get_linewidth(self):
+        return self._linewidths
+
+    def get_linestyle(self):
+        return self._linestyles
+
+    def _set_mappable_flags(self):
+        """
+        Determine whether edges and/or faces are color-mapped.
+
+        This is a helper for update_scalarmappable.
+        It sets Boolean flags '_edge_is_mapped' and '_face_is_mapped'.
+
+        Returns
+        -------
+        mapping_change : bool
+            True if either flag is True, or if a flag has changed.
+        """
+        # The flags are initialized to None to ensure this returns True
+        # the first time it is called.
+        edge0 = self._edge_is_mapped
+        face0 = self._face_is_mapped
+        # After returning, the flags must be Booleans, not None.
+        self._edge_is_mapped = False
+        self._face_is_mapped = False
+        if self._A is not None:
+            if not cbook._str_equal(self._original_facecolor, 'none'):
+                self._face_is_mapped = True
+                if cbook._str_equal(self._original_edgecolor, 'face'):
+                    self._edge_is_mapped = True
+            else:
+                if self._original_edgecolor is None:
+                    self._edge_is_mapped = True
+
+        mapped = self._face_is_mapped or self._edge_is_mapped
+        changed = (edge0 is None or face0 is None
+                   or self._edge_is_mapped != edge0
+                   or self._face_is_mapped != face0)
+        return mapped or changed
+
+    def update_scalarmappable(self):
+        """
+        Update colors from the scalar mappable array, if any.
+
+        Assign colors to edges and faces based on the array and/or
+        colors that were directly set, as appropriate.
+        """
+        if not self._set_mappable_flags():
+            return
+        # Allow possibility to call 'self.set_array(None)'.
+        if self._A is not None:
+            # QuadMesh can map 2d arrays (but pcolormesh supplies 1d array)
+            if self._A.ndim > 1 and not isinstance(self, _MeshData):
+                raise ValueError('Collections can only map rank 1 arrays')
+            if np.iterable(self._alpha):
+                if self._alpha.size != self._A.size:
+                    raise ValueError(
+                        f'Data array shape, {self._A.shape} '
+                        'is incompatible with alpha array shape, '
+                        f'{self._alpha.shape}. '
+                        'This can occur with the deprecated '
+                        'behavior of the "flat" shading option, '
+                        'in which a row and/or column of the data '
+                        'array is dropped.')
+                # pcolormesh, scatter, maybe others flatten their _A
+                self._alpha = self._alpha.reshape(self._A.shape)
+            self._mapped_colors = self.to_rgba(self._A, self._alpha)
+
+        if self._face_is_mapped:
+            self._facecolors = self._mapped_colors
+        else:
+            self._set_facecolor(self._original_facecolor)
+        if self._edge_is_mapped:
+            self._edgecolors = self._mapped_colors
+        else:
+            self._set_edgecolor(self._original_edgecolor)
+        self.stale = True
+
+    def get_fill(self):
+        """Return whether face is colored."""
+        return not cbook._str_lower_equal(self._original_facecolor, "none")
+
+    def update_from(self, other):
+        """Copy properties from other to self."""
+
+        artist.Artist.update_from(self, other)
+        self._antialiaseds = other._antialiaseds
+        self._mapped_colors = other._mapped_colors
+        self._edge_is_mapped = other._edge_is_mapped
+        self._original_edgecolor = other._original_edgecolor
+        self._edgecolors = other._edgecolors
+        self._face_is_mapped = other._face_is_mapped
+        self._original_facecolor = other._original_facecolor
+        self._facecolors = other._facecolors
+        self._linewidths = other._linewidths
+        self._linestyles = other._linestyles
+        self._us_linestyles = other._us_linestyles
+        self._pickradius = other._pickradius
+        self._hatch = other._hatch
+
+        # update_from for scalarmappable
+        self._A = other._A
+        self.norm = other.norm
+        self.cmap = other.cmap
+        self.stale = True
+
+
+class _CollectionWithSizes(Collection):
+    """
+    Base class for collections that have an array of sizes.
+    """
+    _factor = 1.0
+
+    def get_sizes(self):
+        """
+        Return the sizes ('areas') of the elements in the collection.
+
+        Returns
+        -------
+        array
+            The 'area' of each element.
+        """
+        return self._sizes
+
+    def set_sizes(self, sizes, dpi=72.0):
+        """
+        Set the sizes of each member of the collection.
+
+        Parameters
+        ----------
+        sizes : `numpy.ndarray` or None
+            The size to set for each element of the collection.  The
+            value is the 'area' of the element.
+        dpi : float, default: 72
+            The dpi of the canvas.
+        """
+        if sizes is None:
+            self._sizes = np.array([])
+            self._transforms = np.empty((0, 3, 3))
+        else:
+            self._sizes = np.asarray(sizes)
+            self._transforms = np.zeros((len(self._sizes), 3, 3))
+            scale = np.sqrt(self._sizes) * dpi / 72.0 * self._factor
+            self._transforms[:, 0, 0] = scale
+            self._transforms[:, 1, 1] = scale
+            self._transforms[:, 2, 2] = 1.0
+        self.stale = True
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+        super().draw(renderer)
+
+
+class PathCollection(_CollectionWithSizes):
+    r"""
+    A collection of `~.path.Path`\s, as created by e.g. `~.Axes.scatter`.
+    """
+
+    def __init__(self, paths, sizes=None, **kwargs):
+        """
+        Parameters
+        ----------
+        paths : list of `.path.Path`
+            The paths that will make up the `.Collection`.
+        sizes : array-like
+            The factor by which to scale each drawn `~.path.Path`. One unit
+            squared in the Path's data space is scaled to be ``sizes**2``
+            points when rendered.
+        **kwargs
+            Forwarded to `.Collection`.
+        """
+
+        super().__init__(**kwargs)
+        self.set_paths(paths)
+        self.set_sizes(sizes)
+        self.stale = True
+
+    def get_paths(self):
+        return self._paths
+
+    def legend_elements(self, prop="colors", num="auto",
+                        fmt=None, func=lambda x: x, **kwargs):
+        """
+        Create legend handles and labels for a PathCollection.
+
+        Each legend handle is a `.Line2D` representing the Path that was drawn,
+        and each label is a string that represents the Path.
+
+        This is useful for obtaining a legend for a `~.Axes.scatter` plot;
+        e.g.::
+
+            scatter = plt.scatter([1, 2, 3],  [4, 5, 6],  c=[7, 2, 3], num=None)
+            plt.legend(*scatter.legend_elements())
+
+        creates three legend elements, one for each color with the numerical
+        values passed to *c* as the labels.
+
+        Also see the :ref:`automatedlegendcreation` example.
+
+        Parameters
+        ----------
+        prop : {"colors", "sizes"}, default: "colors"
+            If "colors", the legend handles will show the different colors of
+            the collection. If "sizes", the legend will show the different
+            sizes. To set both, use *kwargs* to directly edit the `.Line2D`
+            properties.
+        num : int, None, "auto" (default), array-like, or `~.ticker.Locator`
+            Target number of elements to create.
+            If None, use all unique elements of the mappable array. If an
+            integer, target to use *num* elements in the normed range.
+            If *"auto"*, try to determine which option better suits the nature
+            of the data.
+            The number of created elements may slightly deviate from *num* due
+            to a `~.ticker.Locator` being used to find useful locations.
+            If a list or array, use exactly those elements for the legend.
+            Finally, a `~.ticker.Locator` can be provided.
+        fmt : str, `~matplotlib.ticker.Formatter`, or None (default)
+            The format or formatter to use for the labels. If a string must be
+            a valid input for a `.StrMethodFormatter`. If None (the default),
+            use a `.ScalarFormatter`.
+        func : function, default: ``lambda x: x``
+            Function to calculate the labels.  Often the size (or color)
+            argument to `~.Axes.scatter` will have been pre-processed by the
+            user using a function ``s = f(x)`` to make the markers visible;
+            e.g. ``size = np.log10(x)``.  Providing the inverse of this
+            function here allows that pre-processing to be inverted, so that
+            the legend labels have the correct values; e.g. ``func = lambda
+            x: 10**x``.
+        **kwargs
+            Allowed keyword arguments are *color* and *size*. E.g. it may be
+            useful to set the color of the markers if *prop="sizes"* is used;
+            similarly to set the size of the markers if *prop="colors"* is
+            used. Any further parameters are passed onto the `.Line2D`
+            instance. This may be useful to e.g. specify a different
+            *markeredgecolor* or *alpha* for the legend handles.
+
+        Returns
+        -------
+        handles : list of `.Line2D`
+            Visual representation of each element of the legend.
+        labels : list of str
+            The string labels for elements of the legend.
+        """
+        handles = []
+        labels = []
+        hasarray = self.get_array() is not None
+        if fmt is None:
+            fmt = mpl.ticker.ScalarFormatter(useOffset=False, useMathText=True)
+        elif isinstance(fmt, str):
+            fmt = mpl.ticker.StrMethodFormatter(fmt)
+        fmt.create_dummy_axis()
+
+        if prop == "colors":
+            if not hasarray:
+                warnings.warn("Collection without array used. Make sure to "
+                              "specify the values to be colormapped via the "
+                              "`c` argument.")
+                return handles, labels
+            u = np.unique(self.get_array())
+            size = kwargs.pop("size", mpl.rcParams["lines.markersize"])
+        elif prop == "sizes":
+            u = np.unique(self.get_sizes())
+            color = kwargs.pop("color", "k")
+        else:
+            raise ValueError("Valid values for `prop` are 'colors' or "
+                             f"'sizes'. You supplied '{prop}' instead.")
+
+        fu = func(u)
+        fmt.axis.set_view_interval(fu.min(), fu.max())
+        fmt.axis.set_data_interval(fu.min(), fu.max())
+        if num == "auto":
+            num = 9
+            if len(u) <= num:
+                num = None
+        if num is None:
+            values = u
+            label_values = func(values)
+        else:
+            if prop == "colors":
+                arr = self.get_array()
+            elif prop == "sizes":
+                arr = self.get_sizes()
+            if isinstance(num, mpl.ticker.Locator):
+                loc = num
+            elif np.iterable(num):
+                loc = mpl.ticker.FixedLocator(num)
+            else:
+                num = int(num)
+                loc = mpl.ticker.MaxNLocator(nbins=num, min_n_ticks=num-1,
+                                             steps=[1, 2, 2.5, 3, 5, 6, 8, 10])
+            label_values = loc.tick_values(func(arr).min(), func(arr).max())
+            cond = ((label_values >= func(arr).min()) &
+                    (label_values <= func(arr).max()))
+            label_values = label_values[cond]
+            yarr = np.linspace(arr.min(), arr.max(), 256)
+            xarr = func(yarr)
+            ix = np.argsort(xarr)
+            values = np.interp(label_values, xarr[ix], yarr[ix])
+
+        kw = {"markeredgewidth": self.get_linewidths()[0],
+              "alpha": self.get_alpha(),
+              **kwargs}
+
+        for val, lab in zip(values, label_values):
+            if prop == "colors":
+                color = self.cmap(self.norm(val))
+            elif prop == "sizes":
+                size = np.sqrt(val)
+                if np.isclose(size, 0.0):
+                    continue
+            h = mlines.Line2D([0], [0], ls="", color=color, ms=size,
+                              marker=self.get_paths()[0], **kw)
+            handles.append(h)
+            if hasattr(fmt, "set_locs"):
+                fmt.set_locs(label_values)
+            l = fmt(lab)
+            labels.append(l)
+
+        return handles, labels
+
+
+class PolyCollection(_CollectionWithSizes):
+
+    def __init__(self, verts, sizes=None, *, closed=True, **kwargs):
+        """
+        Parameters
+        ----------
+        verts : list of array-like
+            The sequence of polygons [*verts0*, *verts1*, ...] where each
+            element *verts_i* defines the vertices of polygon *i* as a 2D
+            array-like of shape (M, 2).
+        sizes : array-like, default: None
+            Squared scaling factors for the polygons. The coordinates of each
+            polygon *verts_i* are multiplied by the square-root of the
+            corresponding entry in *sizes* (i.e., *sizes* specify the scaling
+            of areas). The scaling is applied before the Artist master
+            transform.
+        closed : bool, default: True
+            Whether the polygon should be closed by adding a CLOSEPOLY
+            connection at the end.
+        **kwargs
+            Forwarded to `.Collection`.
+        """
+        super().__init__(**kwargs)
+        self.set_sizes(sizes)
+        self.set_verts(verts, closed)
+        self.stale = True
+
+    def set_verts(self, verts, closed=True):
+        """
+        Set the vertices of the polygons.
+
+        Parameters
+        ----------
+        verts : list of array-like
+            The sequence of polygons [*verts0*, *verts1*, ...] where each
+            element *verts_i* defines the vertices of polygon *i* as a 2D
+            array-like of shape (M, 2).
+        closed : bool, default: True
+            Whether the polygon should be closed by adding a CLOSEPOLY
+            connection at the end.
+        """
+        self.stale = True
+        if isinstance(verts, np.ma.MaskedArray):
+            verts = verts.astype(float).filled(np.nan)
+
+        # No need to do anything fancy if the path isn't closed.
+        if not closed:
+            self._paths = [mpath.Path(xy) for xy in verts]
+            return
+
+        # Fast path for arrays
+        if isinstance(verts, np.ndarray) and len(verts.shape) == 3:
+            verts_pad = np.concatenate((verts, verts[:, :1]), axis=1)
+            # Creating the codes once is much faster than having Path do it
+            # separately each time by passing closed=True.
+            codes = np.empty(verts_pad.shape[1], dtype=mpath.Path.code_type)
+            codes[:] = mpath.Path.LINETO
+            codes[0] = mpath.Path.MOVETO
+            codes[-1] = mpath.Path.CLOSEPOLY
+            self._paths = [mpath.Path(xy, codes) for xy in verts_pad]
+            return
+
+        self._paths = []
+        for xy in verts:
+            if len(xy):
+                self._paths.append(mpath.Path._create_closed(xy))
+            else:
+                self._paths.append(mpath.Path(xy))
+
+    set_paths = set_verts
+
+    def set_verts_and_codes(self, verts, codes):
+        """Initialize vertices with path codes."""
+        if len(verts) != len(codes):
+            raise ValueError("'codes' must be a 1D list or array "
+                             "with the same length of 'verts'")
+        self._paths = [mpath.Path(xy, cds) if len(xy) else mpath.Path(xy)
+                       for xy, cds in zip(verts, codes)]
+        self.stale = True
+
+
+class FillBetweenPolyCollection(PolyCollection):
+    """
+    `.PolyCollection` that fills the area between two x- or y-curves.
+    """
+    def __init__(
+            self, t_direction, t, f1, f2, *,
+            where=None, interpolate=False, step=None, **kwargs):
+        """
+        Parameters
+        ----------
+        t_direction : {{'x', 'y'}}
+            The axes on which the variable lies.
+
+            - 'x': the curves are ``(t, f1)`` and ``(t, f2)``.
+            - 'y': the curves are ``(f1, t)`` and ``(f2, t)``.
+
+        t : array-like
+            The ``t_direction`` coordinates of the nodes defining the curves.
+
+        f1 : array-like or float
+            The other coordinates of the nodes defining the first curve.
+
+        f2 : array-like or float
+            The other coordinates of the nodes defining the second curve.
+
+        where : array-like of bool, optional
+            Define *where* to exclude some {dir} regions from being filled.
+            The filled regions are defined by the coordinates ``t[where]``.
+            More precisely, fill between ``t[i]`` and ``t[i+1]`` if
+            ``where[i] and where[i+1]``.  Note that this definition implies
+            that an isolated *True* value between two *False* values in *where*
+            will not result in filling.  Both sides of the *True* position
+            remain unfilled due to the adjacent *False* values.
+
+        interpolate : bool, default: False
+            This option is only relevant if *where* is used and the two curves
+            are crossing each other.
+
+            Semantically, *where* is often used for *f1* > *f2* or
+            similar.  By default, the nodes of the polygon defining the filled
+            region will only be placed at the positions in the *t* array.
+            Such a polygon cannot describe the above semantics close to the
+            intersection.  The t-sections containing the intersection are
+            simply clipped.
+
+            Setting *interpolate* to *True* will calculate the actual
+            intersection point and extend the filled region up to this point.
+
+        step : {{'pre', 'post', 'mid'}}, optional
+            Define *step* if the filling should be a step function,
+            i.e. constant in between *t*.  The value determines where the
+            step will occur:
+
+            - 'pre': The f value is continued constantly to the left from
+              every *t* position, i.e. the interval ``(t[i-1], t[i]]`` has the
+              value ``f[i]``.
+            - 'post': The y value is continued constantly to the right from
+              every *x* position, i.e. the interval ``[t[i], t[i+1])`` has the
+              value ``f[i]``.
+            - 'mid': Steps occur half-way between the *t* positions.
+
+        **kwargs
+            Forwarded to `.PolyCollection`.
+
+        See Also
+        --------
+        .Axes.fill_between, .Axes.fill_betweenx
+        """
+        self.t_direction = t_direction
+        self._interpolate = interpolate
+        self._step = step
+        verts = self._make_verts(t, f1, f2, where)
+        super().__init__(verts, **kwargs)
+
+    @staticmethod
+    def _f_dir_from_t(t_direction):
+        """The direction that is other than `t_direction`."""
+        if t_direction == "x":
+            return "y"
+        elif t_direction == "y":
+            return "x"
+        else:
+            msg = f"t_direction must be 'x' or 'y', got {t_direction!r}"
+            raise ValueError(msg)
+
+    @property
+    def _f_direction(self):
+        """The direction that is other than `self.t_direction`."""
+        return self._f_dir_from_t(self.t_direction)
+
+    def set_data(self, t, f1, f2, *, where=None):
+        """
+        Set new values for the two bounding curves.
+
+        Parameters
+        ----------
+        t : array-like
+            The ``self.t_direction`` coordinates of the nodes defining the curves.
+
+        f1 : array-like or float
+            The other coordinates of the nodes defining the first curve.
+
+        f2 : array-like or float
+            The other coordinates of the nodes defining the second curve.
+
+        where : array-like of bool, optional
+            Define *where* to exclude some {dir} regions from being filled.
+            The filled regions are defined by the coordinates ``t[where]``.
+            More precisely, fill between ``t[i]`` and ``t[i+1]`` if
+            ``where[i] and where[i+1]``.  Note that this definition implies
+            that an isolated *True* value between two *False* values in *where*
+            will not result in filling.  Both sides of the *True* position
+            remain unfilled due to the adjacent *False* values.
+
+        See Also
+        --------
+        .PolyCollection.set_verts, .Line2D.set_data
+        """
+        t, f1, f2 = self.axes._fill_between_process_units(
+            self.t_direction, self._f_direction, t, f1, f2)
+
+        verts = self._make_verts(t, f1, f2, where)
+        self.set_verts(verts)
+
+    def get_datalim(self, transData):
+        """Calculate the data limits and return them as a `.Bbox`."""
+        datalim = transforms.Bbox.null()
+        datalim.update_from_data_xy((self.get_transform() - transData).transform(
+            np.concatenate([self._bbox, [self._bbox.minpos]])))
+        return datalim
+
+    def _make_verts(self, t, f1, f2, where):
+        """
+        Make verts that can be forwarded to `.PolyCollection`.
+        """
+        self._validate_shapes(self.t_direction, self._f_direction, t, f1, f2)
+
+        where = self._get_data_mask(t, f1, f2, where)
+        t, f1, f2 = np.broadcast_arrays(np.atleast_1d(t), f1, f2, subok=True)
+
+        self._bbox = transforms.Bbox.null()
+        self._bbox.update_from_data_xy(self._fix_pts_xy_order(np.concatenate([
+            np.stack((t[where], f[where]), axis=-1) for f in (f1, f2)])))
+
+        return [
+            self._make_verts_for_region(t, f1, f2, idx0, idx1)
+            for idx0, idx1 in cbook.contiguous_regions(where)
+        ]
+
+    def _get_data_mask(self, t, f1, f2, where):
+        """
+        Return a bool array, with True at all points that should eventually be rendered.
+
+        The array is True at a point if none of the data inputs
+        *t*, *f1*, *f2* is masked and if the input *where* is true at that point.
+        """
+        if where is None:
+            where = True
+        else:
+            where = np.asarray(where, dtype=bool)
+            if where.size != t.size:
+                msg = "where size ({}) does not match {!r} size ({})".format(
+                    where.size, self.t_direction, t.size)
+                raise ValueError(msg)
+        return where & ~functools.reduce(
+            np.logical_or, map(np.ma.getmaskarray, [t, f1, f2]))
+
+    @staticmethod
+    def _validate_shapes(t_dir, f_dir, t, f1, f2):
+        """Validate that t, f1 and f2 are 1-dimensional and have the same length."""
+        names = (d + s for d, s in zip((t_dir, f_dir, f_dir), ("", "1", "2")))
+        for name, array in zip(names, [t, f1, f2]):
+            if array.ndim > 1:
+                raise ValueError(f"{name!r} is not 1-dimensional")
+            if t.size > 1 and array.size > 1 and t.size != array.size:
+                msg = "{!r} has size {}, but {!r} has an unequal size of {}".format(
+                    t_dir, t.size, name, array.size)
+                raise ValueError(msg)
+
+    def _make_verts_for_region(self, t, f1, f2, idx0, idx1):
+        """
+        Make ``verts`` for a contiguous region between ``idx0`` and ``idx1``, taking
+        into account ``step`` and ``interpolate``.
+        """
+        t_slice = t[idx0:idx1]
+        f1_slice = f1[idx0:idx1]
+        f2_slice = f2[idx0:idx1]
+        if self._step is not None:
+            step_func = cbook.STEP_LOOKUP_MAP["steps-" + self._step]
+            t_slice, f1_slice, f2_slice = step_func(t_slice, f1_slice, f2_slice)
+
+        if self._interpolate:
+            start = self._get_interpolating_points(t, f1, f2, idx0)
+            end = self._get_interpolating_points(t, f1, f2, idx1)
+        else:
+            # Handle scalar f2 (e.g. 0): the fill should go all
+            # the way down to 0 even if none of the dep1 sample points do.
+            start = t_slice[0], f2_slice[0]
+            end = t_slice[-1], f2_slice[-1]
+
+        pts = np.concatenate((
+            np.asarray([start]),
+            np.stack((t_slice, f1_slice), axis=-1),
+            np.asarray([end]),
+            np.stack((t_slice, f2_slice), axis=-1)[::-1]))
+
+        return self._fix_pts_xy_order(pts)
+
+    @classmethod
+    def _get_interpolating_points(cls, t, f1, f2, idx):
+        """Calculate interpolating points."""
+        im1 = max(idx - 1, 0)
+        t_values = t[im1:idx+1]
+        diff_values = f1[im1:idx+1] - f2[im1:idx+1]
+        f1_values = f1[im1:idx+1]
+
+        if len(diff_values) == 2:
+            if np.ma.is_masked(diff_values[1]):
+                return t[im1], f1[im1]
+            elif np.ma.is_masked(diff_values[0]):
+                return t[idx], f1[idx]
+
+        diff_root_t = cls._get_diff_root(0, diff_values, t_values)
+        diff_root_f = cls._get_diff_root(diff_root_t, t_values, f1_values)
+        return diff_root_t, diff_root_f
+
+    @staticmethod
+    def _get_diff_root(x, xp, fp):
+        """Calculate diff root."""
+        order = xp.argsort()
+        return np.interp(x, xp[order], fp[order])
+
+    def _fix_pts_xy_order(self, pts):
+        """
+        Fix pts calculation results with `self.t_direction`.
+
+        In the workflow, it is assumed that `self.t_direction` is 'x'. If this
+        is not true, we need to exchange the coordinates.
+        """
+        return pts[:, ::-1] if self.t_direction == "y" else pts
+
+
+class RegularPolyCollection(_CollectionWithSizes):
+    """A collection of n-sided regular polygons."""
+
+    _path_generator = mpath.Path.unit_regular_polygon
+    _factor = np.pi ** (-1/2)
+
+    def __init__(self,
+                 numsides,
+                 *,
+                 rotation=0,
+                 sizes=(1,),
+                 **kwargs):
+        """
+        Parameters
+        ----------
+        numsides : int
+            The number of sides of the polygon.
+        rotation : float
+            The rotation of the polygon in radians.
+        sizes : tuple of float
+            The area of the circle circumscribing the polygon in points^2.
+        **kwargs
+            Forwarded to `.Collection`.
+
+        Examples
+        --------
+        See :doc:`/gallery/event_handling/lasso_demo` for a complete example::
+
+            offsets = np.random.rand(20, 2)
+            facecolors = [cm.jet(x) for x in np.random.rand(20)]
+
+            collection = RegularPolyCollection(
+                numsides=5, # a pentagon
+                rotation=0, sizes=(50,),
+                facecolors=facecolors,
+                edgecolors=("black",),
+                linewidths=(1,),
+                offsets=offsets,
+                offset_transform=ax.transData,
+                )
+        """
+        super().__init__(**kwargs)
+        self.set_sizes(sizes)
+        self._numsides = numsides
+        self._paths = [self._path_generator(numsides)]
+        self._rotation = rotation
+        self.set_transform(transforms.IdentityTransform())
+
+    def get_numsides(self):
+        return self._numsides
+
+    def get_rotation(self):
+        return self._rotation
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+        self._transforms = [
+            transforms.Affine2D(x).rotate(-self._rotation).get_matrix()
+            for x in self._transforms
+        ]
+        # Explicitly not super().draw, because set_sizes must be called before
+        # updating self._transforms.
+        Collection.draw(self, renderer)
+
+
+class StarPolygonCollection(RegularPolyCollection):
+    """Draw a collection of regular stars with *numsides* points."""
+    _path_generator = mpath.Path.unit_regular_star
+
+
+class AsteriskPolygonCollection(RegularPolyCollection):
+    """Draw a collection of regular asterisks with *numsides* points."""
+    _path_generator = mpath.Path.unit_regular_asterisk
+
+
+class LineCollection(Collection):
+    r"""
+    Represents a sequence of `.Line2D`\s that should be drawn together.
+
+    This class extends `.Collection` to represent a sequence of
+    `.Line2D`\s instead of just a sequence of `.Patch`\s.
+    Just as in `.Collection`, each property of a *LineCollection* may be either
+    a single value or a list of values. This list is then used cyclically for
+    each element of the LineCollection, so the property of the ``i``\th element
+    of the collection is::
+
+      prop[i % len(prop)]
+
+    The properties of each member of a *LineCollection* default to their values
+    in :rc:`lines.*` instead of :rc:`patch.*`, and the property *colors* is
+    added in place of *edgecolors*.
+    """
+
+    _edge_default = True
+
+    def __init__(self, segments,  # Can be None.
+                 *,
+                 zorder=2,        # Collection.zorder is 1
+                 **kwargs
+                 ):
+        """
+        Parameters
+        ----------
+        segments : list of (N, 2) array-like
+            A sequence ``[line0, line1, ...]`` where each line is a (N, 2)-shape
+            array-like containing points::
+
+                line0 = [(x0, y0), (x1, y1), ...]
+
+            Each line can contain a different number of points.
+        linewidths : float or list of float, default: :rc:`lines.linewidth`
+            The width of each line in points.
+        colors : :mpltype:`color` or list of color, default: :rc:`lines.color`
+            A sequence of RGBA tuples (e.g., arbitrary color strings, etc, not
+            allowed).
+        antialiaseds : bool or list of bool, default: :rc:`lines.antialiased`
+            Whether to use antialiasing for each line.
+        zorder : float, default: 2
+            zorder of the lines once drawn.
+
+        facecolors : :mpltype:`color` or list of :mpltype:`color`, default: 'none'
+            When setting *facecolors*, each line is interpreted as a boundary
+            for an area, implicitly closing the path from the last point to the
+            first point. The enclosed area is filled with *facecolor*.
+            In order to manually specify what should count as the "interior" of
+            each line, please use `.PathCollection` instead, where the
+            "interior" can be specified by appropriate usage of
+            `~.path.Path.CLOSEPOLY`.
+
+        **kwargs
+            Forwarded to `.Collection`.
+        """
+        # Unfortunately, mplot3d needs this explicit setting of 'facecolors'.
+        kwargs.setdefault('facecolors', 'none')
+        super().__init__(
+            zorder=zorder,
+            **kwargs)
+        self.set_segments(segments)
+
+    def set_segments(self, segments):
+        if segments is None:
+            return
+
+        self._paths = [mpath.Path(seg) if isinstance(seg, np.ma.MaskedArray)
+                       else mpath.Path(np.asarray(seg, float))
+                       for seg in segments]
+        self.stale = True
+
+    set_verts = set_segments  # for compatibility with PolyCollection
+    set_paths = set_segments
+
+    def get_segments(self):
+        """
+        Returns
+        -------
+        list
+            List of segments in the LineCollection. Each list item contains an
+            array of vertices.
+        """
+        segments = []
+
+        for path in self._paths:
+            vertices = [
+                vertex
+                for vertex, _
+                # Never simplify here, we want to get the data-space values
+                # back and there in no way to know the "right" simplification
+                # threshold so never try.
+                in path.iter_segments(simplify=False)
+            ]
+            vertices = np.asarray(vertices)
+            segments.append(vertices)
+
+        return segments
+
+    def _get_default_linewidth(self):
+        return mpl.rcParams['lines.linewidth']
+
+    def _get_default_antialiased(self):
+        return mpl.rcParams['lines.antialiased']
+
+    def _get_default_edgecolor(self):
+        return mpl.rcParams['lines.color']
+
+    def _get_default_facecolor(self):
+        return 'none'
+
+    def set_alpha(self, alpha):
+        # docstring inherited
+        super().set_alpha(alpha)
+        if self._gapcolor is not None:
+            self.set_gapcolor(self._original_gapcolor)
+
+    def set_color(self, c):
+        """
+        Set the edgecolor(s) of the LineCollection.
+
+        Parameters
+        ----------
+        c : :mpltype:`color` or list of :mpltype:`color`
+            Single color (all lines have same color), or a
+            sequence of RGBA tuples; if it is a sequence the lines will
+            cycle through the sequence.
+        """
+        self.set_edgecolor(c)
+
+    set_colors = set_color
+
+    def get_color(self):
+        return self._edgecolors
+
+    get_colors = get_color  # for compatibility with old versions
+
+    def set_gapcolor(self, gapcolor):
+        """
+        Set a color to fill the gaps in the dashed line style.
+
+        .. note::
+
+            Striped lines are created by drawing two interleaved dashed lines.
+            There can be overlaps between those two, which may result in
+            artifacts when using transparency.
+
+            This functionality is experimental and may change.
+
+        Parameters
+        ----------
+        gapcolor : :mpltype:`color` or list of :mpltype:`color` or None
+            The color with which to fill the gaps. If None, the gaps are
+            unfilled.
+        """
+        self._original_gapcolor = gapcolor
+        self._set_gapcolor(gapcolor)
+
+    def _set_gapcolor(self, gapcolor):
+        if gapcolor is not None:
+            gapcolor = mcolors.to_rgba_array(gapcolor, self._alpha)
+        self._gapcolor = gapcolor
+        self.stale = True
+
+    def get_gapcolor(self):
+        return self._gapcolor
+
+    def _get_inverse_paths_linestyles(self):
+        """
+        Returns the path and pattern for the gaps in the non-solid lines.
+
+        This path and pattern is the inverse of the path and pattern used to
+        construct the non-solid lines. For solid lines, we set the inverse path
+        to nans to prevent drawing an inverse line.
+        """
+        path_patterns = [
+            (mpath.Path(np.full((1, 2), np.nan)), ls)
+            if ls == (0, None) else
+            (path, mlines._get_inverse_dash_pattern(*ls))
+            for (path, ls) in
+            zip(self._paths, itertools.cycle(self._linestyles))]
+
+        return zip(*path_patterns)
+
+
+class EventCollection(LineCollection):
+    """
+    A collection of locations along a single axis at which an "event" occurred.
+
+    The events are given by a 1-dimensional array. They do not have an
+    amplitude and are displayed as parallel lines.
+    """
+
+    _edge_default = True
+
+    def __init__(self,
+                 positions,  # Cannot be None.
+                 orientation='horizontal',
+                 *,
+                 lineoffset=0,
+                 linelength=1,
+                 linewidth=None,
+                 color=None,
+                 linestyle='solid',
+                 antialiased=None,
+                 **kwargs
+                 ):
+        """
+        Parameters
+        ----------
+        positions : 1D array-like
+            Each value is an event.
+        orientation : {'horizontal', 'vertical'}, default: 'horizontal'
+            The sequence of events is plotted along this direction.
+            The marker lines of the single events are along the orthogonal
+            direction.
+        lineoffset : float, default: 0
+            The offset of the center of the markers from the origin, in the
+            direction orthogonal to *orientation*.
+        linelength : float, default: 1
+            The total height of the marker (i.e. the marker stretches from
+            ``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
+        linewidth : float or list thereof, default: :rc:`lines.linewidth`
+            The line width of the event lines, in points.
+        color : :mpltype:`color` or list of :mpltype:`color`, default: :rc:`lines.color`
+            The color of the event lines.
+        linestyle : str or tuple or list thereof, default: 'solid'
+            Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
+            '-', '--', '-.', ':']. Dash tuples should be of the form::
+
+                (offset, onoffseq),
+
+            where *onoffseq* is an even length tuple of on and off ink
+            in points.
+        antialiased : bool or list thereof, default: :rc:`lines.antialiased`
+            Whether to use antialiasing for drawing the lines.
+        **kwargs
+            Forwarded to `.LineCollection`.
+
+        Examples
+        --------
+        .. plot:: gallery/lines_bars_and_markers/eventcollection_demo.py
+        """
+        super().__init__([],
+                         linewidths=linewidth, linestyles=linestyle,
+                         colors=color, antialiaseds=antialiased,
+                         **kwargs)
+        self._is_horizontal = True  # Initial value, may be switched below.
+        self._linelength = linelength
+        self._lineoffset = lineoffset
+        self.set_orientation(orientation)
+        self.set_positions(positions)
+
+    def get_positions(self):
+        """
+        Return an array containing the floating-point values of the positions.
+        """
+        pos = 0 if self.is_horizontal() else 1
+        return [segment[0, pos] for segment in self.get_segments()]
+
+    def set_positions(self, positions):
+        """Set the positions of the events."""
+        if positions is None:
+            positions = []
+        if np.ndim(positions) != 1:
+            raise ValueError('positions must be one-dimensional')
+        lineoffset = self.get_lineoffset()
+        linelength = self.get_linelength()
+        pos_idx = 0 if self.is_horizontal() else 1
+        segments = np.empty((len(positions), 2, 2))
+        segments[:, :, pos_idx] = np.sort(positions)[:, None]
+        segments[:, 0, 1 - pos_idx] = lineoffset + linelength / 2
+        segments[:, 1, 1 - pos_idx] = lineoffset - linelength / 2
+        self.set_segments(segments)
+
+    def add_positions(self, position):
+        """Add one or more events at the specified positions."""
+        if position is None or (hasattr(position, 'len') and
+                                len(position) == 0):
+            return
+        positions = self.get_positions()
+        positions = np.hstack([positions, np.asanyarray(position)])
+        self.set_positions(positions)
+    extend_positions = append_positions = add_positions
+
+    def is_horizontal(self):
+        """True if the eventcollection is horizontal, False if vertical."""
+        return self._is_horizontal
+
+    def get_orientation(self):
+        """
+        Return the orientation of the event line ('horizontal' or 'vertical').
+        """
+        return 'horizontal' if self.is_horizontal() else 'vertical'
+
+    def switch_orientation(self):
+        """
+        Switch the orientation of the event line, either from vertical to
+        horizontal or vice versus.
+        """
+        segments = self.get_segments()
+        for i, segment in enumerate(segments):
+            segments[i] = np.fliplr(segment)
+        self.set_segments(segments)
+        self._is_horizontal = not self.is_horizontal()
+        self.stale = True
+
+    def set_orientation(self, orientation):
+        """
+        Set the orientation of the event line.
+
+        Parameters
+        ----------
+        orientation : {'horizontal', 'vertical'}
+        """
+        is_horizontal = _api.check_getitem(
+            {"horizontal": True, "vertical": False},
+            orientation=orientation)
+        if is_horizontal == self.is_horizontal():
+            return
+        self.switch_orientation()
+
+    def get_linelength(self):
+        """Return the length of the lines used to mark each event."""
+        return self._linelength
+
+    def set_linelength(self, linelength):
+        """Set the length of the lines used to mark each event."""
+        if linelength == self.get_linelength():
+            return
+        lineoffset = self.get_lineoffset()
+        segments = self.get_segments()
+        pos = 1 if self.is_horizontal() else 0
+        for segment in segments:
+            segment[0, pos] = lineoffset + linelength / 2.
+            segment[1, pos] = lineoffset - linelength / 2.
+        self.set_segments(segments)
+        self._linelength = linelength
+
+    def get_lineoffset(self):
+        """Return the offset of the lines used to mark each event."""
+        return self._lineoffset
+
+    def set_lineoffset(self, lineoffset):
+        """Set the offset of the lines used to mark each event."""
+        if lineoffset == self.get_lineoffset():
+            return
+        linelength = self.get_linelength()
+        segments = self.get_segments()
+        pos = 1 if self.is_horizontal() else 0
+        for segment in segments:
+            segment[0, pos] = lineoffset + linelength / 2.
+            segment[1, pos] = lineoffset - linelength / 2.
+        self.set_segments(segments)
+        self._lineoffset = lineoffset
+
+    def get_linewidth(self):
+        """Get the width of the lines used to mark each event."""
+        return super().get_linewidth()[0]
+
+    def get_linewidths(self):
+        return super().get_linewidth()
+
+    def get_color(self):
+        """Return the color of the lines used to mark each event."""
+        return self.get_colors()[0]
+
+
+class CircleCollection(_CollectionWithSizes):
+    """A collection of circles, drawn using splines."""
+
+    _factor = np.pi ** (-1/2)
+
+    def __init__(self, sizes, **kwargs):
+        """
+        Parameters
+        ----------
+        sizes : float or array-like
+            The area of each circle in points^2.
+        **kwargs
+            Forwarded to `.Collection`.
+        """
+        super().__init__(**kwargs)
+        self.set_sizes(sizes)
+        self.set_transform(transforms.IdentityTransform())
+        self._paths = [mpath.Path.unit_circle()]
+
+
+class EllipseCollection(Collection):
+    """A collection of ellipses, drawn using splines."""
+
+    def __init__(self, widths, heights, angles, *, units='points', **kwargs):
+        """
+        Parameters
+        ----------
+        widths : array-like
+            The lengths of the first axes (e.g., major axis lengths).
+        heights : array-like
+            The lengths of second axes.
+        angles : array-like
+            The angles of the first axes, degrees CCW from the x-axis.
+        units : {'points', 'inches', 'dots', 'width', 'height', 'x', 'y', 'xy'}
+            The units in which majors and minors are given; 'width' and
+            'height' refer to the dimensions of the axes, while 'x' and 'y'
+            refer to the *offsets* data units. 'xy' differs from all others in
+            that the angle as plotted varies with the aspect ratio, and equals
+            the specified angle only when the aspect ratio is unity.  Hence
+            it behaves the same as the `~.patches.Ellipse` with
+            ``axes.transData`` as its transform.
+        **kwargs
+            Forwarded to `Collection`.
+        """
+        super().__init__(**kwargs)
+        self.set_widths(widths)
+        self.set_heights(heights)
+        self.set_angles(angles)
+        self._units = units
+        self.set_transform(transforms.IdentityTransform())
+        self._transforms = np.empty((0, 3, 3))
+        self._paths = [mpath.Path.unit_circle()]
+
+    def _set_transforms(self):
+        """Calculate transforms immediately before drawing."""
+
+        ax = self.axes
+        fig = self.get_figure(root=False)
+
+        if self._units == 'xy':
+            sc = 1
+        elif self._units == 'x':
+            sc = ax.bbox.width / ax.viewLim.width
+        elif self._units == 'y':
+            sc = ax.bbox.height / ax.viewLim.height
+        elif self._units == 'inches':
+            sc = fig.dpi
+        elif self._units == 'points':
+            sc = fig.dpi / 72.0
+        elif self._units == 'width':
+            sc = ax.bbox.width
+        elif self._units == 'height':
+            sc = ax.bbox.height
+        elif self._units == 'dots':
+            sc = 1.0
+        else:
+            raise ValueError(f'Unrecognized units: {self._units!r}')
+
+        self._transforms = np.zeros((len(self._widths), 3, 3))
+        widths = self._widths * sc
+        heights = self._heights * sc
+        sin_angle = np.sin(self._angles)
+        cos_angle = np.cos(self._angles)
+        self._transforms[:, 0, 0] = widths * cos_angle
+        self._transforms[:, 0, 1] = heights * -sin_angle
+        self._transforms[:, 1, 0] = widths * sin_angle
+        self._transforms[:, 1, 1] = heights * cos_angle
+        self._transforms[:, 2, 2] = 1.0
+
+        _affine = transforms.Affine2D
+        if self._units == 'xy':
+            m = ax.transData.get_affine().get_matrix().copy()
+            m[:2, 2:] = 0
+            self.set_transform(_affine(m))
+
+    def set_widths(self, widths):
+        """Set the lengths of the first axes (e.g., major axis)."""
+        self._widths = 0.5 * np.asarray(widths).ravel()
+        self.stale = True
+
+    def set_heights(self, heights):
+        """Set the lengths of second axes (e.g., minor axes)."""
+        self._heights = 0.5 * np.asarray(heights).ravel()
+        self.stale = True
+
+    def set_angles(self, angles):
+        """Set the angles of the first axes, degrees CCW from the x-axis."""
+        self._angles = np.deg2rad(angles).ravel()
+        self.stale = True
+
+    def get_widths(self):
+        """Get the lengths of the first axes (e.g., major axis)."""
+        return self._widths * 2
+
+    def get_heights(self):
+        """Set the lengths of second axes (e.g., minor axes)."""
+        return self._heights * 2
+
+    def get_angles(self):
+        """Get the angles of the first axes, degrees CCW from the x-axis."""
+        return np.rad2deg(self._angles)
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        self._set_transforms()
+        super().draw(renderer)
+
+
+class PatchCollection(Collection):
+    """
+    A generic collection of patches.
+
+    PatchCollection draws faster than a large number of equivalent individual
+    Patches. It also makes it easier to assign a colormap to a heterogeneous
+    collection of patches.
+    """
+
+    def __init__(self, patches, *, match_original=False, **kwargs):
+        """
+        Parameters
+        ----------
+        patches : list of `.Patch`
+            A sequence of Patch objects.  This list may include
+            a heterogeneous assortment of different patch types.
+
+        match_original : bool, default: False
+            If True, use the colors and linewidths of the original
+            patches.  If False, new colors may be assigned by
+            providing the standard collection arguments, facecolor,
+            edgecolor, linewidths, norm or cmap.
+
+        **kwargs
+            All other parameters are forwarded to `.Collection`.
+
+            If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*
+            are None, they default to their `.rcParams` patch setting, in
+            sequence form.
+
+        Notes
+        -----
+        The use of `~matplotlib.cm.ScalarMappable` functionality is optional.
+        If the `~matplotlib.cm.ScalarMappable` matrix ``_A`` has been set (via
+        a call to `~.ScalarMappable.set_array`), at draw time a call to scalar
+        mappable will be made to set the face colors.
+        """
+
+        if match_original:
+            def determine_facecolor(patch):
+                if patch.get_fill():
+                    return patch.get_facecolor()
+                return [0, 0, 0, 0]
+
+            kwargs['facecolors'] = [determine_facecolor(p) for p in patches]
+            kwargs['edgecolors'] = [p.get_edgecolor() for p in patches]
+            kwargs['linewidths'] = [p.get_linewidth() for p in patches]
+            kwargs['linestyles'] = [p.get_linestyle() for p in patches]
+            kwargs['antialiaseds'] = [p.get_antialiased() for p in patches]
+
+        super().__init__(**kwargs)
+
+        self.set_paths(patches)
+
+    def set_paths(self, patches):
+        paths = [p.get_transform().transform_path(p.get_path())
+                 for p in patches]
+        self._paths = paths
+
+
+class TriMesh(Collection):
+    """
+    Class for the efficient drawing of a triangular mesh using Gouraud shading.
+
+    A triangular mesh is a `~matplotlib.tri.Triangulation` object.
+    """
+    def __init__(self, triangulation, **kwargs):
+        super().__init__(**kwargs)
+        self._triangulation = triangulation
+        self._shading = 'gouraud'
+
+        self._bbox = transforms.Bbox.unit()
+
+        # Unfortunately this requires a copy, unless Triangulation
+        # was rewritten.
+        xy = np.hstack((triangulation.x.reshape(-1, 1),
+                        triangulation.y.reshape(-1, 1)))
+        self._bbox.update_from_data_xy(xy)
+
+    def get_paths(self):
+        if self._paths is None:
+            self.set_paths()
+        return self._paths
+
+    def set_paths(self):
+        self._paths = self.convert_mesh_to_paths(self._triangulation)
+
+    @staticmethod
+    def convert_mesh_to_paths(tri):
+        """
+        Convert a given mesh into a sequence of `.Path` objects.
+
+        This function is primarily of use to implementers of backends that do
+        not directly support meshes.
+        """
+        triangles = tri.get_masked_triangles()
+        verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1)
+        return [mpath.Path(x) for x in verts]
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        if not self.get_visible():
+            return
+        renderer.open_group(self.__class__.__name__, gid=self.get_gid())
+        transform = self.get_transform()
+
+        # Get a list of triangles and the color at each vertex.
+        tri = self._triangulation
+        triangles = tri.get_masked_triangles()
+
+        verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1)
+
+        self.update_scalarmappable()
+        colors = self._facecolors[triangles]
+
+        gc = renderer.new_gc()
+        self._set_gc_clip(gc)
+        gc.set_linewidth(self.get_linewidth()[0])
+        renderer.draw_gouraud_triangles(gc, verts, colors, transform.frozen())
+        gc.restore()
+        renderer.close_group(self.__class__.__name__)
+
+
+class _MeshData:
+    r"""
+    Class for managing the two dimensional coordinates of Quadrilateral meshes
+    and the associated data with them. This class is a mixin and is intended to
+    be used with another collection that will implement the draw separately.
+
+    A quadrilateral mesh is a grid of M by N adjacent quadrilaterals that are
+    defined via a (M+1, N+1) grid of vertices. The quadrilateral (m, n) is
+    defined by the vertices ::
+
+               (m+1, n) ----------- (m+1, n+1)
+                  /                   /
+                 /                 /
+                /               /
+            (m, n) -------- (m, n+1)
+
+    The mesh need not be regular and the polygons need not be convex.
+
+    Parameters
+    ----------
+    coordinates : (M+1, N+1, 2) array-like
+        The vertices. ``coordinates[m, n]`` specifies the (x, y) coordinates
+        of vertex (m, n).
+
+    shading : {'flat', 'gouraud'}, default: 'flat'
+    """
+    def __init__(self, coordinates, *, shading='flat'):
+        _api.check_shape((None, None, 2), coordinates=coordinates)
+        self._coordinates = coordinates
+        self._shading = shading
+
+    def set_array(self, A):
+        """
+        Set the data values.
+
+        Parameters
+        ----------
+        A : array-like
+            The mesh data. Supported array shapes are:
+
+            - (M, N) or (M*N,): a mesh with scalar data. The values are mapped
+              to colors using normalization and a colormap. See parameters
+              *norm*, *cmap*, *vmin*, *vmax*.
+            - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
+            - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
+              i.e. including transparency.
+
+            If the values are provided as a 2D grid, the shape must match the
+            coordinates grid. If the values are 1D, they are reshaped to 2D.
+            M, N follow from the coordinates grid, where the coordinates grid
+            shape is (M, N) for 'gouraud' *shading* and (M+1, N+1) for 'flat'
+            shading.
+        """
+        height, width = self._coordinates.shape[0:-1]
+        if self._shading == 'flat':
+            h, w = height - 1, width - 1
+        else:
+            h, w = height, width
+        ok_shapes = [(h, w, 3), (h, w, 4), (h, w), (h * w,)]
+        if A is not None:
+            shape = np.shape(A)
+            if shape not in ok_shapes:
+                raise ValueError(
+                    f"For X ({width}) and Y ({height}) with {self._shading} "
+                    f"shading, A should have shape "
+                    f"{' or '.join(map(str, ok_shapes))}, not {A.shape}")
+        return super().set_array(A)
+
+    def get_coordinates(self):
+        """
+        Return the vertices of the mesh as an (M+1, N+1, 2) array.
+
+        M, N are the number of quadrilaterals in the rows / columns of the
+        mesh, corresponding to (M+1, N+1) vertices.
+        The last dimension specifies the components (x, y).
+        """
+        return self._coordinates
+
+    def get_edgecolor(self):
+        # docstring inherited
+        # Note that we want to return an array of shape (N*M, 4)
+        # a flattened RGBA collection
+        return super().get_edgecolor().reshape(-1, 4)
+
+    def get_facecolor(self):
+        # docstring inherited
+        # Note that we want to return an array of shape (N*M, 4)
+        # a flattened RGBA collection
+        return super().get_facecolor().reshape(-1, 4)
+
+    @staticmethod
+    def _convert_mesh_to_paths(coordinates):
+        """
+        Convert a given mesh into a sequence of `.Path` objects.
+
+        This function is primarily of use to implementers of backends that do
+        not directly support quadmeshes.
+        """
+        if isinstance(coordinates, np.ma.MaskedArray):
+            c = coordinates.data
+        else:
+            c = coordinates
+        points = np.concatenate([
+            c[:-1, :-1],
+            c[:-1, 1:],
+            c[1:, 1:],
+            c[1:, :-1],
+            c[:-1, :-1]
+        ], axis=2).reshape((-1, 5, 2))
+        return [mpath.Path(x) for x in points]
+
+    def _convert_mesh_to_triangles(self, coordinates):
+        """
+        Convert a given mesh into a sequence of triangles, each point
+        with its own color.  The result can be used to construct a call to
+        `~.RendererBase.draw_gouraud_triangles`.
+        """
+        if isinstance(coordinates, np.ma.MaskedArray):
+            p = coordinates.data
+        else:
+            p = coordinates
+
+        p_a = p[:-1, :-1]
+        p_b = p[:-1, 1:]
+        p_c = p[1:, 1:]
+        p_d = p[1:, :-1]
+        p_center = (p_a + p_b + p_c + p_d) / 4.0
+        triangles = np.concatenate([
+            p_a, p_b, p_center,
+            p_b, p_c, p_center,
+            p_c, p_d, p_center,
+            p_d, p_a, p_center,
+        ], axis=2).reshape((-1, 3, 2))
+
+        c = self.get_facecolor().reshape((*coordinates.shape[:2], 4))
+        z = self.get_array()
+        mask = z.mask if np.ma.is_masked(z) else None
+        if mask is not None:
+            c[mask, 3] = np.nan
+        c_a = c[:-1, :-1]
+        c_b = c[:-1, 1:]
+        c_c = c[1:, 1:]
+        c_d = c[1:, :-1]
+        c_center = (c_a + c_b + c_c + c_d) / 4.0
+        colors = np.concatenate([
+            c_a, c_b, c_center,
+            c_b, c_c, c_center,
+            c_c, c_d, c_center,
+            c_d, c_a, c_center,
+        ], axis=2).reshape((-1, 3, 4))
+        tmask = np.isnan(colors[..., 2, 3])
+        return triangles[~tmask], colors[~tmask]
+
+
+class QuadMesh(_MeshData, Collection):
+    r"""
+    Class for the efficient drawing of a quadrilateral mesh.
+
+    A quadrilateral mesh is a grid of M by N adjacent quadrilaterals that are
+    defined via a (M+1, N+1) grid of vertices. The quadrilateral (m, n) is
+    defined by the vertices ::
+
+               (m+1, n) ----------- (m+1, n+1)
+                  /                   /
+                 /                 /
+                /               /
+            (m, n) -------- (m, n+1)
+
+    The mesh need not be regular and the polygons need not be convex.
+
+    Parameters
+    ----------
+    coordinates : (M+1, N+1, 2) array-like
+        The vertices. ``coordinates[m, n]`` specifies the (x, y) coordinates
+        of vertex (m, n).
+
+    antialiased : bool, default: True
+
+    shading : {'flat', 'gouraud'}, default: 'flat'
+
+    Notes
+    -----
+    Unlike other `.Collection`\s, the default *pickradius* of `.QuadMesh` is 0,
+    i.e. `~.Artist.contains` checks whether the test point is within any of the
+    mesh quadrilaterals.
+
+    """
+
+    def __init__(self, coordinates, *, antialiased=True, shading='flat',
+                 **kwargs):
+        kwargs.setdefault("pickradius", 0)
+        super().__init__(coordinates=coordinates, shading=shading)
+        Collection.__init__(self, **kwargs)
+
+        self._antialiased = antialiased
+        self._bbox = transforms.Bbox.unit()
+        self._bbox.update_from_data_xy(self._coordinates.reshape(-1, 2))
+        self.set_mouseover(False)
+
+    def get_paths(self):
+        if self._paths is None:
+            self.set_paths()
+        return self._paths
+
+    def set_paths(self):
+        self._paths = self._convert_mesh_to_paths(self._coordinates)
+        self.stale = True
+
+    def get_datalim(self, transData):
+        return (self.get_transform() - transData).transform_bbox(self._bbox)
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        if not self.get_visible():
+            return
+        renderer.open_group(self.__class__.__name__, self.get_gid())
+        transform = self.get_transform()
+        offset_trf = self.get_offset_transform()
+        offsets = self.get_offsets()
+
+        if self.have_units():
+            xs = self.convert_xunits(offsets[:, 0])
+            ys = self.convert_yunits(offsets[:, 1])
+            offsets = np.column_stack([xs, ys])
+
+        self.update_scalarmappable()
+
+        if not transform.is_affine:
+            coordinates = self._coordinates.reshape((-1, 2))
+            coordinates = transform.transform(coordinates)
+            coordinates = coordinates.reshape(self._coordinates.shape)
+            transform = transforms.IdentityTransform()
+        else:
+            coordinates = self._coordinates
+
+        if not offset_trf.is_affine:
+            offsets = offset_trf.transform_non_affine(offsets)
+            offset_trf = offset_trf.get_affine()
+
+        gc = renderer.new_gc()
+        gc.set_snap(self.get_snap())
+        self._set_gc_clip(gc)
+        gc.set_linewidth(self.get_linewidth()[0])
+
+        if self._shading == 'gouraud':
+            triangles, colors = self._convert_mesh_to_triangles(coordinates)
+            renderer.draw_gouraud_triangles(
+                gc, triangles, colors, transform.frozen())
+        else:
+            renderer.draw_quad_mesh(
+                gc, transform.frozen(),
+                coordinates.shape[1] - 1, coordinates.shape[0] - 1,
+                coordinates, offsets, offset_trf,
+                # Backends expect flattened rgba arrays (n*m, 4) for fc and ec
+                self.get_facecolor().reshape((-1, 4)),
+                self._antialiased, self.get_edgecolors().reshape((-1, 4)))
+        gc.restore()
+        renderer.close_group(self.__class__.__name__)
+        self.stale = False
+
+    def get_cursor_data(self, event):
+        contained, info = self.contains(event)
+        if contained and self.get_array() is not None:
+            return self.get_array().ravel()[info["ind"]]
+        return None
+
+
+class PolyQuadMesh(_MeshData, PolyCollection):
+    """
+    Class for drawing a quadrilateral mesh as individual Polygons.
+
+    A quadrilateral mesh is a grid of M by N adjacent quadrilaterals that are
+    defined via a (M+1, N+1) grid of vertices. The quadrilateral (m, n) is
+    defined by the vertices ::
+
+               (m+1, n) ----------- (m+1, n+1)
+                  /                   /
+                 /                 /
+                /               /
+            (m, n) -------- (m, n+1)
+
+    The mesh need not be regular and the polygons need not be convex.
+
+    Parameters
+    ----------
+    coordinates : (M+1, N+1, 2) array-like
+        The vertices. ``coordinates[m, n]`` specifies the (x, y) coordinates
+        of vertex (m, n).
+
+    Notes
+    -----
+    Unlike `.QuadMesh`, this class will draw each cell as an individual Polygon.
+    This is significantly slower, but allows for more flexibility when wanting
+    to add additional properties to the cells, such as hatching.
+
+    Another difference from `.QuadMesh` is that if any of the vertices or data
+    of a cell are masked, that Polygon will **not** be drawn and it won't be in
+    the list of paths returned.
+    """
+
+    def __init__(self, coordinates, **kwargs):
+        super().__init__(coordinates=coordinates)
+        PolyCollection.__init__(self, verts=[], **kwargs)
+        # Setting the verts updates the paths of the PolyCollection
+        # This is called after the initializers to make sure the kwargs
+        # have all been processed and available for the masking calculations
+        self._set_unmasked_verts()
+
+    def _get_unmasked_polys(self):
+        """Get the unmasked regions using the coordinates and array"""
+        # mask(X) | mask(Y)
+        mask = np.any(np.ma.getmaskarray(self._coordinates), axis=-1)
+
+        # We want the shape of the polygon, which is the corner of each X/Y array
+        mask = (mask[0:-1, 0:-1] | mask[1:, 1:] | mask[0:-1, 1:] | mask[1:, 0:-1])
+        arr = self.get_array()
+        if arr is not None:
+            arr = np.ma.getmaskarray(arr)
+            if arr.ndim == 3:
+                # RGB(A) case
+                mask |= np.any(arr, axis=-1)
+            elif arr.ndim == 2:
+                mask |= arr
+            else:
+                mask |= arr.reshape(self._coordinates[:-1, :-1, :].shape[:2])
+        return ~mask
+
+    def _set_unmasked_verts(self):
+        X = self._coordinates[..., 0]
+        Y = self._coordinates[..., 1]
+
+        unmask = self._get_unmasked_polys()
+        X1 = np.ma.filled(X[:-1, :-1])[unmask]
+        Y1 = np.ma.filled(Y[:-1, :-1])[unmask]
+        X2 = np.ma.filled(X[1:, :-1])[unmask]
+        Y2 = np.ma.filled(Y[1:, :-1])[unmask]
+        X3 = np.ma.filled(X[1:, 1:])[unmask]
+        Y3 = np.ma.filled(Y[1:, 1:])[unmask]
+        X4 = np.ma.filled(X[:-1, 1:])[unmask]
+        Y4 = np.ma.filled(Y[:-1, 1:])[unmask]
+        npoly = len(X1)
+
+        xy = np.ma.stack([X1, Y1, X2, Y2, X3, Y3, X4, Y4, X1, Y1], axis=-1)
+        verts = xy.reshape((npoly, 5, 2))
+        self.set_verts(verts)
+
+    def get_edgecolor(self):
+        # docstring inherited
+        # We only want to return the facecolors of the polygons
+        # that were drawn.
+        ec = super().get_edgecolor()
+        unmasked_polys = self._get_unmasked_polys().ravel()
+        if len(ec) != len(unmasked_polys):
+            # Mapping is off
+            return ec
+        return ec[unmasked_polys, :]
+
+    def get_facecolor(self):
+        # docstring inherited
+        # We only want to return the facecolors of the polygons
+        # that were drawn.
+        fc = super().get_facecolor()
+        unmasked_polys = self._get_unmasked_polys().ravel()
+        if len(fc) != len(unmasked_polys):
+            # Mapping is off
+            return fc
+        return fc[unmasked_polys, :]
+
+    def set_array(self, A):
+        # docstring inherited
+        prev_unmask = self._get_unmasked_polys()
+        super().set_array(A)
+        # If the mask has changed at all we need to update
+        # the set of Polys that we are drawing
+        if not np.array_equal(prev_unmask, self._get_unmasked_polys()):
+            self._set_unmasked_verts()
diff --git a/lib/python3.12/site-packages/matplotlib/colorbar.pyi b/lib/python3.12/site-packages/matplotlib/colorbar.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..07467ca74f3d5a528f8c1c0859fc25a2eb285664
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/colorbar.pyi
@@ -0,0 +1,139 @@
+import matplotlib.spines as mspines
+from matplotlib import cm, collections, colors, contour, colorizer
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.backend_bases import RendererBase
+from matplotlib.patches import Patch
+from matplotlib.ticker import Locator, Formatter
+from matplotlib.transforms import Bbox
+
+import numpy as np
+from numpy.typing import ArrayLike
+from collections.abc import Sequence
+from typing import Any, Literal, overload
+from .typing import ColorType
+
+class _ColorbarSpine(mspines.Spines):
+    def __init__(self, axes: Axes): ...
+    def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox:...
+    def set_xy(self, xy: ArrayLike) -> None: ...
+    def draw(self, renderer: RendererBase | None) -> None:...
+
+
+class Colorbar:
+    n_rasterize: int
+    mappable: cm.ScalarMappable | colorizer.ColorizingArtist
+    ax: Axes
+    alpha: float | None
+    cmap: colors.Colormap
+    norm: colors.Normalize
+    values: Sequence[float] | None
+    boundaries: Sequence[float] | None
+    extend: Literal["neither", "both", "min", "max"]
+    spacing: Literal["uniform", "proportional"]
+    orientation: Literal["vertical", "horizontal"]
+    drawedges: bool
+    extendfrac: Literal["auto"] | float | Sequence[float] | None
+    extendrect: bool
+    solids: None | collections.QuadMesh
+    solids_patches: list[Patch]
+    lines: list[collections.LineCollection]
+    outline: _ColorbarSpine
+    dividers: collections.LineCollection
+    ticklocation: Literal["left", "right", "top", "bottom"]
+    def __init__(
+        self,
+        ax: Axes,
+        mappable: cm.ScalarMappable | colorizer.ColorizingArtist | None = ...,
+        *,
+        cmap: str | colors.Colormap | None = ...,
+        norm: colors.Normalize | None = ...,
+        alpha: float | None = ...,
+        values: Sequence[float] | None = ...,
+        boundaries: Sequence[float] | None = ...,
+        orientation: Literal["vertical", "horizontal"] | None = ...,
+        ticklocation: Literal["auto", "left", "right", "top", "bottom"] = ...,
+        extend: Literal["neither", "both", "min", "max"] | None = ...,
+        spacing: Literal["uniform", "proportional"] = ...,
+        ticks: Sequence[float] | Locator | None = ...,
+        format: str | Formatter | None = ...,
+        drawedges: bool = ...,
+        extendfrac: Literal["auto"] | float | Sequence[float] | None = ...,
+        extendrect: bool = ...,
+        label: str = ...,
+        location: Literal["left", "right", "top", "bottom"] | None = ...
+    ) -> None: ...
+    @property
+    def long_axis(self) -> Axis: ...
+    @property
+    def locator(self) -> Locator: ...
+    @locator.setter
+    def locator(self, loc: Locator) -> None: ...
+    @property
+    def minorlocator(self) -> Locator: ...
+    @minorlocator.setter
+    def minorlocator(self, loc: Locator) -> None: ...
+    @property
+    def formatter(self) -> Formatter: ...
+    @formatter.setter
+    def formatter(self, fmt: Formatter) -> None: ...
+    @property
+    def minorformatter(self) -> Formatter: ...
+    @minorformatter.setter
+    def minorformatter(self, fmt: Formatter) -> None: ...
+    def update_normal(self, mappable: cm.ScalarMappable | None = ...) -> None: ...
+    @overload
+    def add_lines(self, CS: contour.ContourSet, erase: bool = ...) -> None: ...
+    @overload
+    def add_lines(
+        self,
+        levels: ArrayLike,
+        colors: ColorType | Sequence[ColorType],
+        linewidths: float | ArrayLike,
+        erase: bool = ...,
+    ) -> None: ...
+    def update_ticks(self) -> None: ...
+    def set_ticks(
+        self,
+        ticks: Sequence[float] | Locator,
+        *,
+        labels: Sequence[str] | None = ...,
+        minor: bool = ...,
+        **kwargs
+    ) -> None: ...
+    def get_ticks(self, minor: bool = ...) -> np.ndarray: ...
+    def set_ticklabels(
+        self,
+        ticklabels: Sequence[str],
+        *,
+        minor: bool = ...,
+        **kwargs
+    ) -> None: ...
+    def minorticks_on(self) -> None: ...
+    def minorticks_off(self) -> None: ...
+    def set_label(self, label: str, *, loc: str | None = ..., **kwargs) -> None: ...
+    def set_alpha(self, alpha: float | np.ndarray) -> None: ...
+    def remove(self) -> None: ...
+    def drag_pan(self, button: Any, key: Any, x: float, y: float) -> None: ...
+
+ColorbarBase = Colorbar
+
+def make_axes(
+    parents: Axes | list[Axes] | np.ndarray,
+    location: Literal["left", "right", "top", "bottom"] | None = ...,
+    orientation: Literal["vertical", "horizontal"] | None = ...,
+    fraction: float = ...,
+    shrink: float = ...,
+    aspect: float = ...,
+    **kwargs
+) -> tuple[Axes, dict[str, Any]]: ...
+def make_axes_gridspec(
+    parent: Axes,
+    *,
+    location: Literal["left", "right", "top", "bottom"] | None = ...,
+    orientation: Literal["vertical", "horizontal"] | None = ...,
+    fraction: float = ...,
+    shrink: float = ...,
+    aspect: float = ...,
+    **kwargs
+) -> tuple[Axes, dict[str, Any]]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/colorizer.py b/lib/python3.12/site-packages/matplotlib/colorizer.py
new file mode 100644
index 0000000000000000000000000000000000000000..b4223f38980410c1929d598265cd3dab1c3cfcad
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/colorizer.py
@@ -0,0 +1,703 @@
+"""
+The Colorizer class which handles the data to color pipeline via a
+normalization and a colormap.
+
+.. admonition:: Provisional status of colorizer
+
+    The ``colorizer`` module and classes in this file are considered
+    provisional and may change at any time without a deprecation period.
+
+.. seealso::
+
+  :doc:`/gallery/color/colormap_reference` for a list of builtin colormaps.
+
+  :ref:`colormap-manipulation` for examples of how to make colormaps.
+
+  :ref:`colormaps` for an in-depth discussion of choosing colormaps.
+
+  :ref:`colormapnorms` for more details about data normalization.
+
+"""
+
+import functools
+
+import numpy as np
+from numpy import ma
+
+from matplotlib import _api, colors, cbook, scale, artist
+import matplotlib as mpl
+
+mpl._docstring.interpd.register(
+    colorizer_doc="""\
+colorizer : `~matplotlib.colorizer.Colorizer` or None, default: None
+    The Colorizer object used to map color to data. If None, a Colorizer
+    object is created from a *norm* and *cmap*.""",
+    )
+
+
+class Colorizer:
+    """
+    Data to color pipeline.
+
+    This pipeline is accessible via `.Colorizer.to_rgba` and executed via
+    the `.Colorizer.norm` and `.Colorizer.cmap` attributes.
+
+    Parameters
+    ----------
+    cmap: colorbar.Colorbar or str or None, default: None
+        The colormap used to color data.
+
+    norm: colors.Normalize or str or None, default: None
+        The normalization used to normalize the data
+    """
+    def __init__(self, cmap=None, norm=None):
+
+        self._cmap = None
+        self._set_cmap(cmap)
+
+        self._id_norm = None
+        self._norm = None
+        self.norm = norm
+
+        self.callbacks = cbook.CallbackRegistry(signals=["changed"])
+        self.colorbar = None
+
+    def _scale_norm(self, norm, vmin, vmax, A):
+        """
+        Helper for initial scaling.
+
+        Used by public functions that create a ScalarMappable and support
+        parameters *vmin*, *vmax* and *norm*. This makes sure that a *norm*
+        will take precedence over *vmin*, *vmax*.
+
+        Note that this method does not set the norm.
+        """
+        if vmin is not None or vmax is not None:
+            self.set_clim(vmin, vmax)
+            if isinstance(norm, colors.Normalize):
+                raise ValueError(
+                    "Passing a Normalize instance simultaneously with "
+                    "vmin/vmax is not supported.  Please pass vmin/vmax "
+                    "directly to the norm when creating it.")
+
+        # always resolve the autoscaling so we have concrete limits
+        # rather than deferring to draw time.
+        self.autoscale_None(A)
+
+    @property
+    def norm(self):
+        return self._norm
+
+    @norm.setter
+    def norm(self, norm):
+        _api.check_isinstance((colors.Normalize, str, None), norm=norm)
+        if norm is None:
+            norm = colors.Normalize()
+        elif isinstance(norm, str):
+            try:
+                scale_cls = scale._scale_mapping[norm]
+            except KeyError:
+                raise ValueError(
+                    "Invalid norm str name; the following values are "
+                    f"supported: {', '.join(scale._scale_mapping)}"
+                ) from None
+            norm = _auto_norm_from_scale(scale_cls)()
+
+        if norm is self.norm:
+            # We aren't updating anything
+            return
+
+        in_init = self.norm is None
+        # Remove the current callback and connect to the new one
+        if not in_init:
+            self.norm.callbacks.disconnect(self._id_norm)
+        self._norm = norm
+        self._id_norm = self.norm.callbacks.connect('changed',
+                                                    self.changed)
+        if not in_init:
+            self.changed()
+
+    def to_rgba(self, x, alpha=None, bytes=False, norm=True):
+        """
+        Return a normalized RGBA array corresponding to *x*.
+
+        In the normal case, *x* is a 1D or 2D sequence of scalars, and
+        the corresponding `~numpy.ndarray` of RGBA values will be returned,
+        based on the norm and colormap set for this Colorizer.
+
+        There is one special case, for handling images that are already
+        RGB or RGBA, such as might have been read from an image file.
+        If *x* is an `~numpy.ndarray` with 3 dimensions,
+        and the last dimension is either 3 or 4, then it will be
+        treated as an RGB or RGBA array, and no mapping will be done.
+        The array can be `~numpy.uint8`, or it can be floats with
+        values in the 0-1 range; otherwise a ValueError will be raised.
+        Any NaNs or masked elements will be set to 0 alpha.
+        If the last dimension is 3, the *alpha* kwarg (defaulting to 1)
+        will be used to fill in the transparency.  If the last dimension
+        is 4, the *alpha* kwarg is ignored; it does not
+        replace the preexisting alpha.  A ValueError will be raised
+        if the third dimension is other than 3 or 4.
+
+        In either case, if *bytes* is *False* (default), the RGBA
+        array will be floats in the 0-1 range; if it is *True*,
+        the returned RGBA array will be `~numpy.uint8` in the 0 to 255 range.
+
+        If norm is False, no normalization of the input data is
+        performed, and it is assumed to be in the range (0-1).
+
+        """
+        # First check for special case, image input:
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return self._pass_image_data(x, alpha, bytes, norm)
+
+        # Otherwise run norm -> colormap pipeline
+        x = ma.asarray(x)
+        if norm:
+            x = self.norm(x)
+        rgba = self.cmap(x, alpha=alpha, bytes=bytes)
+        return rgba
+
+    @staticmethod
+    def _pass_image_data(x, alpha=None, bytes=False, norm=True):
+        """
+        Helper function to pass ndarray of shape (...,3) or (..., 4)
+        through `to_rgba()`, see `to_rgba()` for docstring.
+        """
+        if x.shape[2] == 3:
+            if alpha is None:
+                alpha = 1
+            if x.dtype == np.uint8:
+                alpha = np.uint8(alpha * 255)
+            m, n = x.shape[:2]
+            xx = np.empty(shape=(m, n, 4), dtype=x.dtype)
+            xx[:, :, :3] = x
+            xx[:, :, 3] = alpha
+        elif x.shape[2] == 4:
+            xx = x
+        else:
+            raise ValueError("Third dimension must be 3 or 4")
+        if xx.dtype.kind == 'f':
+            # If any of R, G, B, or A is nan, set to 0
+            if np.any(nans := np.isnan(x)):
+                if x.shape[2] == 4:
+                    xx = xx.copy()
+                xx[np.any(nans, axis=2), :] = 0
+
+            if norm and (xx.max() > 1 or xx.min() < 0):
+                raise ValueError("Floating point image RGB values "
+                                 "must be in the 0..1 range.")
+            if bytes:
+                xx = (xx * 255).astype(np.uint8)
+        elif xx.dtype == np.uint8:
+            if not bytes:
+                xx = xx.astype(np.float32) / 255
+        else:
+            raise ValueError("Image RGB array must be uint8 or "
+                             "floating point; found %s" % xx.dtype)
+        # Account for any masked entries in the original array
+        # If any of R, G, B, or A are masked for an entry, we set alpha to 0
+        if np.ma.is_masked(x):
+            xx[np.any(np.ma.getmaskarray(x), axis=2), 3] = 0
+        return xx
+
+    def autoscale(self, A):
+        """
+        Autoscale the scalar limits on the norm instance using the
+        current array
+        """
+        if A is None:
+            raise TypeError('You must first set_array for mappable')
+        # If the norm's limits are updated self.changed() will be called
+        # through the callbacks attached to the norm
+        self.norm.autoscale(A)
+
+    def autoscale_None(self, A):
+        """
+        Autoscale the scalar limits on the norm instance using the
+        current array, changing only limits that are None
+        """
+        if A is None:
+            raise TypeError('You must first set_array for mappable')
+        # If the norm's limits are updated self.changed() will be called
+        # through the callbacks attached to the norm
+        self.norm.autoscale_None(A)
+
+    def _set_cmap(self, cmap):
+        """
+        Set the colormap for luminance data.
+
+        Parameters
+        ----------
+        cmap : `.Colormap` or str or None
+        """
+        # bury import to avoid circular imports
+        from matplotlib import cm
+        in_init = self._cmap is None
+        self._cmap = cm._ensure_cmap(cmap)
+        if not in_init:
+            self.changed()  # Things are not set up properly yet.
+
+    @property
+    def cmap(self):
+        return self._cmap
+
+    @cmap.setter
+    def cmap(self, cmap):
+        self._set_cmap(cmap)
+
+    def set_clim(self, vmin=None, vmax=None):
+        """
+        Set the norm limits for image scaling.
+
+        Parameters
+        ----------
+        vmin, vmax : float
+             The limits.
+
+             The limits may also be passed as a tuple (*vmin*, *vmax*) as a
+             single positional argument.
+
+             .. ACCEPTS: (vmin: float, vmax: float)
+        """
+        # If the norm's limits are updated self.changed() will be called
+        # through the callbacks attached to the norm, this causes an inconsistent
+        # state, to prevent this blocked context manager is used
+        if vmax is None:
+            try:
+                vmin, vmax = vmin
+            except (TypeError, ValueError):
+                pass
+
+        orig_vmin_vmax = self.norm.vmin, self.norm.vmax
+
+        # Blocked context manager prevents callbacks from being triggered
+        # until both vmin and vmax are updated
+        with self.norm.callbacks.blocked(signal='changed'):
+            if vmin is not None:
+                self.norm.vmin = colors._sanitize_extrema(vmin)
+            if vmax is not None:
+                self.norm.vmax = colors._sanitize_extrema(vmax)
+
+        # emit a update signal if the limits are changed
+        if orig_vmin_vmax != (self.norm.vmin, self.norm.vmax):
+            self.norm.callbacks.process('changed')
+
+    def get_clim(self):
+        """
+        Return the values (min, max) that are mapped to the colormap limits.
+        """
+        return self.norm.vmin, self.norm.vmax
+
+    def changed(self):
+        """
+        Call this whenever the mappable is changed to notify all the
+        callbackSM listeners to the 'changed' signal.
+        """
+        self.callbacks.process('changed')
+        self.stale = True
+
+    @property
+    def vmin(self):
+        return self.get_clim()[0]
+
+    @vmin.setter
+    def vmin(self, vmin):
+        self.set_clim(vmin=vmin)
+
+    @property
+    def vmax(self):
+        return self.get_clim()[1]
+
+    @vmax.setter
+    def vmax(self, vmax):
+        self.set_clim(vmax=vmax)
+
+    @property
+    def clip(self):
+        return self.norm.clip
+
+    @clip.setter
+    def clip(self, clip):
+        self.norm.clip = clip
+
+
+class _ColorizerInterface:
+    """
+    Base class that contains the interface to `Colorizer` objects from
+    a `ColorizingArtist` or `.cm.ScalarMappable`.
+
+    Note: This class only contain functions that interface the .colorizer
+    attribute. Other functions that as shared between `.ColorizingArtist`
+    and `.cm.ScalarMappable` are not included.
+    """
+    def _scale_norm(self, norm, vmin, vmax):
+        self._colorizer._scale_norm(norm, vmin, vmax, self._A)
+
+    def to_rgba(self, x, alpha=None, bytes=False, norm=True):
+        """
+        Return a normalized RGBA array corresponding to *x*.
+
+        In the normal case, *x* is a 1D or 2D sequence of scalars, and
+        the corresponding `~numpy.ndarray` of RGBA values will be returned,
+        based on the norm and colormap set for this Colorizer.
+
+        There is one special case, for handling images that are already
+        RGB or RGBA, such as might have been read from an image file.
+        If *x* is an `~numpy.ndarray` with 3 dimensions,
+        and the last dimension is either 3 or 4, then it will be
+        treated as an RGB or RGBA array, and no mapping will be done.
+        The array can be `~numpy.uint8`, or it can be floats with
+        values in the 0-1 range; otherwise a ValueError will be raised.
+        Any NaNs or masked elements will be set to 0 alpha.
+        If the last dimension is 3, the *alpha* kwarg (defaulting to 1)
+        will be used to fill in the transparency.  If the last dimension
+        is 4, the *alpha* kwarg is ignored; it does not
+        replace the preexisting alpha.  A ValueError will be raised
+        if the third dimension is other than 3 or 4.
+
+        In either case, if *bytes* is *False* (default), the RGBA
+        array will be floats in the 0-1 range; if it is *True*,
+        the returned RGBA array will be `~numpy.uint8` in the 0 to 255 range.
+
+        If norm is False, no normalization of the input data is
+        performed, and it is assumed to be in the range (0-1).
+
+        """
+        return self._colorizer.to_rgba(x, alpha=alpha, bytes=bytes, norm=norm)
+
+    def get_clim(self):
+        """
+        Return the values (min, max) that are mapped to the colormap limits.
+        """
+        return self._colorizer.get_clim()
+
+    def set_clim(self, vmin=None, vmax=None):
+        """
+        Set the norm limits for image scaling.
+
+        Parameters
+        ----------
+        vmin, vmax : float
+             The limits.
+
+             For scalar data, the limits may also be passed as a
+             tuple (*vmin*, *vmax*) as a single positional argument.
+
+             .. ACCEPTS: (vmin: float, vmax: float)
+        """
+        # If the norm's limits are updated self.changed() will be called
+        # through the callbacks attached to the norm
+        self._colorizer.set_clim(vmin, vmax)
+
+    def get_alpha(self):
+        try:
+            return super().get_alpha()
+        except AttributeError:
+            return 1
+
+    @property
+    def cmap(self):
+        return self._colorizer.cmap
+
+    @cmap.setter
+    def cmap(self, cmap):
+        self._colorizer.cmap = cmap
+
+    def get_cmap(self):
+        """Return the `.Colormap` instance."""
+        return self._colorizer.cmap
+
+    def set_cmap(self, cmap):
+        """
+        Set the colormap for luminance data.
+
+        Parameters
+        ----------
+        cmap : `.Colormap` or str or None
+        """
+        self.cmap = cmap
+
+    @property
+    def norm(self):
+        return self._colorizer.norm
+
+    @norm.setter
+    def norm(self, norm):
+        self._colorizer.norm = norm
+
+    def set_norm(self, norm):
+        """
+        Set the normalization instance.
+
+        Parameters
+        ----------
+        norm : `.Normalize` or str or None
+
+        Notes
+        -----
+        If there are any colorbars using the mappable for this norm, setting
+        the norm of the mappable will reset the norm, locator, and formatters
+        on the colorbar to default.
+        """
+        self.norm = norm
+
+    def autoscale(self):
+        """
+        Autoscale the scalar limits on the norm instance using the
+        current array
+        """
+        self._colorizer.autoscale(self._A)
+
+    def autoscale_None(self):
+        """
+        Autoscale the scalar limits on the norm instance using the
+        current array, changing only limits that are None
+        """
+        self._colorizer.autoscale_None(self._A)
+
+    @property
+    def colorbar(self):
+        """
+        The last colorbar associated with this object. May be None
+        """
+        return self._colorizer.colorbar
+
+    @colorbar.setter
+    def colorbar(self, colorbar):
+        self._colorizer.colorbar = colorbar
+
+    def _format_cursor_data_override(self, data):
+        # This function overwrites Artist.format_cursor_data(). We cannot
+        # implement cm.ScalarMappable.format_cursor_data() directly, because
+        # most cm.ScalarMappable subclasses inherit from Artist first and from
+        # cm.ScalarMappable second, so Artist.format_cursor_data would always
+        # have precedence over cm.ScalarMappable.format_cursor_data.
+
+        # Note if cm.ScalarMappable is depreciated, this functionality should be
+        # implemented as format_cursor_data() on ColorizingArtist.
+        n = self.cmap.N
+        if np.ma.getmask(data):
+            return "[]"
+        normed = self.norm(data)
+        if np.isfinite(normed):
+            if isinstance(self.norm, colors.BoundaryNorm):
+                # not an invertible normalization mapping
+                cur_idx = np.argmin(np.abs(self.norm.boundaries - data))
+                neigh_idx = max(0, cur_idx - 1)
+                # use max diff to prevent delta == 0
+                delta = np.diff(
+                    self.norm.boundaries[neigh_idx:cur_idx + 2]
+                ).max()
+            elif self.norm.vmin == self.norm.vmax:
+                # singular norms, use delta of 10% of only value
+                delta = np.abs(self.norm.vmin * .1)
+            else:
+                # Midpoints of neighboring color intervals.
+                neighbors = self.norm.inverse(
+                    (int(normed * n) + np.array([0, 1])) / n)
+                delta = abs(neighbors - data).max()
+            g_sig_digits = cbook._g_sig_digits(data, delta)
+        else:
+            g_sig_digits = 3  # Consistent with default below.
+        return f"[{data:-#.{g_sig_digits}g}]"
+
+
+class _ScalarMappable(_ColorizerInterface):
+    """
+    A mixin class to map one or multiple sets of scalar data to RGBA.
+
+    The ScalarMappable applies data normalization before returning RGBA colors from
+    the given `~matplotlib.colors.Colormap`.
+    """
+
+    # _ScalarMappable exists for compatibility with
+    # code written before the introduction of the Colorizer
+    # and ColorizingArtist classes.
+
+    # _ScalarMappable can be depreciated so that ColorizingArtist
+    # inherits directly from _ColorizerInterface.
+    # in this case, the following changes should occur:
+    # __init__() has its functionality moved to ColorizingArtist.
+    # set_array(), get_array(), _get_colorizer() and
+    # _check_exclusionary_keywords() are moved to ColorizingArtist.
+    # changed() can be removed so long as colorbar.Colorbar
+    # is changed to connect to the colorizer instead of the
+    # ScalarMappable/ColorizingArtist,
+    # otherwise changed() can be moved to ColorizingArtist.
+    def __init__(self, norm=None, cmap=None, *, colorizer=None, **kwargs):
+        """
+        Parameters
+        ----------
+        norm : `.Normalize` (or subclass thereof) or str or None
+            The normalizing object which scales data, typically into the
+            interval ``[0, 1]``.
+            If a `str`, a `.Normalize` subclass is dynamically generated based
+            on the scale with the corresponding name.
+            If *None*, *norm* defaults to a *colors.Normalize* object which
+            initializes its scaling based on the first data processed.
+        cmap : str or `~matplotlib.colors.Colormap`
+            The colormap used to map normalized data values to RGBA colors.
+        """
+        super().__init__(**kwargs)
+        self._A = None
+        self._colorizer = self._get_colorizer(colorizer=colorizer, norm=norm, cmap=cmap)
+
+        self.colorbar = None
+        self._id_colorizer = self._colorizer.callbacks.connect('changed', self.changed)
+        self.callbacks = cbook.CallbackRegistry(signals=["changed"])
+
+    def set_array(self, A):
+        """
+        Set the value array from array-like *A*.
+
+        Parameters
+        ----------
+        A : array-like or None
+            The values that are mapped to colors.
+
+            The base class `.ScalarMappable` does not make any assumptions on
+            the dimensionality and shape of the value array *A*.
+        """
+        if A is None:
+            self._A = None
+            return
+
+        A = cbook.safe_masked_invalid(A, copy=True)
+        if not np.can_cast(A.dtype, float, "same_kind"):
+            raise TypeError(f"Image data of dtype {A.dtype} cannot be "
+                            "converted to float")
+
+        self._A = A
+        if not self.norm.scaled():
+            self._colorizer.autoscale_None(A)
+
+    def get_array(self):
+        """
+        Return the array of values, that are mapped to colors.
+
+        The base class `.ScalarMappable` does not make any assumptions on
+        the dimensionality and shape of the array.
+        """
+        return self._A
+
+    def changed(self):
+        """
+        Call this whenever the mappable is changed to notify all the
+        callbackSM listeners to the 'changed' signal.
+        """
+        self.callbacks.process('changed', self)
+        self.stale = True
+
+    @staticmethod
+    def _check_exclusionary_keywords(colorizer, **kwargs):
+        """
+        Raises a ValueError if any kwarg is not None while colorizer is not None
+        """
+        if colorizer is not None:
+            if any([val is not None for val in kwargs.values()]):
+                raise ValueError("The `colorizer` keyword cannot be used simultaneously"
+                                 " with any of the following keywords: "
+                                 + ", ".join(f'`{key}`' for key in kwargs.keys()))
+
+    @staticmethod
+    def _get_colorizer(cmap, norm, colorizer):
+        if isinstance(colorizer, Colorizer):
+            _ScalarMappable._check_exclusionary_keywords(
+                Colorizer, cmap=cmap, norm=norm
+            )
+            return colorizer
+        return Colorizer(cmap, norm)
+
+# The docstrings here must be generic enough to apply to all relevant methods.
+mpl._docstring.interpd.register(
+    cmap_doc="""\
+cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
+    The Colormap instance or registered colormap name used to map scalar data
+    to colors.""",
+    norm_doc="""\
+norm : str or `~matplotlib.colors.Normalize`, optional
+    The normalization method used to scale scalar data to the [0, 1] range
+    before mapping to colors using *cmap*. By default, a linear scaling is
+    used, mapping the lowest value to 0 and the highest to 1.
+
+    If given, this can be one of the following:
+
+    - An instance of `.Normalize` or one of its subclasses
+      (see :ref:`colormapnorms`).
+    - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc.  For a
+      list of available scales, call `matplotlib.scale.get_scale_names()`.
+      In that case, a suitable `.Normalize` subclass is dynamically generated
+      and instantiated.""",
+    vmin_vmax_doc="""\
+vmin, vmax : float, optional
+    When using scalar data and no explicit *norm*, *vmin* and *vmax* define
+    the data range that the colormap covers. By default, the colormap covers
+    the complete value range of the supplied data. It is an error to use
+    *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
+    name together with *vmin*/*vmax* is acceptable).""",
+)
+
+
+class ColorizingArtist(_ScalarMappable, artist.Artist):
+    """
+    Base class for artists that make map data to color using a `.colorizer.Colorizer`.
+
+    The `.colorizer.Colorizer` applies data normalization before
+    returning RGBA colors from a `~matplotlib.colors.Colormap`.
+
+    """
+    def __init__(self, colorizer, **kwargs):
+        """
+        Parameters
+        ----------
+        colorizer : `.colorizer.Colorizer`
+        """
+        _api.check_isinstance(Colorizer, colorizer=colorizer)
+        super().__init__(colorizer=colorizer, **kwargs)
+
+    @property
+    def colorizer(self):
+        return self._colorizer
+
+    @colorizer.setter
+    def colorizer(self, cl):
+        _api.check_isinstance(Colorizer, colorizer=cl)
+        self._colorizer.callbacks.disconnect(self._id_colorizer)
+        self._colorizer = cl
+        self._id_colorizer = cl.callbacks.connect('changed', self.changed)
+
+    def _set_colorizer_check_keywords(self, colorizer, **kwargs):
+        """
+        Raises a ValueError if any kwarg is not None while colorizer is not None.
+        """
+        self._check_exclusionary_keywords(colorizer, **kwargs)
+        self.colorizer = colorizer
+
+
+def _auto_norm_from_scale(scale_cls):
+    """
+    Automatically generate a norm class from *scale_cls*.
+
+    This differs from `.colors.make_norm_from_scale` in the following points:
+
+    - This function is not a class decorator, but directly returns a norm class
+      (as if decorating `.Normalize`).
+    - The scale is automatically constructed with ``nonpositive="mask"``, if it
+      supports such a parameter, to work around the difference in defaults
+      between standard scales (which use "clip") and norms (which use "mask").
+
+    Note that ``make_norm_from_scale`` caches the generated norm classes
+    (not the instances) and reuses them for later calls.  For example,
+    ``type(_auto_norm_from_scale("log")) == LogNorm``.
+    """
+    # Actually try to construct an instance, to verify whether
+    # ``nonpositive="mask"`` is supported.
+    try:
+        norm = colors.make_norm_from_scale(
+            functools.partial(scale_cls, nonpositive="mask"))(
+            colors.Normalize)()
+    except TypeError:
+        norm = colors.make_norm_from_scale(scale_cls)(
+            colors.Normalize)()
+    return type(norm)
diff --git a/lib/python3.12/site-packages/matplotlib/container.py b/lib/python3.12/site-packages/matplotlib/container.py
new file mode 100644
index 0000000000000000000000000000000000000000..b6dd43724f34b219a7d8864542af4dbec81d89ff
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/container.py
@@ -0,0 +1,141 @@
+from matplotlib import cbook
+from matplotlib.artist import Artist
+
+
+class Container(tuple):
+    """
+    Base class for containers.
+
+    Containers are classes that collect semantically related Artists such as
+    the bars of a bar plot.
+    """
+
+    def __repr__(self):
+        return f"<{type(self).__name__} object of {len(self)} artists>"
+
+    def __new__(cls, *args, **kwargs):
+        return tuple.__new__(cls, args[0])
+
+    def __init__(self, kl, label=None):
+        self._callbacks = cbook.CallbackRegistry(signals=["pchanged"])
+        self._remove_method = None
+        self._label = str(label) if label is not None else None
+
+    def remove(self):
+        for c in cbook.flatten(
+                self, scalarp=lambda x: isinstance(x, Artist)):
+            if c is not None:
+                c.remove()
+        if self._remove_method:
+            self._remove_method(self)
+
+    def get_children(self):
+        return [child for child in cbook.flatten(self) if child is not None]
+
+    get_label = Artist.get_label
+    set_label = Artist.set_label
+    add_callback = Artist.add_callback
+    remove_callback = Artist.remove_callback
+    pchanged = Artist.pchanged
+
+
+class BarContainer(Container):
+    """
+    Container for the artists of bar plots (e.g. created by `.Axes.bar`).
+
+    The container can be treated as a tuple of the *patches* themselves.
+    Additionally, you can access these and further parameters by the
+    attributes.
+
+    Attributes
+    ----------
+    patches : list of :class:`~matplotlib.patches.Rectangle`
+        The artists of the bars.
+
+    errorbar : None or :class:`~matplotlib.container.ErrorbarContainer`
+        A container for the error bar artists if error bars are present.
+        *None* otherwise.
+
+    datavalues : None or array-like
+        The underlying data values corresponding to the bars.
+
+    orientation : {'vertical', 'horizontal'}, default: None
+        If 'vertical', the bars are assumed to be vertical.
+        If 'horizontal', the bars are assumed to be horizontal.
+
+    """
+
+    def __init__(self, patches, errorbar=None, *, datavalues=None,
+                 orientation=None, **kwargs):
+        self.patches = patches
+        self.errorbar = errorbar
+        self.datavalues = datavalues
+        self.orientation = orientation
+        super().__init__(patches, **kwargs)
+
+
+class ErrorbarContainer(Container):
+    """
+    Container for the artists of error bars (e.g. created by `.Axes.errorbar`).
+
+    The container can be treated as the *lines* tuple itself.
+    Additionally, you can access these and further parameters by the
+    attributes.
+
+    Attributes
+    ----------
+    lines : tuple
+        Tuple of ``(data_line, caplines, barlinecols)``.
+
+        - data_line : A `~matplotlib.lines.Line2D` instance of x, y plot markers
+          and/or line.
+        - caplines : A tuple of `~matplotlib.lines.Line2D` instances of the error
+          bar caps.
+        - barlinecols : A tuple of `~matplotlib.collections.LineCollection` with the
+          horizontal and vertical error ranges.
+
+    has_xerr, has_yerr : bool
+        ``True`` if the errorbar has x/y errors.
+
+    """
+
+    def __init__(self, lines, has_xerr=False, has_yerr=False, **kwargs):
+        self.lines = lines
+        self.has_xerr = has_xerr
+        self.has_yerr = has_yerr
+        super().__init__(lines, **kwargs)
+
+
+class StemContainer(Container):
+    """
+    Container for the artists created in a :meth:`.Axes.stem` plot.
+
+    The container can be treated like a namedtuple ``(markerline, stemlines,
+    baseline)``.
+
+    Attributes
+    ----------
+    markerline : `~matplotlib.lines.Line2D`
+        The artist of the markers at the stem heads.
+
+    stemlines : `~matplotlib.collections.LineCollection`
+        The artists of the vertical lines for all stems.
+
+    baseline : `~matplotlib.lines.Line2D`
+        The artist of the horizontal baseline.
+    """
+    def __init__(self, markerline_stemlines_baseline, **kwargs):
+        """
+        Parameters
+        ----------
+        markerline_stemlines_baseline : tuple
+            Tuple of ``(markerline, stemlines, baseline)``.
+            ``markerline`` contains the `.Line2D` of the markers,
+            ``stemlines`` is a `.LineCollection` of the main lines,
+            ``baseline`` is the `.Line2D` of the baseline.
+        """
+        markerline, stemlines, baseline = markerline_stemlines_baseline
+        self.markerline = markerline
+        self.stemlines = stemlines
+        self.baseline = baseline
+        super().__init__(markerline_stemlines_baseline, **kwargs)
diff --git a/lib/python3.12/site-packages/matplotlib/contour.py b/lib/python3.12/site-packages/matplotlib/contour.py
new file mode 100644
index 0000000000000000000000000000000000000000..f7318d57812161ab164e3d3e3a62ab13cf020c2c
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/contour.py
@@ -0,0 +1,1702 @@
+"""
+Classes to support contour plotting and labelling for the Axes class.
+"""
+
+from contextlib import ExitStack
+import functools
+import math
+from numbers import Integral
+
+import numpy as np
+from numpy import ma
+
+import matplotlib as mpl
+from matplotlib import _api, _docstring
+from matplotlib.backend_bases import MouseButton
+from matplotlib.lines import Line2D
+from matplotlib.path import Path
+from matplotlib.text import Text
+import matplotlib.ticker as ticker
+import matplotlib.cm as cm
+import matplotlib.colors as mcolors
+import matplotlib.collections as mcoll
+import matplotlib.font_manager as font_manager
+import matplotlib.cbook as cbook
+import matplotlib.patches as mpatches
+import matplotlib.transforms as mtransforms
+
+
+def _contour_labeler_event_handler(cs, inline, inline_spacing, event):
+    canvas = cs.axes.get_figure(root=True).canvas
+    is_button = event.name == "button_press_event"
+    is_key = event.name == "key_press_event"
+    # Quit (even if not in infinite mode; this is consistent with
+    # MATLAB and sometimes quite useful, but will require the user to
+    # test how many points were actually returned before using data).
+    if (is_button and event.button == MouseButton.MIDDLE
+            or is_key and event.key in ["escape", "enter"]):
+        canvas.stop_event_loop()
+    # Pop last click.
+    elif (is_button and event.button == MouseButton.RIGHT
+          or is_key and event.key in ["backspace", "delete"]):
+        # Unfortunately, if one is doing inline labels, then there is currently
+        # no way to fix the broken contour - once humpty-dumpty is broken, he
+        # can't be put back together.  In inline mode, this does nothing.
+        if not inline:
+            cs.pop_label()
+            canvas.draw()
+    # Add new click.
+    elif (is_button and event.button == MouseButton.LEFT
+          # On macOS/gtk, some keys return None.
+          or is_key and event.key is not None):
+        if cs.axes.contains(event)[0]:
+            cs.add_label_near(event.x, event.y, transform=False,
+                              inline=inline, inline_spacing=inline_spacing)
+            canvas.draw()
+
+
+class ContourLabeler:
+    """Mixin to provide labelling capability to `.ContourSet`."""
+
+    def clabel(self, levels=None, *,
+               fontsize=None, inline=True, inline_spacing=5, fmt=None,
+               colors=None, use_clabeltext=False, manual=False,
+               rightside_up=True, zorder=None):
+        """
+        Label a contour plot.
+
+        Adds labels to line contours in this `.ContourSet` (which inherits from
+        this mixin class).
+
+        Parameters
+        ----------
+        levels : array-like, optional
+            A list of level values, that should be labeled. The list must be
+            a subset of ``cs.levels``. If not given, all levels are labeled.
+
+        fontsize : str or float, default: :rc:`font.size`
+            Size in points or relative size e.g., 'smaller', 'x-large'.
+            See `.Text.set_size` for accepted string values.
+
+        colors : :mpltype:`color` or colors or None, default: None
+            The label colors:
+
+            - If *None*, the color of each label matches the color of
+              the corresponding contour.
+
+            - If one string color, e.g., *colors* = 'r' or *colors* =
+              'red', all labels will be plotted in this color.
+
+            - If a tuple of colors (string, float, RGB, etc), different labels
+              will be plotted in different colors in the order specified.
+
+        inline : bool, default: True
+            If ``True`` the underlying contour is removed where the label is
+            placed.
+
+        inline_spacing : float, default: 5
+            Space in pixels to leave on each side of label when placing inline.
+
+            This spacing will be exact for labels at locations where the
+            contour is straight, less so for labels on curved contours.
+
+        fmt : `.Formatter` or str or callable or dict, optional
+            How the levels are formatted:
+
+            - If a `.Formatter`, it is used to format all levels at once, using
+              its `.Formatter.format_ticks` method.
+            - If a str, it is interpreted as a %-style format string.
+            - If a callable, it is called with one level at a time and should
+              return the corresponding label.
+            - If a dict, it should directly map levels to labels.
+
+            The default is to use a standard `.ScalarFormatter`.
+
+        manual : bool or iterable, default: False
+            If ``True``, contour labels will be placed manually using
+            mouse clicks. Click the first button near a contour to
+            add a label, click the second button (or potentially both
+            mouse buttons at once) to finish adding labels. The third
+            button can be used to remove the last label added, but
+            only if labels are not inline. Alternatively, the keyboard
+            can be used to select label locations (enter to end label
+            placement, delete or backspace act like the third mouse button,
+            and any other key will select a label location).
+
+            *manual* can also be an iterable object of (x, y) tuples.
+            Contour labels will be created as if mouse is clicked at each
+            (x, y) position.
+
+        rightside_up : bool, default: True
+            If ``True``, label rotations will always be plus
+            or minus 90 degrees from level.
+
+        use_clabeltext : bool, default: False
+            If ``True``, use `.Text.set_transform_rotates_text` to ensure that
+            label rotation is updated whenever the Axes aspect changes.
+
+        zorder : float or None, default: ``(2 + contour.get_zorder())``
+            zorder of the contour labels.
+
+        Returns
+        -------
+        labels
+            A list of `.Text` instances for the labels.
+        """
+
+        # Based on the input arguments, clabel() adds a list of "label
+        # specific" attributes to the ContourSet object.  These attributes are
+        # all of the form label* and names should be fairly self explanatory.
+        #
+        # Once these attributes are set, clabel passes control to the labels()
+        # method (for automatic label placement) or blocking_input_loop and
+        # _contour_labeler_event_handler (for manual label placement).
+
+        if fmt is None:
+            fmt = ticker.ScalarFormatter(useOffset=False)
+            fmt.create_dummy_axis()
+        self.labelFmt = fmt
+        self._use_clabeltext = use_clabeltext
+        self.labelManual = manual
+        self.rightside_up = rightside_up
+        self._clabel_zorder = 2 + self.get_zorder() if zorder is None else zorder
+
+        if levels is None:
+            levels = self.levels
+            indices = list(range(len(self.cvalues)))
+        else:
+            levlabs = list(levels)
+            indices, levels = [], []
+            for i, lev in enumerate(self.levels):
+                if lev in levlabs:
+                    indices.append(i)
+                    levels.append(lev)
+            if len(levels) < len(levlabs):
+                raise ValueError(f"Specified levels {levlabs} don't match "
+                                 f"available levels {self.levels}")
+        self.labelLevelList = levels
+        self.labelIndiceList = indices
+
+        self._label_font_props = font_manager.FontProperties(size=fontsize)
+
+        if colors is None:
+            self.labelMappable = self
+            self.labelCValueList = np.take(self.cvalues, self.labelIndiceList)
+        else:
+            cmap = mcolors.ListedColormap(colors, N=len(self.labelLevelList))
+            self.labelCValueList = list(range(len(self.labelLevelList)))
+            self.labelMappable = cm.ScalarMappable(cmap=cmap,
+                                                   norm=mcolors.NoNorm())
+
+        self.labelXYs = []
+
+        if np.iterable(manual):
+            for x, y in manual:
+                self.add_label_near(x, y, inline, inline_spacing)
+        elif manual:
+            print('Select label locations manually using first mouse button.')
+            print('End manual selection with second mouse button.')
+            if not inline:
+                print('Remove last label by clicking third mouse button.')
+            mpl._blocking_input.blocking_input_loop(
+                self.axes.get_figure(root=True),
+                ["button_press_event", "key_press_event"],
+                timeout=-1, handler=functools.partial(
+                    _contour_labeler_event_handler,
+                    self, inline, inline_spacing))
+        else:
+            self.labels(inline, inline_spacing)
+
+        return cbook.silent_list('text.Text', self.labelTexts)
+
+    def print_label(self, linecontour, labelwidth):
+        """Return whether a contour is long enough to hold a label."""
+        return (len(linecontour) > 10 * labelwidth
+                or (len(linecontour)
+                    and (np.ptp(linecontour, axis=0) > 1.2 * labelwidth).any()))
+
+    def too_close(self, x, y, lw):
+        """Return whether a label is already near this location."""
+        thresh = (1.2 * lw) ** 2
+        return any((x - loc[0]) ** 2 + (y - loc[1]) ** 2 < thresh
+                   for loc in self.labelXYs)
+
+    def _get_nth_label_width(self, nth):
+        """Return the width of the *nth* label, in pixels."""
+        fig = self.axes.get_figure(root=False)
+        renderer = fig.get_figure(root=True)._get_renderer()
+        return (Text(0, 0,
+                     self.get_text(self.labelLevelList[nth], self.labelFmt),
+                     figure=fig, fontproperties=self._label_font_props)
+                .get_window_extent(renderer).width)
+
+    def get_text(self, lev, fmt):
+        """Get the text of the label."""
+        if isinstance(lev, str):
+            return lev
+        elif isinstance(fmt, dict):
+            return fmt.get(lev, '%1.3f')
+        elif callable(getattr(fmt, "format_ticks", None)):
+            return fmt.format_ticks([*self.labelLevelList, lev])[-1]
+        elif callable(fmt):
+            return fmt(lev)
+        else:
+            return fmt % lev
+
+    def locate_label(self, linecontour, labelwidth):
+        """
+        Find good place to draw a label (relatively flat part of the contour).
+        """
+        ctr_size = len(linecontour)
+        n_blocks = int(np.ceil(ctr_size / labelwidth)) if labelwidth > 1 else 1
+        block_size = ctr_size if n_blocks == 1 else int(labelwidth)
+        # Split contour into blocks of length ``block_size``, filling the last
+        # block by cycling the contour start (per `np.resize` semantics).  (Due
+        # to cycling, the index returned is taken modulo ctr_size.)
+        xx = np.resize(linecontour[:, 0], (n_blocks, block_size))
+        yy = np.resize(linecontour[:, 1], (n_blocks, block_size))
+        yfirst = yy[:, :1]
+        ylast = yy[:, -1:]
+        xfirst = xx[:, :1]
+        xlast = xx[:, -1:]
+        s = (yfirst - yy) * (xlast - xfirst) - (xfirst - xx) * (ylast - yfirst)
+        l = np.hypot(xlast - xfirst, ylast - yfirst)
+        # Ignore warning that divide by zero throws, as this is a valid option
+        with np.errstate(divide='ignore', invalid='ignore'):
+            distances = (abs(s) / l).sum(axis=-1)
+        # Labels are drawn in the middle of the block (``hbsize``) where the
+        # contour is the closest (per ``distances``) to a straight line, but
+        # not `too_close()` to a preexisting label.
+        hbsize = block_size // 2
+        adist = np.argsort(distances)
+        # If all candidates are `too_close()`, go back to the straightest part
+        # (``adist[0]``).
+        for idx in np.append(adist, adist[0]):
+            x, y = xx[idx, hbsize], yy[idx, hbsize]
+            if not self.too_close(x, y, labelwidth):
+                break
+        return x, y, (idx * block_size + hbsize) % ctr_size
+
+    def _split_path_and_get_label_rotation(self, path, idx, screen_pos, lw, spacing=5):
+        """
+        Prepare for insertion of a label at index *idx* of *path*.
+
+        Parameters
+        ----------
+        path : Path
+            The path where the label will be inserted, in data space.
+        idx : int
+            The vertex index after which the label will be inserted.
+        screen_pos : (float, float)
+            The position where the label will be inserted, in screen space.
+        lw : float
+            The label width, in screen space.
+        spacing : float
+            Extra spacing around the label, in screen space.
+
+        Returns
+        -------
+        path : Path
+            The path, broken so that the label can be drawn over it.
+        angle : float
+            The rotation of the label.
+
+        Notes
+        -----
+        Both tasks are done together to avoid calculating path lengths multiple times,
+        which is relatively costly.
+
+        The method used here involves computing the path length along the contour in
+        pixel coordinates and then looking (label width / 2) away from central point to
+        determine rotation and then to break contour if desired.  The extra spacing is
+        taken into account when breaking the path, but not when computing the angle.
+        """
+        xys = path.vertices
+        codes = path.codes
+
+        # Insert a vertex at idx/pos (converting back to data space), if there isn't yet
+        # a vertex there.  With infinite precision one could also always insert the
+        # extra vertex (it will get masked out by the label below anyways), but floating
+        # point inaccuracies (the point can have undergone a data->screen->data
+        # transform loop) can slightly shift the point and e.g. shift the angle computed
+        # below from exactly zero to nonzero.
+        pos = self.get_transform().inverted().transform(screen_pos)
+        if not np.allclose(pos, xys[idx]):
+            xys = np.insert(xys, idx, pos, axis=0)
+            codes = np.insert(codes, idx, Path.LINETO)
+
+        # Find the connected component where the label will be inserted.  Note that a
+        # path always starts with a MOVETO, and we consider there's an implicit
+        # MOVETO (closing the last path) at the end.
+        movetos = (codes == Path.MOVETO).nonzero()[0]
+        start = movetos[movetos <= idx][-1]
+        try:
+            stop = movetos[movetos > idx][0]
+        except IndexError:
+            stop = len(codes)
+
+        # Restrict ourselves to the connected component.
+        cc_xys = xys[start:stop]
+        idx -= start
+
+        # If the path is closed, rotate it s.t. it starts at the label.
+        is_closed_path = codes[stop - 1] == Path.CLOSEPOLY
+        if is_closed_path:
+            cc_xys = np.concatenate([cc_xys[idx:-1], cc_xys[:idx+1]])
+            idx = 0
+
+        # Like np.interp, but additionally vectorized over fp.
+        def interp_vec(x, xp, fp): return [np.interp(x, xp, col) for col in fp.T]
+
+        # Use cumulative path lengths ("cpl") as curvilinear coordinate along contour.
+        screen_xys = self.get_transform().transform(cc_xys)
+        path_cpls = np.insert(
+            np.cumsum(np.hypot(*np.diff(screen_xys, axis=0).T)), 0, 0)
+        path_cpls -= path_cpls[idx]
+
+        # Use linear interpolation to get end coordinates of label.
+        target_cpls = np.array([-lw/2, lw/2])
+        if is_closed_path:  # For closed paths, target from the other end.
+            target_cpls[0] += (path_cpls[-1] - path_cpls[0])
+        (sx0, sx1), (sy0, sy1) = interp_vec(target_cpls, path_cpls, screen_xys)
+        angle = np.rad2deg(np.arctan2(sy1 - sy0, sx1 - sx0))  # Screen space.
+        if self.rightside_up:  # Fix angle so text is never upside-down
+            angle = (angle + 90) % 180 - 90
+
+        target_cpls += [-spacing, +spacing]  # Expand range by spacing.
+
+        # Get indices near points of interest; use -1 as out of bounds marker.
+        i0, i1 = np.interp(target_cpls, path_cpls, range(len(path_cpls)),
+                           left=-1, right=-1)
+        i0 = math.floor(i0)
+        i1 = math.ceil(i1)
+        (x0, x1), (y0, y1) = interp_vec(target_cpls, path_cpls, cc_xys)
+
+        # Actually break contours (dropping zero-len parts).
+        new_xy_blocks = []
+        new_code_blocks = []
+        if is_closed_path:
+            if i0 != -1 and i1 != -1:
+                # This is probably wrong in the case that the entire contour would
+                # be discarded, but ensures that a valid path is returned and is
+                # consistent with behavior of mpl <3.8
+                points = cc_xys[i1:i0+1]
+                new_xy_blocks.extend([[(x1, y1)], points, [(x0, y0)]])
+                nlines = len(points) + 1
+                new_code_blocks.extend([[Path.MOVETO], [Path.LINETO] * nlines])
+        else:
+            if i0 != -1:
+                new_xy_blocks.extend([cc_xys[:i0 + 1], [(x0, y0)]])
+                new_code_blocks.extend([[Path.MOVETO], [Path.LINETO] * (i0 + 1)])
+            if i1 != -1:
+                new_xy_blocks.extend([[(x1, y1)], cc_xys[i1:]])
+                new_code_blocks.extend([
+                    [Path.MOVETO], [Path.LINETO] * (len(cc_xys) - i1)])
+
+        # Back to the full path.
+        xys = np.concatenate([xys[:start], *new_xy_blocks, xys[stop:]])
+        codes = np.concatenate([codes[:start], *new_code_blocks, codes[stop:]])
+
+        return angle, Path(xys, codes)
+
+    def add_label(self, x, y, rotation, lev, cvalue):
+        """Add a contour label, respecting whether *use_clabeltext* was set."""
+        data_x, data_y = self.axes.transData.inverted().transform((x, y))
+        t = Text(
+            data_x, data_y,
+            text=self.get_text(lev, self.labelFmt),
+            rotation=rotation,
+            horizontalalignment='center', verticalalignment='center',
+            zorder=self._clabel_zorder,
+            color=self.labelMappable.to_rgba(cvalue, alpha=self.get_alpha()),
+            fontproperties=self._label_font_props,
+            clip_box=self.axes.bbox)
+        if self._use_clabeltext:
+            data_rotation, = self.axes.transData.inverted().transform_angles(
+                [rotation], [[x, y]])
+            t.set(rotation=data_rotation, transform_rotates_text=True)
+        self.labelTexts.append(t)
+        self.labelCValues.append(cvalue)
+        self.labelXYs.append((x, y))
+        # Add label to plot here - useful for manual mode label selection
+        self.axes.add_artist(t)
+
+    def add_label_near(self, x, y, inline=True, inline_spacing=5,
+                       transform=None):
+        """
+        Add a label near the point ``(x, y)``.
+
+        Parameters
+        ----------
+        x, y : float
+            The approximate location of the label.
+        inline : bool, default: True
+            If *True* remove the segment of the contour beneath the label.
+        inline_spacing : int, default: 5
+            Space in pixels to leave on each side of label when placing
+            inline. This spacing will be exact for labels at locations where
+            the contour is straight, less so for labels on curved contours.
+        transform : `.Transform` or `False`, default: ``self.axes.transData``
+            A transform applied to ``(x, y)`` before labeling.  The default
+            causes ``(x, y)`` to be interpreted as data coordinates.  `False`
+            is a synonym for `.IdentityTransform`; i.e. ``(x, y)`` should be
+            interpreted as display coordinates.
+        """
+
+        if transform is None:
+            transform = self.axes.transData
+        if transform:
+            x, y = transform.transform((x, y))
+
+        idx_level_min, idx_vtx_min, proj = self._find_nearest_contour(
+            (x, y), self.labelIndiceList)
+        path = self._paths[idx_level_min]
+        level = self.labelIndiceList.index(idx_level_min)
+        label_width = self._get_nth_label_width(level)
+        rotation, path = self._split_path_and_get_label_rotation(
+            path, idx_vtx_min, proj, label_width, inline_spacing)
+        self.add_label(*proj, rotation, self.labelLevelList[idx_level_min],
+                       self.labelCValueList[idx_level_min])
+
+        if inline:
+            self._paths[idx_level_min] = path
+
+    def pop_label(self, index=-1):
+        """Defaults to removing last label, but any index can be supplied"""
+        self.labelCValues.pop(index)
+        t = self.labelTexts.pop(index)
+        t.remove()
+
+    def labels(self, inline, inline_spacing):
+        for idx, (icon, lev, cvalue) in enumerate(zip(
+                self.labelIndiceList,
+                self.labelLevelList,
+                self.labelCValueList,
+        )):
+            trans = self.get_transform()
+            label_width = self._get_nth_label_width(idx)
+            additions = []
+            for subpath in self._paths[icon]._iter_connected_components():
+                screen_xys = trans.transform(subpath.vertices)
+                # Check if long enough for a label
+                if self.print_label(screen_xys, label_width):
+                    x, y, idx = self.locate_label(screen_xys, label_width)
+                    rotation, path = self._split_path_and_get_label_rotation(
+                        subpath, idx, (x, y),
+                        label_width, inline_spacing)
+                    self.add_label(x, y, rotation, lev, cvalue)  # Really add label.
+                    if inline:  # If inline, add new contours
+                        additions.append(path)
+                else:  # If not adding label, keep old path
+                    additions.append(subpath)
+            # After looping over all segments on a contour, replace old path by new one
+            # if inlining.
+            if inline:
+                self._paths[icon] = Path.make_compound_path(*additions)
+
+    def remove(self):
+        super().remove()
+        for text in self.labelTexts:
+            text.remove()
+
+
+def _find_closest_point_on_path(xys, p):
+    """
+    Parameters
+    ----------
+    xys : (N, 2) array-like
+        Coordinates of vertices.
+    p : (float, float)
+        Coordinates of point.
+
+    Returns
+    -------
+    d2min : float
+        Minimum square distance of *p* to *xys*.
+    proj : (float, float)
+        Projection of *p* onto *xys*.
+    imin : (int, int)
+        Consecutive indices of vertices of segment in *xys* where *proj* is.
+        Segments are considered as including their end-points; i.e. if the
+        closest point on the path is a node in *xys* with index *i*, this
+        returns ``(i-1, i)``.  For the special case where *xys* is a single
+        point, this returns ``(0, 0)``.
+    """
+    if len(xys) == 1:
+        return (((p - xys[0]) ** 2).sum(), xys[0], (0, 0))
+    dxys = xys[1:] - xys[:-1]  # Individual segment vectors.
+    norms = (dxys ** 2).sum(axis=1)
+    norms[norms == 0] = 1  # For zero-length segment, replace 0/0 by 0/1.
+    rel_projs = np.clip(  # Project onto each segment in relative 0-1 coords.
+        ((p - xys[:-1]) * dxys).sum(axis=1) / norms,
+        0, 1)[:, None]
+    projs = xys[:-1] + rel_projs * dxys  # Projs. onto each segment, in (x, y).
+    d2s = ((projs - p) ** 2).sum(axis=1)  # Squared distances.
+    imin = np.argmin(d2s)
+    return (d2s[imin], projs[imin], (imin, imin+1))
+
+
+_docstring.interpd.register(contour_set_attributes=r"""
+Attributes
+----------
+levels : array
+    The values of the contour levels.
+
+layers : array
+    Same as levels for line contours; half-way between
+    levels for filled contours.  See ``ContourSet._process_colors``.
+""")
+
+
+@_docstring.interpd
+class ContourSet(ContourLabeler, mcoll.Collection):
+    """
+    Store a set of contour lines or filled regions.
+
+    User-callable method: `~.Axes.clabel`
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+
+    levels : [level0, level1, ..., leveln]
+        A list of floating point numbers indicating the contour levels.
+
+    allsegs : [level0segs, level1segs, ...]
+        List of all the polygon segments for all the *levels*.
+        For contour lines ``len(allsegs) == len(levels)``, and for
+        filled contour regions ``len(allsegs) = len(levels)-1``. The lists
+        should look like ::
+
+            level0segs = [polygon0, polygon1, ...]
+            polygon0 = [[x0, y0], [x1, y1], ...]
+
+    allkinds : ``None`` or [level0kinds, level1kinds, ...]
+        Optional list of all the polygon vertex kinds (code types), as
+        described and used in Path. This is used to allow multiply-
+        connected paths such as holes within filled polygons.
+        If not ``None``, ``len(allkinds) == len(allsegs)``. The lists
+        should look like ::
+
+            level0kinds = [polygon0kinds, ...]
+            polygon0kinds = [vertexcode0, vertexcode1, ...]
+
+        If *allkinds* is not ``None``, usually all polygons for a
+        particular contour level are grouped together so that
+        ``level0segs = [polygon0]`` and ``level0kinds = [polygon0kinds]``.
+
+    **kwargs
+        Keyword arguments are as described in the docstring of
+        `~.Axes.contour`.
+
+    %(contour_set_attributes)s
+    """
+
+    def __init__(self, ax, *args,
+                 levels=None, filled=False, linewidths=None, linestyles=None,
+                 hatches=(None,), alpha=None, origin=None, extent=None,
+                 cmap=None, colors=None, norm=None, vmin=None, vmax=None,
+                 colorizer=None, extend='neither', antialiased=None, nchunk=0,
+                 locator=None, transform=None, negative_linestyles=None, clip_path=None,
+                 **kwargs):
+        """
+        Draw contour lines or filled regions, depending on
+        whether keyword arg *filled* is ``False`` (default) or ``True``.
+
+        Call signature::
+
+            ContourSet(ax, levels, allsegs, [allkinds], **kwargs)
+
+        Parameters
+        ----------
+        ax : `~matplotlib.axes.Axes`
+            The `~.axes.Axes` object to draw on.
+
+        levels : [level0, level1, ..., leveln]
+            A list of floating point numbers indicating the contour
+            levels.
+
+        allsegs : [level0segs, level1segs, ...]
+            List of all the polygon segments for all the *levels*.
+            For contour lines ``len(allsegs) == len(levels)``, and for
+            filled contour regions ``len(allsegs) = len(levels)-1``. The lists
+            should look like ::
+
+                level0segs = [polygon0, polygon1, ...]
+                polygon0 = [[x0, y0], [x1, y1], ...]
+
+        allkinds : [level0kinds, level1kinds, ...], optional
+            Optional list of all the polygon vertex kinds (code types), as
+            described and used in Path. This is used to allow multiply-
+            connected paths such as holes within filled polygons.
+            If not ``None``, ``len(allkinds) == len(allsegs)``. The lists
+            should look like ::
+
+                level0kinds = [polygon0kinds, ...]
+                polygon0kinds = [vertexcode0, vertexcode1, ...]
+
+            If *allkinds* is not ``None``, usually all polygons for a
+            particular contour level are grouped together so that
+            ``level0segs = [polygon0]`` and ``level0kinds = [polygon0kinds]``.
+
+        **kwargs
+            Keyword arguments are as described in the docstring of
+            `~.Axes.contour`.
+        """
+        if antialiased is None and filled:
+            # Eliminate artifacts; we are not stroking the boundaries.
+            antialiased = False
+            # The default for line contours will be taken from the
+            # LineCollection default, which uses :rc:`lines.antialiased`.
+        super().__init__(
+            antialiaseds=antialiased,
+            alpha=alpha,
+            clip_path=clip_path,
+            transform=transform,
+            colorizer=colorizer,
+        )
+        self.axes = ax
+        self.levels = levels
+        self.filled = filled
+        self.hatches = hatches
+        self.origin = origin
+        self.extent = extent
+        self.colors = colors
+        self.extend = extend
+
+        self.nchunk = nchunk
+        self.locator = locator
+
+        if colorizer:
+            self._set_colorizer_check_keywords(colorizer, cmap=cmap,
+                                               norm=norm, vmin=vmin,
+                                               vmax=vmax, colors=colors)
+            norm = colorizer.norm
+            cmap = colorizer.cmap
+        if (isinstance(norm, mcolors.LogNorm)
+                or isinstance(self.locator, ticker.LogLocator)):
+            self.logscale = True
+            if norm is None:
+                norm = mcolors.LogNorm()
+        else:
+            self.logscale = False
+
+        _api.check_in_list([None, 'lower', 'upper', 'image'], origin=origin)
+        if self.extent is not None and len(self.extent) != 4:
+            raise ValueError(
+                "If given, 'extent' must be None or (x0, x1, y0, y1)")
+        if self.colors is not None and cmap is not None:
+            raise ValueError('Either colors or cmap must be None')
+        if self.origin == 'image':
+            self.origin = mpl.rcParams['image.origin']
+
+        self._orig_linestyles = linestyles  # Only kept for user access.
+        self.negative_linestyles = negative_linestyles
+        # If negative_linestyles was not defined as a keyword argument, define
+        # negative_linestyles with rcParams
+        if self.negative_linestyles is None:
+            self.negative_linestyles = \
+                mpl.rcParams['contour.negative_linestyle']
+
+        kwargs = self._process_args(*args, **kwargs)
+        self._process_levels()
+
+        self._extend_min = self.extend in ['min', 'both']
+        self._extend_max = self.extend in ['max', 'both']
+        if self.colors is not None:
+            if mcolors.is_color_like(self.colors):
+                color_sequence = [self.colors]
+            else:
+                color_sequence = self.colors
+
+            ncolors = len(self.levels)
+            if self.filled:
+                ncolors -= 1
+            i0 = 0
+
+            # Handle the case where colors are given for the extended
+            # parts of the contour.
+
+            use_set_under_over = False
+            # if we are extending the lower end, and we've been given enough
+            # colors then skip the first color in the resulting cmap. For the
+            # extend_max case we don't need to worry about passing more colors
+            # than ncolors as ListedColormap will clip.
+            total_levels = (ncolors +
+                            int(self._extend_min) +
+                            int(self._extend_max))
+            if (len(color_sequence) == total_levels and
+                    (self._extend_min or self._extend_max)):
+                use_set_under_over = True
+                if self._extend_min:
+                    i0 = 1
+
+            cmap = mcolors.ListedColormap(color_sequence[i0:None], N=ncolors)
+
+            if use_set_under_over:
+                if self._extend_min:
+                    cmap.set_under(color_sequence[0])
+                if self._extend_max:
+                    cmap.set_over(color_sequence[-1])
+
+        # label lists must be initialized here
+        self.labelTexts = []
+        self.labelCValues = []
+
+        self.set_cmap(cmap)
+        if norm is not None:
+            self.set_norm(norm)
+        with self.norm.callbacks.blocked(signal="changed"):
+            if vmin is not None:
+                self.norm.vmin = vmin
+            if vmax is not None:
+                self.norm.vmax = vmax
+        self.norm._changed()
+        self._process_colors()
+
+        if self._paths is None:
+            self._paths = self._make_paths_from_contour_generator()
+
+        if self.filled:
+            if linewidths is not None:
+                _api.warn_external('linewidths is ignored by contourf')
+            # Lower and upper contour levels.
+            lowers, uppers = self._get_lowers_and_uppers()
+            self.set(
+                edgecolor="none",
+                # Default zorder taken from Collection
+                zorder=kwargs.pop("zorder", 1),
+            )
+
+        else:
+            self.set(
+                facecolor="none",
+                linewidths=self._process_linewidths(linewidths),
+                linestyle=self._process_linestyles(linestyles),
+                # Default zorder taken from LineCollection, which is higher
+                # than for filled contours so that lines are displayed on top.
+                zorder=kwargs.pop("zorder", 2),
+                label="_nolegend_",
+            )
+
+        self.axes.add_collection(self, autolim=False)
+        self.sticky_edges.x[:] = [self._mins[0], self._maxs[0]]
+        self.sticky_edges.y[:] = [self._mins[1], self._maxs[1]]
+        self.axes.update_datalim([self._mins, self._maxs])
+        self.axes.autoscale_view(tight=True)
+
+        self.changed()  # set the colors
+
+        if kwargs:
+            _api.warn_external(
+                'The following kwargs were not used by contour: ' +
+                ", ".join(map(repr, kwargs))
+            )
+
+    allsegs = property(lambda self: [
+        [subp.vertices for subp in p._iter_connected_components()]
+        for p in self.get_paths()])
+    allkinds = property(lambda self: [
+        [subp.codes for subp in p._iter_connected_components()]
+        for p in self.get_paths()])
+    alpha = property(lambda self: self.get_alpha())
+    linestyles = property(lambda self: self._orig_linestyles)
+
+    def get_transform(self):
+        """Return the `.Transform` instance used by this ContourSet."""
+        if self._transform is None:
+            self._transform = self.axes.transData
+        elif (not isinstance(self._transform, mtransforms.Transform)
+              and hasattr(self._transform, '_as_mpl_transform')):
+            self._transform = self._transform._as_mpl_transform(self.axes)
+        return self._transform
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        # the C object _contour_generator cannot currently be pickled. This
+        # isn't a big issue as it is not actually used once the contour has
+        # been calculated.
+        state['_contour_generator'] = None
+        return state
+
+    def legend_elements(self, variable_name='x', str_format=str):
+        """
+        Return a list of artists and labels suitable for passing through
+        to `~.Axes.legend` which represent this ContourSet.
+
+        The labels have the form "0 < x <= 1" stating the data ranges which
+        the artists represent.
+
+        Parameters
+        ----------
+        variable_name : str
+            The string used inside the inequality used on the labels.
+        str_format : function: float -> str
+            Function used to format the numbers in the labels.
+
+        Returns
+        -------
+        artists : list[`.Artist`]
+            A list of the artists.
+        labels : list[str]
+            A list of the labels.
+        """
+        artists = []
+        labels = []
+
+        if self.filled:
+            lowers, uppers = self._get_lowers_and_uppers()
+            n_levels = len(self._paths)
+            for idx in range(n_levels):
+                artists.append(mpatches.Rectangle(
+                    (0, 0), 1, 1,
+                    facecolor=self.get_facecolor()[idx],
+                    hatch=self.hatches[idx % len(self.hatches)],
+                ))
+                lower = str_format(lowers[idx])
+                upper = str_format(uppers[idx])
+                if idx == 0 and self.extend in ('min', 'both'):
+                    labels.append(fr'${variable_name} \leq {lower}s$')
+                elif idx == n_levels - 1 and self.extend in ('max', 'both'):
+                    labels.append(fr'${variable_name} > {upper}s$')
+                else:
+                    labels.append(fr'${lower} < {variable_name} \leq {upper}$')
+        else:
+            for idx, level in enumerate(self.levels):
+                artists.append(Line2D(
+                    [], [],
+                    color=self.get_edgecolor()[idx],
+                    linewidth=self.get_linewidths()[idx],
+                    linestyle=self.get_linestyles()[idx],
+                ))
+                labels.append(fr'${variable_name} = {str_format(level)}$')
+
+        return artists, labels
+
+    def _process_args(self, *args, **kwargs):
+        """
+        Process *args* and *kwargs*; override in derived classes.
+
+        Must set self.levels, self.zmin and self.zmax, and update Axes limits.
+        """
+        self.levels = args[0]
+        allsegs = args[1]
+        allkinds = args[2] if len(args) > 2 else None
+        self.zmax = np.max(self.levels)
+        self.zmin = np.min(self.levels)
+
+        if allkinds is None:
+            allkinds = [[None] * len(segs) for segs in allsegs]
+
+        # Check lengths of levels and allsegs.
+        if self.filled:
+            if len(allsegs) != len(self.levels) - 1:
+                raise ValueError('must be one less number of segments as '
+                                 'levels')
+        else:
+            if len(allsegs) != len(self.levels):
+                raise ValueError('must be same number of segments as levels')
+
+        # Check length of allkinds.
+        if len(allkinds) != len(allsegs):
+            raise ValueError('allkinds has different length to allsegs')
+
+        # Determine x, y bounds and update axes data limits.
+        flatseglist = [s for seg in allsegs for s in seg]
+        points = np.concatenate(flatseglist, axis=0)
+        self._mins = points.min(axis=0)
+        self._maxs = points.max(axis=0)
+
+        # Each entry in (allsegs, allkinds) is a list of (segs, kinds): segs is a list
+        # of (N, 2) arrays of xy coordinates, kinds is a list of arrays of corresponding
+        # pathcodes.  However, kinds can also be None; in which case all paths in that
+        # list are codeless (this case is normalized above).  These lists are used to
+        # construct paths, which then get concatenated.
+        self._paths = [Path.make_compound_path(*map(Path, segs, kinds))
+                       for segs, kinds in zip(allsegs, allkinds)]
+
+        return kwargs
+
+    def _make_paths_from_contour_generator(self):
+        """Compute ``paths`` using C extension."""
+        if self._paths is not None:
+            return self._paths
+        cg = self._contour_generator
+        empty_path = Path(np.empty((0, 2)))
+        vertices_and_codes = (
+            map(cg.create_filled_contour, *self._get_lowers_and_uppers())
+            if self.filled else
+            map(cg.create_contour, self.levels))
+        return [Path(np.concatenate(vs), np.concatenate(cs)) if len(vs) else empty_path
+                for vs, cs in vertices_and_codes]
+
+    def _get_lowers_and_uppers(self):
+        """
+        Return ``(lowers, uppers)`` for filled contours.
+        """
+        lowers = self._levels[:-1]
+        if self.zmin == lowers[0]:
+            # Include minimum values in lowest interval
+            lowers = lowers.copy()  # so we don't change self._levels
+            if self.logscale:
+                lowers[0] = 0.99 * self.zmin
+            else:
+                lowers[0] -= 1
+        uppers = self._levels[1:]
+        return (lowers, uppers)
+
+    def changed(self):
+        if not hasattr(self, "cvalues"):
+            self._process_colors()  # Sets cvalues.
+        # Force an autoscale immediately because self.to_rgba() calls
+        # autoscale_None() internally with the data passed to it,
+        # so if vmin/vmax are not set yet, this would override them with
+        # content from *cvalues* rather than levels like we want
+        self.norm.autoscale_None(self.levels)
+        self.set_array(self.cvalues)
+        self.update_scalarmappable()
+        alphas = np.broadcast_to(self.get_alpha(), len(self.cvalues))
+        for label, cv, alpha in zip(self.labelTexts, self.labelCValues, alphas):
+            label.set_alpha(alpha)
+            label.set_color(self.labelMappable.to_rgba(cv))
+        super().changed()
+
+    def _autolev(self, N):
+        """
+        Select contour levels to span the data.
+
+        The target number of levels, *N*, is used only when the
+        scale is not log and default locator is used.
+
+        We need two more levels for filled contours than for
+        line contours, because for the latter we need to specify
+        the lower and upper boundary of each range. For example,
+        a single contour boundary, say at z = 0, requires only
+        one contour line, but two filled regions, and therefore
+        three levels to provide boundaries for both regions.
+        """
+        if self.locator is None:
+            if self.logscale:
+                self.locator = ticker.LogLocator()
+            else:
+                self.locator = ticker.MaxNLocator(N + 1, min_n_ticks=1)
+
+        lev = self.locator.tick_values(self.zmin, self.zmax)
+
+        try:
+            if self.locator._symmetric:
+                return lev
+        except AttributeError:
+            pass
+
+        # Trim excess levels the locator may have supplied.
+        under = np.nonzero(lev < self.zmin)[0]
+        i0 = under[-1] if len(under) else 0
+        over = np.nonzero(lev > self.zmax)[0]
+        i1 = over[0] + 1 if len(over) else len(lev)
+        if self.extend in ('min', 'both'):
+            i0 += 1
+        if self.extend in ('max', 'both'):
+            i1 -= 1
+
+        if i1 - i0 < 3:
+            i0, i1 = 0, len(lev)
+
+        return lev[i0:i1]
+
+    def _process_contour_level_args(self, args, z_dtype):
+        """
+        Determine the contour levels and store in self.levels.
+        """
+        if self.levels is None:
+            if args:
+                levels_arg = args[0]
+            elif np.issubdtype(z_dtype, bool):
+                if self.filled:
+                    levels_arg = [0, .5, 1]
+                else:
+                    levels_arg = [.5]
+            else:
+                levels_arg = 7  # Default, hard-wired.
+        else:
+            levels_arg = self.levels
+        if isinstance(levels_arg, Integral):
+            self.levels = self._autolev(levels_arg)
+        else:
+            self.levels = np.asarray(levels_arg, np.float64)
+        if self.filled and len(self.levels) < 2:
+            raise ValueError("Filled contours require at least 2 levels.")
+        if len(self.levels) > 1 and np.min(np.diff(self.levels)) <= 0.0:
+            raise ValueError("Contour levels must be increasing")
+
+    def _process_levels(self):
+        """
+        Assign values to :attr:`layers` based on :attr:`levels`,
+        adding extended layers as needed if contours are filled.
+
+        For line contours, layers simply coincide with levels;
+        a line is a thin layer.  No extended levels are needed
+        with line contours.
+        """
+        # Make a private _levels to include extended regions; we
+        # want to leave the original levels attribute unchanged.
+        # (Colorbar needs this even for line contours.)
+        self._levels = list(self.levels)
+
+        if self.logscale:
+            lower, upper = 1e-250, 1e250
+        else:
+            lower, upper = -1e250, 1e250
+
+        if self.extend in ('both', 'min'):
+            self._levels.insert(0, lower)
+        if self.extend in ('both', 'max'):
+            self._levels.append(upper)
+        self._levels = np.asarray(self._levels)
+
+        if not self.filled:
+            self.layers = self.levels
+            return
+
+        # Layer values are mid-way between levels in screen space.
+        if self.logscale:
+            # Avoid overflow by taking sqrt before multiplying.
+            self.layers = (np.sqrt(self._levels[:-1])
+                           * np.sqrt(self._levels[1:]))
+        else:
+            self.layers = 0.5 * (self._levels[:-1] + self._levels[1:])
+
+    def _process_colors(self):
+        """
+        Color argument processing for contouring.
+
+        Note that we base the colormapping on the contour levels
+        and layers, not on the actual range of the Z values.  This
+        means we don't have to worry about bad values in Z, and we
+        always have the full dynamic range available for the selected
+        levels.
+
+        The color is based on the midpoint of the layer, except for
+        extended end layers.  By default, the norm vmin and vmax
+        are the extreme values of the non-extended levels.  Hence,
+        the layer color extremes are not the extreme values of
+        the colormap itself, but approach those values as the number
+        of levels increases.  An advantage of this scheme is that
+        line contours, when added to filled contours, take on
+        colors that are consistent with those of the filled regions;
+        for example, a contour line on the boundary between two
+        regions will have a color intermediate between those
+        of the regions.
+
+        """
+        self.monochrome = self.cmap.monochrome
+        if self.colors is not None:
+            # Generate integers for direct indexing.
+            i0, i1 = 0, len(self.levels)
+            if self.filled:
+                i1 -= 1
+                # Out of range indices for over and under:
+                if self.extend in ('both', 'min'):
+                    i0 -= 1
+                if self.extend in ('both', 'max'):
+                    i1 += 1
+            self.cvalues = list(range(i0, i1))
+            self.set_norm(mcolors.NoNorm())
+        else:
+            self.cvalues = self.layers
+        self.norm.autoscale_None(self.levels)
+        self.set_array(self.cvalues)
+        self.update_scalarmappable()
+        if self.extend in ('both', 'max', 'min'):
+            self.norm.clip = False
+
+    def _process_linewidths(self, linewidths):
+        Nlev = len(self.levels)
+        if linewidths is None:
+            default_linewidth = mpl.rcParams['contour.linewidth']
+            if default_linewidth is None:
+                default_linewidth = mpl.rcParams['lines.linewidth']
+            return [default_linewidth] * Nlev
+        elif not np.iterable(linewidths):
+            return [linewidths] * Nlev
+        else:
+            linewidths = list(linewidths)
+            return (linewidths * math.ceil(Nlev / len(linewidths)))[:Nlev]
+
+    def _process_linestyles(self, linestyles):
+        Nlev = len(self.levels)
+        if linestyles is None:
+            tlinestyles = ['solid'] * Nlev
+            if self.monochrome:
+                eps = - (self.zmax - self.zmin) * 1e-15
+                for i, lev in enumerate(self.levels):
+                    if lev < eps:
+                        tlinestyles[i] = self.negative_linestyles
+        else:
+            if isinstance(linestyles, str):
+                tlinestyles = [linestyles] * Nlev
+            elif np.iterable(linestyles):
+                tlinestyles = list(linestyles)
+                if len(tlinestyles) < Nlev:
+                    nreps = int(np.ceil(Nlev / len(linestyles)))
+                    tlinestyles = tlinestyles * nreps
+                if len(tlinestyles) > Nlev:
+                    tlinestyles = tlinestyles[:Nlev]
+            else:
+                raise ValueError("Unrecognized type for linestyles kwarg")
+        return tlinestyles
+
+    def _find_nearest_contour(self, xy, indices=None):
+        """
+        Find the point in the unfilled contour plot that is closest (in screen
+        space) to point *xy*.
+
+        Parameters
+        ----------
+        xy : tuple[float, float]
+            The reference point (in screen space).
+        indices : list of int or None, default: None
+            Indices of contour levels to consider.  If None (the default), all levels
+            are considered.
+
+        Returns
+        -------
+        idx_level_min : int
+            The index of the contour level closest to *xy*.
+        idx_vtx_min : int
+            The index of the `.Path` segment closest to *xy* (at that level).
+        proj : (float, float)
+            The point in the contour plot closest to *xy*.
+        """
+
+        # Convert each contour segment to pixel coordinates and then compare the given
+        # point to those coordinates for each contour. This is fast enough in normal
+        # cases, but speedups may be possible.
+
+        if self.filled:
+            raise ValueError("Method does not support filled contours")
+
+        if indices is None:
+            indices = range(len(self._paths))
+
+        d2min = np.inf
+        idx_level_min = idx_vtx_min = proj_min = None
+
+        for idx_level in indices:
+            path = self._paths[idx_level]
+            idx_vtx_start = 0
+            for subpath in path._iter_connected_components():
+                if not len(subpath.vertices):
+                    continue
+                lc = self.get_transform().transform(subpath.vertices)
+                d2, proj, leg = _find_closest_point_on_path(lc, xy)
+                if d2 < d2min:
+                    d2min = d2
+                    idx_level_min = idx_level
+                    idx_vtx_min = leg[1] + idx_vtx_start
+                    proj_min = proj
+                idx_vtx_start += len(subpath)
+
+        return idx_level_min, idx_vtx_min, proj_min
+
+    def find_nearest_contour(self, x, y, indices=None, pixel=True):
+        """
+        Find the point in the contour plot that is closest to ``(x, y)``.
+
+        This method does not support filled contours.
+
+        Parameters
+        ----------
+        x, y : float
+            The reference point.
+        indices : list of int or None, default: None
+            Indices of contour levels to consider.  If None (the default), all
+            levels are considered.
+        pixel : bool, default: True
+            If *True*, measure distance in pixel (screen) space, which is
+            useful for manual contour labeling; else, measure distance in axes
+            space.
+
+        Returns
+        -------
+        path : int
+            The index of the path that is closest to ``(x, y)``.  Each path corresponds
+            to one contour level.
+        subpath : int
+            The index within that closest path of the subpath that is closest to
+            ``(x, y)``.  Each subpath corresponds to one unbroken contour line.
+        index : int
+            The index of the vertices within that subpath that are closest to
+            ``(x, y)``.
+        xmin, ymin : float
+            The point in the contour plot that is closest to ``(x, y)``.
+        d2 : float
+            The squared distance from ``(xmin, ymin)`` to ``(x, y)``.
+        """
+        segment = index = d2 = None
+
+        with ExitStack() as stack:
+            if not pixel:
+                # _find_nearest_contour works in pixel space. We want axes space, so
+                # effectively disable the transformation here by setting to identity.
+                stack.enter_context(self._cm_set(
+                    transform=mtransforms.IdentityTransform()))
+
+            i_level, i_vtx, (xmin, ymin) = self._find_nearest_contour((x, y), indices)
+
+        if i_level is not None:
+            cc_cumlens = np.cumsum(
+                [*map(len, self._paths[i_level]._iter_connected_components())])
+            segment = cc_cumlens.searchsorted(i_vtx, "right")
+            index = i_vtx if segment == 0 else i_vtx - cc_cumlens[segment - 1]
+            d2 = (xmin-x)**2 + (ymin-y)**2
+
+        return (i_level, segment, index, xmin, ymin, d2)
+
+    def draw(self, renderer):
+        paths = self._paths
+        n_paths = len(paths)
+        if not self.filled or all(hatch is None for hatch in self.hatches):
+            super().draw(renderer)
+            return
+        # In presence of hatching, draw contours one at a time.
+        edgecolors = self.get_edgecolors()
+        if edgecolors.size == 0:
+            edgecolors = ("none",)
+        for idx in range(n_paths):
+            with cbook._setattr_cm(self, _paths=[paths[idx]]), self._cm_set(
+                hatch=self.hatches[idx % len(self.hatches)],
+                array=[self.get_array()[idx]],
+                linewidths=[self.get_linewidths()[idx % len(self.get_linewidths())]],
+                linestyles=[self.get_linestyles()[idx % len(self.get_linestyles())]],
+                edgecolors=edgecolors[idx % len(edgecolors)],
+            ):
+                super().draw(renderer)
+
+
+@_docstring.interpd
+class QuadContourSet(ContourSet):
+    """
+    Create and store a set of contour lines or filled regions.
+
+    This class is typically not instantiated directly by the user but by
+    `~.Axes.contour` and `~.Axes.contourf`.
+
+    %(contour_set_attributes)s
+    """
+
+    def _process_args(self, *args, corner_mask=None, algorithm=None, **kwargs):
+        """
+        Process args and kwargs.
+        """
+        if args and isinstance(args[0], QuadContourSet):
+            if self.levels is None:
+                self.levels = args[0].levels
+            self.zmin = args[0].zmin
+            self.zmax = args[0].zmax
+            self._corner_mask = args[0]._corner_mask
+            contour_generator = args[0]._contour_generator
+            self._mins = args[0]._mins
+            self._maxs = args[0]._maxs
+            self._algorithm = args[0]._algorithm
+        else:
+            import contourpy
+
+            if algorithm is None:
+                algorithm = mpl.rcParams['contour.algorithm']
+            mpl.rcParams.validate["contour.algorithm"](algorithm)
+            self._algorithm = algorithm
+
+            if corner_mask is None:
+                if self._algorithm == "mpl2005":
+                    # mpl2005 does not support corner_mask=True so if not
+                    # specifically requested then disable it.
+                    corner_mask = False
+                else:
+                    corner_mask = mpl.rcParams['contour.corner_mask']
+            self._corner_mask = corner_mask
+
+            x, y, z = self._contour_args(args, kwargs)
+
+            contour_generator = contourpy.contour_generator(
+                x, y, z, name=self._algorithm, corner_mask=self._corner_mask,
+                line_type=contourpy.LineType.SeparateCode,
+                fill_type=contourpy.FillType.OuterCode,
+                chunk_size=self.nchunk)
+
+            t = self.get_transform()
+
+            # if the transform is not trans data, and some part of it
+            # contains transData, transform the xs and ys to data coordinates
+            if (t != self.axes.transData and
+                    any(t.contains_branch_seperately(self.axes.transData))):
+                trans_to_data = t - self.axes.transData
+                pts = np.vstack([x.flat, y.flat]).T
+                transformed_pts = trans_to_data.transform(pts)
+                x = transformed_pts[..., 0]
+                y = transformed_pts[..., 1]
+
+            self._mins = [ma.min(x), ma.min(y)]
+            self._maxs = [ma.max(x), ma.max(y)]
+
+        self._contour_generator = contour_generator
+
+        return kwargs
+
+    def _contour_args(self, args, kwargs):
+        if self.filled:
+            fn = 'contourf'
+        else:
+            fn = 'contour'
+        nargs = len(args)
+
+        if 0 < nargs <= 2:
+            z, *args = args
+            z = ma.asarray(z)
+            x, y = self._initialize_x_y(z)
+        elif 2 < nargs <= 4:
+            x, y, z_orig, *args = args
+            x, y, z = self._check_xyz(x, y, z_orig, kwargs)
+
+        else:
+            raise _api.nargs_error(fn, takes="from 1 to 4", given=nargs)
+        z = ma.masked_invalid(z, copy=False)
+        self.zmax = z.max().astype(float)
+        self.zmin = z.min().astype(float)
+        if self.logscale and self.zmin <= 0:
+            z = ma.masked_where(z <= 0, z)
+            _api.warn_external('Log scale: values of z <= 0 have been masked')
+            self.zmin = z.min().astype(float)
+        self._process_contour_level_args(args, z.dtype)
+        return (x, y, z)
+
+    def _check_xyz(self, x, y, z, kwargs):
+        """
+        Check that the shapes of the input arrays match; if x and y are 1D,
+        convert them to 2D using meshgrid.
+        """
+        x, y = self.axes._process_unit_info([("x", x), ("y", y)], kwargs)
+
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        z = ma.asarray(z)
+
+        if z.ndim != 2:
+            raise TypeError(f"Input z must be 2D, not {z.ndim}D")
+        if z.shape[0] < 2 or z.shape[1] < 2:
+            raise TypeError(f"Input z must be at least a (2, 2) shaped array, "
+                            f"but has shape {z.shape}")
+        Ny, Nx = z.shape
+
+        if x.ndim != y.ndim:
+            raise TypeError(f"Number of dimensions of x ({x.ndim}) and y "
+                            f"({y.ndim}) do not match")
+        if x.ndim == 1:
+            nx, = x.shape
+            ny, = y.shape
+            if nx != Nx:
+                raise TypeError(f"Length of x ({nx}) must match number of "
+                                f"columns in z ({Nx})")
+            if ny != Ny:
+                raise TypeError(f"Length of y ({ny}) must match number of "
+                                f"rows in z ({Ny})")
+            x, y = np.meshgrid(x, y)
+        elif x.ndim == 2:
+            if x.shape != z.shape:
+                raise TypeError(
+                    f"Shapes of x {x.shape} and z {z.shape} do not match")
+            if y.shape != z.shape:
+                raise TypeError(
+                    f"Shapes of y {y.shape} and z {z.shape} do not match")
+        else:
+            raise TypeError(f"Inputs x and y must be 1D or 2D, not {x.ndim}D")
+
+        return x, y, z
+
+    def _initialize_x_y(self, z):
+        """
+        Return X, Y arrays such that contour(Z) will match imshow(Z)
+        if origin is not None.
+        The center of pixel Z[i, j] depends on origin:
+        if origin is None, x = j, y = i;
+        if origin is 'lower', x = j + 0.5, y = i + 0.5;
+        if origin is 'upper', x = j + 0.5, y = Nrows - i - 0.5
+        If extent is not None, x and y will be scaled to match,
+        as in imshow.
+        If origin is None and extent is not None, then extent
+        will give the minimum and maximum values of x and y.
+        """
+        if z.ndim != 2:
+            raise TypeError(f"Input z must be 2D, not {z.ndim}D")
+        elif z.shape[0] < 2 or z.shape[1] < 2:
+            raise TypeError(f"Input z must be at least a (2, 2) shaped array, "
+                            f"but has shape {z.shape}")
+        else:
+            Ny, Nx = z.shape
+        if self.origin is None:  # Not for image-matching.
+            if self.extent is None:
+                return np.meshgrid(np.arange(Nx), np.arange(Ny))
+            else:
+                x0, x1, y0, y1 = self.extent
+                x = np.linspace(x0, x1, Nx)
+                y = np.linspace(y0, y1, Ny)
+                return np.meshgrid(x, y)
+        # Match image behavior:
+        if self.extent is None:
+            x0, x1, y0, y1 = (0, Nx, 0, Ny)
+        else:
+            x0, x1, y0, y1 = self.extent
+        dx = (x1 - x0) / Nx
+        dy = (y1 - y0) / Ny
+        x = x0 + (np.arange(Nx) + 0.5) * dx
+        y = y0 + (np.arange(Ny) + 0.5) * dy
+        if self.origin == 'upper':
+            y = y[::-1]
+        return np.meshgrid(x, y)
+
+
+_docstring.interpd.register(contour_doc="""
+`.contour` and `.contourf` draw contour lines and filled contours,
+respectively.  Except as noted, function signatures and return values
+are the same for both versions.
+
+Parameters
+----------
+X, Y : array-like, optional
+    The coordinates of the values in *Z*.
+
+    *X* and *Y* must both be 2D with the same shape as *Z* (e.g.
+    created via `numpy.meshgrid`), or they must both be 1-D such
+    that ``len(X) == N`` is the number of columns in *Z* and
+    ``len(Y) == M`` is the number of rows in *Z*.
+
+    *X* and *Y* must both be ordered monotonically.
+
+    If not given, they are assumed to be integer indices, i.e.
+    ``X = range(N)``, ``Y = range(M)``.
+
+Z : (M, N) array-like
+    The height values over which the contour is drawn.  Color-mapping is
+    controlled by *cmap*, *norm*, *vmin*, and *vmax*.
+
+levels : int or array-like, optional
+    Determines the number and positions of the contour lines / regions.
+
+    If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries
+    to automatically choose no more than *n+1* "nice" contour levels
+    between minimum and maximum numeric values of *Z*.
+
+    If array-like, draw contour lines at the specified levels.
+    The values must be in increasing order.
+
+Returns
+-------
+`~.contour.QuadContourSet`
+
+Other Parameters
+----------------
+corner_mask : bool, default: :rc:`contour.corner_mask`
+    Enable/disable corner masking, which only has an effect if *Z* is
+    a masked array.  If ``False``, any quad touching a masked point is
+    masked out.  If ``True``, only the triangular corners of quads
+    nearest those points are always masked out, other triangular
+    corners comprising three unmasked points are contoured as usual.
+
+colors : :mpltype:`color` or list of :mpltype:`color`, optional
+    The colors of the levels, i.e. the lines for `.contour` and the
+    areas for `.contourf`.
+
+    The sequence is cycled for the levels in ascending order. If the
+    sequence is shorter than the number of levels, it's repeated.
+
+    As a shortcut, a single color may be used in place of one-element lists, i.e.
+    ``'red'`` instead of ``['red']`` to color all levels with the same color.
+
+    .. versionchanged:: 3.10
+        Previously a single color had to be expressed as a string, but now any
+        valid color format may be passed.
+
+    By default (value *None*), the colormap specified by *cmap*
+    will be used.
+
+alpha : float, default: 1
+    The alpha blending value, between 0 (transparent) and 1 (opaque).
+
+%(cmap_doc)s
+
+    This parameter is ignored if *colors* is set.
+
+%(norm_doc)s
+
+    This parameter is ignored if *colors* is set.
+
+%(vmin_vmax_doc)s
+
+    If *vmin* or *vmax* are not given, the default color scaling is based on
+    *levels*.
+
+    This parameter is ignored if *colors* is set.
+
+%(colorizer_doc)s
+
+    This parameter is ignored if *colors* is set.
+
+origin : {*None*, 'upper', 'lower', 'image'}, default: None
+    Determines the orientation and exact position of *Z* by specifying
+    the position of ``Z[0, 0]``.  This is only relevant, if *X*, *Y*
+    are not given.
+
+    - *None*: ``Z[0, 0]`` is at X=0, Y=0 in the lower left corner.
+    - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner.
+    - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left
+      corner.
+    - 'image': Use the value from :rc:`image.origin`.
+
+extent : (x0, x1, y0, y1), optional
+    If *origin* is not *None*, then *extent* is interpreted as in
+    `.imshow`: it gives the outer pixel boundaries. In this case, the
+    position of Z[0, 0] is the center of the pixel, not a corner. If
+    *origin* is *None*, then (*x0*, *y0*) is the position of Z[0, 0],
+    and (*x1*, *y1*) is the position of Z[-1, -1].
+
+    This argument is ignored if *X* and *Y* are specified in the call
+    to contour.
+
+locator : ticker.Locator subclass, optional
+    The locator is used to determine the contour levels if they
+    are not given explicitly via *levels*.
+    Defaults to `~.ticker.MaxNLocator`.
+
+extend : {'neither', 'both', 'min', 'max'}, default: 'neither'
+    Determines the ``contourf``-coloring of values that are outside the
+    *levels* range.
+
+    If 'neither', values outside the *levels* range are not colored.
+    If 'min', 'max' or 'both', color the values below, above or below
+    and above the *levels* range.
+
+    Values below ``min(levels)`` and above ``max(levels)`` are mapped
+    to the under/over values of the `.Colormap`. Note that most
+    colormaps do not have dedicated colors for these by default, so
+    that the over and under values are the edge values of the colormap.
+    You may want to set these values explicitly using
+    `.Colormap.set_under` and `.Colormap.set_over`.
+
+    .. note::
+
+        An existing `.QuadContourSet` does not get notified if
+        properties of its colormap are changed. Therefore, an explicit
+        call `~.ContourSet.changed()` is needed after modifying the
+        colormap. The explicit call can be left out, if a colorbar is
+        assigned to the `.QuadContourSet` because it internally calls
+        `~.ContourSet.changed()`.
+
+    Example::
+
+        x = np.arange(1, 10)
+        y = x.reshape(-1, 1)
+        h = x * y
+
+        cs = plt.contourf(h, levels=[10, 30, 50],
+            colors=['#808080', '#A0A0A0', '#C0C0C0'], extend='both')
+        cs.cmap.set_over('red')
+        cs.cmap.set_under('blue')
+        cs.changed()
+
+xunits, yunits : registered units, optional
+    Override axis units by specifying an instance of a
+    :class:`matplotlib.units.ConversionInterface`.
+
+antialiased : bool, optional
+    Enable antialiasing, overriding the defaults.  For
+    filled contours, the default is *False*.  For line contours,
+    it is taken from :rc:`lines.antialiased`.
+
+nchunk : int >= 0, optional
+    If 0, no subdivision of the domain.  Specify a positive integer to
+    divide the domain into subdomains of *nchunk* by *nchunk* quads.
+    Chunking reduces the maximum length of polygons generated by the
+    contouring algorithm which reduces the rendering workload passed
+    on to the backend and also requires slightly less RAM.  It can
+    however introduce rendering artifacts at chunk boundaries depending
+    on the backend, the *antialiased* flag and value of *alpha*.
+
+linewidths : float or array-like, default: :rc:`contour.linewidth`
+    *Only applies to* `.contour`.
+
+    The line width of the contour lines.
+
+    If a number, all levels will be plotted with this linewidth.
+
+    If a sequence, the levels in ascending order will be plotted with
+    the linewidths in the order specified.
+
+    If None, this falls back to :rc:`lines.linewidth`.
+
+linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional
+    *Only applies to* `.contour`.
+
+    If *linestyles* is *None*, the default is 'solid' unless the lines are
+    monochrome. In that case, negative contours will instead take their
+    linestyle from the *negative_linestyles* argument.
+
+    *linestyles* can also be an iterable of the above strings specifying a set
+    of linestyles to be used. If this iterable is shorter than the number of
+    contour levels it will be repeated as necessary.
+
+negative_linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, \
+                       optional
+    *Only applies to* `.contour`.
+
+    If *linestyles* is *None* and the lines are monochrome, this argument
+    specifies the line style for negative contours.
+
+    If *negative_linestyles* is *None*, the default is taken from
+    :rc:`contour.negative_linestyle`.
+
+    *negative_linestyles* can also be an iterable of the above strings
+    specifying a set of linestyles to be used. If this iterable is shorter than
+    the number of contour levels it will be repeated as necessary.
+
+hatches : list[str], optional
+    *Only applies to* `.contourf`.
+
+    A list of cross hatch patterns to use on the filled areas.
+    If None, no hatching will be added to the contour.
+
+algorithm : {'mpl2005', 'mpl2014', 'serial', 'threaded'}, optional
+    Which contouring algorithm to use to calculate the contour lines and
+    polygons. The algorithms are implemented in
+    `ContourPy <https://github.com/contourpy/contourpy>`_, consult the
+    `ContourPy documentation <https://contourpy.readthedocs.io>`_ for
+    further information.
+
+    The default is taken from :rc:`contour.algorithm`.
+
+clip_path : `~matplotlib.patches.Patch` or `.Path` or `.TransformedPath`
+    Set the clip path.  See `~matplotlib.artist.Artist.set_clip_path`.
+
+    .. versionadded:: 3.8
+
+data : indexable object, optional
+    DATA_PARAMETER_PLACEHOLDER
+
+Notes
+-----
+1. `.contourf` differs from the MATLAB version in that it does not draw
+   the polygon edges. To draw edges, add line contours with calls to
+   `.contour`.
+
+2. `.contourf` fills intervals that are closed at the top; that is, for
+   boundaries *z1* and *z2*, the filled region is::
+
+      z1 < Z <= z2
+
+   except for the lowest interval, which is closed on both sides (i.e.
+   it includes the lowest value).
+
+3. `.contour` and `.contourf` use a `marching squares
+   <https://en.wikipedia.org/wiki/Marching_squares>`_ algorithm to
+   compute contour locations.  More information can be found in
+   `ContourPy documentation <https://contourpy.readthedocs.io>`_.
+""" % _docstring.interpd.params)
diff --git a/lib/python3.12/site-packages/matplotlib/contour.pyi b/lib/python3.12/site-packages/matplotlib/contour.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..7400fac50993f4560c0fd76d12c530abdd286f26
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/contour.pyi
@@ -0,0 +1,140 @@
+import matplotlib.cm as cm
+from matplotlib.artist import Artist
+from matplotlib.axes import Axes
+from matplotlib.collections import Collection, PathCollection
+from matplotlib.colorizer import Colorizer, ColorizingArtist
+from matplotlib.colors import Colormap, Normalize
+from matplotlib.path import Path
+from matplotlib.patches import Patch
+from matplotlib.text import Text
+from matplotlib.transforms import Transform, TransformedPatchPath, TransformedPath
+from matplotlib.ticker import Locator, Formatter
+
+from numpy.typing import ArrayLike
+import numpy as np
+from collections.abc import Callable, Iterable, Sequence
+from typing import Literal
+from .typing import ColorType
+
+
+
+class ContourLabeler:
+    labelFmt: str | Formatter | Callable[[float], str] | dict[float, str]
+    labelManual: bool | Iterable[tuple[float, float]]
+    rightside_up: bool
+    labelLevelList: list[float]
+    labelIndiceList: list[int]
+    labelMappable: cm.ScalarMappable | ColorizingArtist
+    labelCValueList: list[ColorType]
+    labelXYs: list[tuple[float, float]]
+    def clabel(
+        self,
+        levels: ArrayLike | None = ...,
+        *,
+        fontsize: str | float | None = ...,
+        inline: bool = ...,
+        inline_spacing: float = ...,
+        fmt: str | Formatter | Callable[[float], str] | dict[float, str] | None = ...,
+        colors: ColorType | Sequence[ColorType] | None = ...,
+        use_clabeltext: bool = ...,
+        manual: bool | Iterable[tuple[float, float]] = ...,
+        rightside_up: bool = ...,
+        zorder: float | None = ...
+    ) -> list[Text]: ...
+    def print_label(self, linecontour: ArrayLike, labelwidth: float) -> bool: ...
+    def too_close(self, x: float, y: float, lw: float) -> bool: ...
+    def get_text(
+        self,
+        lev: float,
+        fmt: str | Formatter | Callable[[float], str] | dict[float, str],
+    ) -> str: ...
+    def locate_label(
+        self, linecontour: ArrayLike, labelwidth: float
+    ) -> tuple[float, float, float]: ...
+    def add_label(
+        self, x: float, y: float, rotation: float, lev: float, cvalue: ColorType
+    ) -> None: ...
+    def add_label_near(
+        self,
+        x: float,
+        y: float,
+        inline: bool = ...,
+        inline_spacing: int = ...,
+        transform: Transform | Literal[False] | None = ...,
+    ) -> None: ...
+    def pop_label(self, index: int = ...) -> None: ...
+    def labels(self, inline: bool, inline_spacing: int) -> None: ...
+    def remove(self) -> None: ...
+
+class ContourSet(ContourLabeler, Collection):
+    axes: Axes
+    levels: Iterable[float]
+    filled: bool
+    linewidths: float | ArrayLike | None
+    hatches: Iterable[str | None]
+    origin: Literal["upper", "lower", "image"] | None
+    extent: tuple[float, float, float, float] | None
+    colors: ColorType | Sequence[ColorType]
+    extend: Literal["neither", "both", "min", "max"]
+    nchunk: int
+    locator: Locator | None
+    logscale: bool
+    negative_linestyles: None | Literal[
+        "solid", "dashed", "dashdot", "dotted"
+    ] | Iterable[Literal["solid", "dashed", "dashdot", "dotted"]]
+    clip_path: Patch | Path | TransformedPath | TransformedPatchPath | None
+    labelTexts: list[Text]
+    labelCValues: list[ColorType]
+
+    @property
+    def allkinds(self) -> list[list[np.ndarray | None]]: ...
+    @property
+    def allsegs(self) -> list[list[np.ndarray]]: ...
+    @property
+    def alpha(self) -> float | None: ...
+    @property
+    def linestyles(self) -> (
+        None |
+        Literal["solid", "dashed", "dashdot", "dotted"] |
+        Iterable[Literal["solid", "dashed", "dashdot", "dotted"]]
+    ): ...
+
+    def __init__(
+        self,
+        ax: Axes,
+        *args,
+        levels: Iterable[float] | None = ...,
+        filled: bool = ...,
+        linewidths: float | ArrayLike | None = ...,
+        linestyles: Literal["solid", "dashed", "dashdot", "dotted"]
+        | Iterable[Literal["solid", "dashed", "dashdot", "dotted"]]
+        | None = ...,
+        hatches: Iterable[str | None] = ...,
+        alpha: float | None = ...,
+        origin: Literal["upper", "lower", "image"] | None = ...,
+        extent: tuple[float, float, float, float] | None = ...,
+        cmap: str | Colormap | None = ...,
+        colors: ColorType | Sequence[ColorType] | None = ...,
+        norm: str | Normalize | None = ...,
+        vmin: float | None = ...,
+        vmax: float | None = ...,
+        colorizer: Colorizer | None = ...,
+        extend: Literal["neither", "both", "min", "max"] = ...,
+        antialiased: bool | None = ...,
+        nchunk: int = ...,
+        locator: Locator | None = ...,
+        transform: Transform | None = ...,
+        negative_linestyles: Literal["solid", "dashed", "dashdot", "dotted"]
+        | Iterable[Literal["solid", "dashed", "dashdot", "dotted"]]
+        | None = ...,
+        clip_path: Patch | Path | TransformedPath | TransformedPatchPath | None = ...,
+        **kwargs
+    ) -> None: ...
+    def legend_elements(
+        self, variable_name: str = ..., str_format: Callable[[float], str] = ...
+    ) -> tuple[list[Artist], list[str]]: ...
+    def find_nearest_contour(
+        self, x: float, y: float, indices: Iterable[int] | None = ..., pixel: bool = ...
+    ) -> tuple[int, int, int, float, float, float]: ...
+
+class QuadContourSet(ContourSet): ...
diff --git a/lib/python3.12/site-packages/matplotlib/dates.py b/lib/python3.12/site-packages/matplotlib/dates.py
new file mode 100644
index 0000000000000000000000000000000000000000..511e1c6df6ccbd8747c76f297e0a6c20947cda3a
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/dates.py
@@ -0,0 +1,1840 @@
+"""
+Matplotlib provides sophisticated date plotting capabilities, standing on the
+shoulders of python :mod:`datetime` and the add-on module dateutil_.
+
+By default, Matplotlib uses the units machinery described in
+`~matplotlib.units` to convert `datetime.datetime`, and `numpy.datetime64`
+objects when plotted on an x- or y-axis. The user does not
+need to do anything for dates to be formatted, but dates often have strict
+formatting needs, so this module provides many tick locators and formatters.
+A basic example using `numpy.datetime64` is::
+
+    import numpy as np
+
+    times = np.arange(np.datetime64('2001-01-02'),
+                      np.datetime64('2002-02-03'), np.timedelta64(75, 'm'))
+    y = np.random.randn(len(times))
+
+    fig, ax = plt.subplots()
+    ax.plot(times, y)
+
+.. seealso::
+
+    - :doc:`/gallery/text_labels_and_annotations/date`
+    - :doc:`/gallery/ticks/date_concise_formatter`
+    - :doc:`/gallery/ticks/date_demo_convert`
+
+.. _date-format:
+
+Matplotlib date format
+----------------------
+
+Matplotlib represents dates using floating point numbers specifying the number
+of days since a default epoch of 1970-01-01 UTC; for example,
+1970-01-01, 06:00 is the floating point number 0.25. The formatters and
+locators require the use of `datetime.datetime` objects, so only dates between
+year 0001 and 9999 can be represented.  Microsecond precision
+is achievable for (approximately) 70 years on either side of the epoch, and
+20 microseconds for the rest of the allowable range of dates (year 0001 to
+9999). The epoch can be changed at import time via `.dates.set_epoch` or
+:rc:`date.epoch` to other dates if necessary; see
+:doc:`/gallery/ticks/date_precision_and_epochs` for a discussion.
+
+.. note::
+
+   Before Matplotlib 3.3, the epoch was 0000-12-31 which lost modern
+   microsecond precision and also made the default axis limit of 0 an invalid
+   datetime.  In 3.3 the epoch was changed as above.  To convert old
+   ordinal floats to the new epoch, users can do::
+
+     new_ordinal = old_ordinal + mdates.date2num(np.datetime64('0000-12-31'))
+
+
+There are a number of helper functions to convert between :mod:`datetime`
+objects and Matplotlib dates:
+
+.. currentmodule:: matplotlib.dates
+
+.. autosummary::
+   :nosignatures:
+
+   datestr2num
+   date2num
+   num2date
+   num2timedelta
+   drange
+   set_epoch
+   get_epoch
+
+.. note::
+
+   Like Python's `datetime.datetime`, Matplotlib uses the Gregorian calendar
+   for all conversions between dates and floating point numbers. This practice
+   is not universal, and calendar differences can cause confusing
+   differences between what Python and Matplotlib give as the number of days
+   since 0001-01-01 and what other software and databases yield.  For
+   example, the US Naval Observatory uses a calendar that switches
+   from Julian to Gregorian in October, 1582.  Hence, using their
+   calculator, the number of days between 0001-01-01 and 2006-04-01 is
+   732403, whereas using the Gregorian calendar via the datetime
+   module we find::
+
+     In [1]: date(2006, 4, 1).toordinal() - date(1, 1, 1).toordinal()
+     Out[1]: 732401
+
+All the Matplotlib date converters, locators and formatters are timezone aware.
+If no explicit timezone is provided, :rc:`timezone` is assumed, provided as a
+string.  If you want to use a different timezone, pass the *tz* keyword
+argument of `num2date` to any date tick locators or formatters you create. This
+can be either a `datetime.tzinfo` instance or a string with the timezone name
+that can be parsed by `~dateutil.tz.gettz`.
+
+A wide range of specific and general purpose date tick locators and
+formatters are provided in this module.  See
+:mod:`matplotlib.ticker` for general information on tick locators
+and formatters.  These are described below.
+
+The dateutil_ module provides additional code to handle date ticking, making it
+easy to place ticks on any kinds of dates.  See examples below.
+
+.. _dateutil: https://dateutil.readthedocs.io
+
+.. _date-locators:
+
+Date tick locators
+------------------
+
+Most of the date tick locators can locate single or multiple ticks. For example::
+
+    # import constants for the days of the week
+    from matplotlib.dates import MO, TU, WE, TH, FR, SA, SU
+
+    # tick on Mondays every week
+    loc = WeekdayLocator(byweekday=MO, tz=tz)
+
+    # tick on Mondays and Saturdays
+    loc = WeekdayLocator(byweekday=(MO, SA))
+
+In addition, most of the constructors take an interval argument::
+
+    # tick on Mondays every second week
+    loc = WeekdayLocator(byweekday=MO, interval=2)
+
+The rrule locator allows completely general date ticking::
+
+    # tick every 5th easter
+    rule = rrulewrapper(YEARLY, byeaster=1, interval=5)
+    loc = RRuleLocator(rule)
+
+The available date tick locators are:
+
+* `MicrosecondLocator`: Locate microseconds.
+
+* `SecondLocator`: Locate seconds.
+
+* `MinuteLocator`: Locate minutes.
+
+* `HourLocator`: Locate hours.
+
+* `DayLocator`: Locate specified days of the month.
+
+* `WeekdayLocator`: Locate days of the week, e.g., MO, TU.
+
+* `MonthLocator`: Locate months, e.g., 7 for July.
+
+* `YearLocator`: Locate years that are multiples of base.
+
+* `RRuleLocator`: Locate using a `rrulewrapper`.
+  `rrulewrapper` is a simple wrapper around dateutil_'s `dateutil.rrule`
+  which allow almost arbitrary date tick specifications.
+  See :doc:`rrule example </gallery/ticks/date_demo_rrule>`.
+
+* `AutoDateLocator`: On autoscale, this class picks the best `DateLocator`
+  (e.g., `RRuleLocator`) to set the view limits and the tick locations.  If
+  called with ``interval_multiples=True`` it will make ticks line up with
+  sensible multiples of the tick intervals.  For example, if the interval is
+  4 hours, it will pick hours 0, 4, 8, etc. as ticks.  This behaviour is not
+  guaranteed by default.
+
+.. _date-formatters:
+
+Date formatters
+---------------
+
+The available date formatters are:
+
+* `AutoDateFormatter`: attempts to figure out the best format to use.  This is
+  most useful when used with the `AutoDateLocator`.
+
+* `ConciseDateFormatter`: also attempts to figure out the best format to use,
+  and to make the format as compact as possible while still having complete
+  date information.  This is most useful when used with the `AutoDateLocator`.
+
+* `DateFormatter`: use `~datetime.datetime.strftime` format strings.
+"""
+
+import datetime
+import functools
+import logging
+import re
+
+from dateutil.rrule import (rrule, MO, TU, WE, TH, FR, SA, SU, YEARLY,
+                            MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY,
+                            SECONDLY)
+from dateutil.relativedelta import relativedelta
+import dateutil.parser
+import dateutil.tz
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib import _api, cbook, ticker, units
+
+__all__ = ('datestr2num', 'date2num', 'num2date', 'num2timedelta', 'drange',
+           'set_epoch', 'get_epoch', 'DateFormatter', 'ConciseDateFormatter',
+           'AutoDateFormatter', 'DateLocator', 'RRuleLocator',
+           'AutoDateLocator', 'YearLocator', 'MonthLocator', 'WeekdayLocator',
+           'DayLocator', 'HourLocator', 'MinuteLocator',
+           'SecondLocator', 'MicrosecondLocator',
+           'rrule', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU',
+           'YEARLY', 'MONTHLY', 'WEEKLY', 'DAILY',
+           'HOURLY', 'MINUTELY', 'SECONDLY', 'MICROSECONDLY', 'relativedelta',
+           'DateConverter', 'ConciseDateConverter', 'rrulewrapper')
+
+
+_log = logging.getLogger(__name__)
+UTC = datetime.timezone.utc
+
+
+def _get_tzinfo(tz=None):
+    """
+    Generate `~datetime.tzinfo` from a string or return `~datetime.tzinfo`.
+    If None, retrieve the preferred timezone from the rcParams dictionary.
+    """
+    tz = mpl._val_or_rc(tz, 'timezone')
+    if tz == 'UTC':
+        return UTC
+    if isinstance(tz, str):
+        tzinfo = dateutil.tz.gettz(tz)
+        if tzinfo is None:
+            raise ValueError(f"{tz} is not a valid timezone as parsed by"
+                             " dateutil.tz.gettz.")
+        return tzinfo
+    if isinstance(tz, datetime.tzinfo):
+        return tz
+    raise TypeError(f"tz must be string or tzinfo subclass, not {tz!r}.")
+
+
+# Time-related constants.
+EPOCH_OFFSET = float(datetime.datetime(1970, 1, 1).toordinal())
+# EPOCH_OFFSET is not used by matplotlib
+MICROSECONDLY = SECONDLY + 1
+HOURS_PER_DAY = 24.
+MIN_PER_HOUR = 60.
+SEC_PER_MIN = 60.
+MONTHS_PER_YEAR = 12.
+
+DAYS_PER_WEEK = 7.
+DAYS_PER_MONTH = 30.
+DAYS_PER_YEAR = 365.0
+
+MINUTES_PER_DAY = MIN_PER_HOUR * HOURS_PER_DAY
+
+SEC_PER_HOUR = SEC_PER_MIN * MIN_PER_HOUR
+SEC_PER_DAY = SEC_PER_HOUR * HOURS_PER_DAY
+SEC_PER_WEEK = SEC_PER_DAY * DAYS_PER_WEEK
+
+MUSECONDS_PER_DAY = 1e6 * SEC_PER_DAY
+
+MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY = (
+    MO, TU, WE, TH, FR, SA, SU)
+WEEKDAYS = (MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY)
+
+# default epoch: passed to np.datetime64...
+_epoch = None
+
+
+def _reset_epoch_test_example():
+    """
+    Reset the Matplotlib date epoch so it can be set again.
+
+    Only for use in tests and examples.
+    """
+    global _epoch
+    _epoch = None
+
+
+def set_epoch(epoch):
+    """
+    Set the epoch (origin for dates) for datetime calculations.
+
+    The default epoch is :rc:`date.epoch`.
+
+    If microsecond accuracy is desired, the date being plotted needs to be
+    within approximately 70 years of the epoch. Matplotlib internally
+    represents dates as days since the epoch, so floating point dynamic
+    range needs to be within a factor of 2^52.
+
+    `~.dates.set_epoch` must be called before any dates are converted
+    (i.e. near the import section) or a RuntimeError will be raised.
+
+    See also :doc:`/gallery/ticks/date_precision_and_epochs`.
+
+    Parameters
+    ----------
+    epoch : str
+        valid UTC date parsable by `numpy.datetime64` (do not include
+        timezone).
+
+    """
+    global _epoch
+    if _epoch is not None:
+        raise RuntimeError('set_epoch must be called before dates plotted.')
+    _epoch = epoch
+
+
+def get_epoch():
+    """
+    Get the epoch used by `.dates`.
+
+    Returns
+    -------
+    epoch : str
+        String for the epoch (parsable by `numpy.datetime64`).
+    """
+    global _epoch
+
+    _epoch = mpl._val_or_rc(_epoch, 'date.epoch')
+    return _epoch
+
+
+def _dt64_to_ordinalf(d):
+    """
+    Convert `numpy.datetime64` or an `numpy.ndarray` of those types to
+    Gregorian date as UTC float relative to the epoch (see `.get_epoch`).
+    Roundoff is float64 precision.  Practically: microseconds for dates
+    between 290301 BC, 294241 AD, milliseconds for larger dates
+    (see `numpy.datetime64`).
+    """
+
+    # the "extra" ensures that we at least allow the dynamic range out to
+    # seconds.  That should get out to +/-2e11 years.
+    dseconds = d.astype('datetime64[s]')
+    extra = (d - dseconds).astype('timedelta64[ns]')
+    t0 = np.datetime64(get_epoch(), 's')
+    dt = (dseconds - t0).astype(np.float64)
+    dt += extra.astype(np.float64) / 1.0e9
+    dt = dt / SEC_PER_DAY
+
+    NaT_int = np.datetime64('NaT').astype(np.int64)
+    d_int = d.astype(np.int64)
+    dt[d_int == NaT_int] = np.nan
+    return dt
+
+
+def _from_ordinalf(x, tz=None):
+    """
+    Convert Gregorian float of the date, preserving hours, minutes,
+    seconds and microseconds.  Return value is a `.datetime`.
+
+    The input date *x* is a float in ordinal days at UTC, and the output will
+    be the specified `.datetime` object corresponding to that time in
+    timezone *tz*, or if *tz* is ``None``, in the timezone specified in
+    :rc:`timezone`.
+    """
+
+    tz = _get_tzinfo(tz)
+
+    dt = (np.datetime64(get_epoch()) +
+          np.timedelta64(int(np.round(x * MUSECONDS_PER_DAY)), 'us'))
+    if dt < np.datetime64('0001-01-01') or dt >= np.datetime64('10000-01-01'):
+        raise ValueError(f'Date ordinal {x} converts to {dt} (using '
+                         f'epoch {get_epoch()}), but Matplotlib dates must be '
+                          'between year 0001 and 9999.')
+    # convert from datetime64 to datetime:
+    dt = dt.tolist()
+
+    # datetime64 is always UTC:
+    dt = dt.replace(tzinfo=dateutil.tz.gettz('UTC'))
+    # but maybe we are working in a different timezone so move.
+    dt = dt.astimezone(tz)
+    # fix round off errors
+    if np.abs(x) > 70 * 365:
+        # if x is big, round off to nearest twenty microseconds.
+        # This avoids floating point roundoff error
+        ms = round(dt.microsecond / 20) * 20
+        if ms == 1000000:
+            dt = dt.replace(microsecond=0) + datetime.timedelta(seconds=1)
+        else:
+            dt = dt.replace(microsecond=ms)
+
+    return dt
+
+
+# a version of _from_ordinalf that can operate on numpy arrays
+_from_ordinalf_np_vectorized = np.vectorize(_from_ordinalf, otypes="O")
+# a version of dateutil.parser.parse that can operate on numpy arrays
+_dateutil_parser_parse_np_vectorized = np.vectorize(dateutil.parser.parse)
+
+
+def datestr2num(d, default=None):
+    """
+    Convert a date string to a datenum using `dateutil.parser.parse`.
+
+    Parameters
+    ----------
+    d : str or sequence of str
+        The dates to convert.
+
+    default : datetime.datetime, optional
+        The default date to use when fields are missing in *d*.
+    """
+    if isinstance(d, str):
+        dt = dateutil.parser.parse(d, default=default)
+        return date2num(dt)
+    else:
+        if default is not None:
+            d = [date2num(dateutil.parser.parse(s, default=default))
+                 for s in d]
+            return np.asarray(d)
+        d = np.asarray(d)
+        if not d.size:
+            return d
+        return date2num(_dateutil_parser_parse_np_vectorized(d))
+
+
+def date2num(d):
+    """
+    Convert datetime objects to Matplotlib dates.
+
+    Parameters
+    ----------
+    d : `datetime.datetime` or `numpy.datetime64` or sequences of these
+
+    Returns
+    -------
+    float or sequence of floats
+        Number of days since the epoch.  See `.get_epoch` for the
+        epoch, which can be changed by :rc:`date.epoch` or `.set_epoch`.  If
+        the epoch is "1970-01-01T00:00:00" (default) then noon Jan 1 1970
+        ("1970-01-01T12:00:00") returns 0.5.
+
+    Notes
+    -----
+    The Gregorian calendar is assumed; this is not universal practice.
+    For details see the module docstring.
+    """
+    # Unpack in case of e.g. Pandas or xarray object
+    d = cbook._unpack_to_numpy(d)
+
+    # make an iterable, but save state to unpack later:
+    iterable = np.iterable(d)
+    if not iterable:
+        d = [d]
+
+    masked = np.ma.is_masked(d)
+    mask = np.ma.getmask(d)
+    d = np.asarray(d)
+
+    # convert to datetime64 arrays, if not already:
+    if not np.issubdtype(d.dtype, np.datetime64):
+        # datetime arrays
+        if not d.size:
+            # deals with an empty array...
+            return d
+        tzi = getattr(d[0], 'tzinfo', None)
+        if tzi is not None:
+            # make datetime naive:
+            d = [dt.astimezone(UTC).replace(tzinfo=None) for dt in d]
+            d = np.asarray(d)
+        d = d.astype('datetime64[us]')
+
+    d = np.ma.masked_array(d, mask=mask) if masked else d
+    d = _dt64_to_ordinalf(d)
+
+    return d if iterable else d[0]
+
+
+def num2date(x, tz=None):
+    """
+    Convert Matplotlib dates to `~datetime.datetime` objects.
+
+    Parameters
+    ----------
+    x : float or sequence of floats
+        Number of days (fraction part represents hours, minutes, seconds)
+        since the epoch.  See `.get_epoch` for the
+        epoch, which can be changed by :rc:`date.epoch` or `.set_epoch`.
+    tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+        Timezone of *x*. If a string, *tz* is passed to `dateutil.tz`.
+
+    Returns
+    -------
+    `~datetime.datetime` or sequence of `~datetime.datetime`
+        Dates are returned in timezone *tz*.
+
+        If *x* is a sequence, a sequence of `~datetime.datetime` objects will
+        be returned.
+
+    Notes
+    -----
+    The Gregorian calendar is assumed; this is not universal practice.
+    For details, see the module docstring.
+    """
+    tz = _get_tzinfo(tz)
+    return _from_ordinalf_np_vectorized(x, tz).tolist()
+
+
+_ordinalf_to_timedelta_np_vectorized = np.vectorize(
+    lambda x: datetime.timedelta(days=x), otypes="O")
+
+
+def num2timedelta(x):
+    """
+    Convert number of days to a `~datetime.timedelta` object.
+
+    If *x* is a sequence, a sequence of `~datetime.timedelta` objects will
+    be returned.
+
+    Parameters
+    ----------
+    x : float, sequence of floats
+        Number of days. The fraction part represents hours, minutes, seconds.
+
+    Returns
+    -------
+    `datetime.timedelta` or list[`datetime.timedelta`]
+    """
+    return _ordinalf_to_timedelta_np_vectorized(x).tolist()
+
+
+def drange(dstart, dend, delta):
+    """
+    Return a sequence of equally spaced Matplotlib dates.
+
+    The dates start at *dstart* and reach up to, but not including *dend*.
+    They are spaced by *delta*.
+
+    Parameters
+    ----------
+    dstart, dend : `~datetime.datetime`
+        The date limits.
+    delta : `datetime.timedelta`
+        Spacing of the dates.
+
+    Returns
+    -------
+    `numpy.array`
+        A list floats representing Matplotlib dates.
+
+    """
+    f1 = date2num(dstart)
+    f2 = date2num(dend)
+    step = delta.total_seconds() / SEC_PER_DAY
+
+    # calculate the difference between dend and dstart in times of delta
+    num = int(np.ceil((f2 - f1) / step))
+
+    # calculate end of the interval which will be generated
+    dinterval_end = dstart + num * delta
+
+    # ensure, that an half open interval will be generated [dstart, dend)
+    if dinterval_end >= dend:
+        # if the endpoint is greater than or equal to dend,
+        # just subtract one delta
+        dinterval_end -= delta
+        num -= 1
+
+    f2 = date2num(dinterval_end)  # new float-endpoint
+    return np.linspace(f1, f2, num + 1)
+
+
+def _wrap_in_tex(text):
+    p = r'([a-zA-Z]+)'
+    ret_text = re.sub(p, r'}$\1$\\mathdefault{', text)
+
+    # Braces ensure symbols are not spaced like binary operators.
+    ret_text = ret_text.replace('-', '{-}').replace(':', '{:}')
+    # To not concatenate space between numbers.
+    ret_text = ret_text.replace(' ', r'\;')
+    ret_text = '$\\mathdefault{' + ret_text + '}$'
+    ret_text = ret_text.replace('$\\mathdefault{}$', '')
+    return ret_text
+
+
+## date tick locators and formatters ###
+
+
+class DateFormatter(ticker.Formatter):
+    """
+    Format a tick (in days since the epoch) with a
+    `~datetime.datetime.strftime` format string.
+    """
+
+    def __init__(self, fmt, tz=None, *, usetex=None):
+        """
+        Parameters
+        ----------
+        fmt : str
+            `~datetime.datetime.strftime` format string
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        usetex : bool, default: :rc:`text.usetex`
+            To enable/disable the use of TeX's math mode for rendering the
+            results of the formatter.
+        """
+        self.tz = _get_tzinfo(tz)
+        self.fmt = fmt
+        self._usetex = mpl._val_or_rc(usetex, 'text.usetex')
+
+    def __call__(self, x, pos=0):
+        result = num2date(x, self.tz).strftime(self.fmt)
+        return _wrap_in_tex(result) if self._usetex else result
+
+    def set_tzinfo(self, tz):
+        self.tz = _get_tzinfo(tz)
+
+
+class ConciseDateFormatter(ticker.Formatter):
+    """
+    A `.Formatter` which attempts to figure out the best format to use for the
+    date, and to make it as compact as possible, but still be complete. This is
+    most useful when used with the `AutoDateLocator`::
+
+    >>> locator = AutoDateLocator()
+    >>> formatter = ConciseDateFormatter(locator)
+
+    Parameters
+    ----------
+    locator : `.ticker.Locator`
+        Locator that this axis is using.
+
+    tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+        Ticks timezone, passed to `.dates.num2date`.
+
+    formats : list of 6 strings, optional
+        Format strings for 6 levels of tick labelling: mostly years,
+        months, days, hours, minutes, and seconds.  Strings use
+        the same format codes as `~datetime.datetime.strftime`.  Default is
+        ``['%Y', '%b', '%d', '%H:%M', '%H:%M', '%S.%f']``
+
+    zero_formats : list of 6 strings, optional
+        Format strings for tick labels that are "zeros" for a given tick
+        level.  For instance, if most ticks are months, ticks around 1 Jan 2005
+        will be labeled "Dec", "2005", "Feb".  The default is
+        ``['', '%Y', '%b', '%b-%d', '%H:%M', '%H:%M']``
+
+    offset_formats : list of 6 strings, optional
+        Format strings for the 6 levels that is applied to the "offset"
+        string found on the right side of an x-axis, or top of a y-axis.
+        Combined with the tick labels this should completely specify the
+        date.  The default is::
+
+            ['', '%Y', '%Y-%b', '%Y-%b-%d', '%Y-%b-%d', '%Y-%b-%d %H:%M']
+
+    show_offset : bool, default: True
+        Whether to show the offset or not.
+
+    usetex : bool, default: :rc:`text.usetex`
+        To enable/disable the use of TeX's math mode for rendering the results
+        of the formatter.
+
+    Examples
+    --------
+    See :doc:`/gallery/ticks/date_concise_formatter`
+
+    .. plot::
+
+        import datetime
+        import matplotlib.dates as mdates
+
+        base = datetime.datetime(2005, 2, 1)
+        dates = np.array([base + datetime.timedelta(hours=(2 * i))
+                          for i in range(732)])
+        N = len(dates)
+        np.random.seed(19680801)
+        y = np.cumsum(np.random.randn(N))
+
+        fig, ax = plt.subplots(constrained_layout=True)
+        locator = mdates.AutoDateLocator()
+        formatter = mdates.ConciseDateFormatter(locator)
+        ax.xaxis.set_major_locator(locator)
+        ax.xaxis.set_major_formatter(formatter)
+
+        ax.plot(dates, y)
+        ax.set_title('Concise Date Formatter')
+
+    """
+
+    def __init__(self, locator, tz=None, formats=None, offset_formats=None,
+                 zero_formats=None, show_offset=True, *, usetex=None):
+        """
+        Autoformat the date labels.  The default format is used to form an
+        initial string, and then redundant elements are removed.
+        """
+        self._locator = locator
+        self._tz = tz
+        self.defaultfmt = '%Y'
+        # there are 6 levels with each level getting a specific format
+        # 0: mostly years,  1: months,  2: days,
+        # 3: hours, 4: minutes, 5: seconds
+        if formats:
+            if len(formats) != 6:
+                raise ValueError('formats argument must be a list of '
+                                 '6 format strings (or None)')
+            self.formats = formats
+        else:
+            self.formats = ['%Y',  # ticks are mostly years
+                            '%b',          # ticks are mostly months
+                            '%d',          # ticks are mostly days
+                            '%H:%M',       # hrs
+                            '%H:%M',       # min
+                            '%S.%f',       # secs
+                            ]
+        # fmt for zeros ticks at this level.  These are
+        # ticks that should be labeled w/ info the level above.
+        # like 1 Jan can just be labelled "Jan".  02:02:00 can
+        # just be labeled 02:02.
+        if zero_formats:
+            if len(zero_formats) != 6:
+                raise ValueError('zero_formats argument must be a list of '
+                                 '6 format strings (or None)')
+            self.zero_formats = zero_formats
+        elif formats:
+            # use the users formats for the zero tick formats
+            self.zero_formats = [''] + self.formats[:-1]
+        else:
+            # make the defaults a bit nicer:
+            self.zero_formats = [''] + self.formats[:-1]
+            self.zero_formats[3] = '%b-%d'
+
+        if offset_formats:
+            if len(offset_formats) != 6:
+                raise ValueError('offset_formats argument must be a list of '
+                                 '6 format strings (or None)')
+            self.offset_formats = offset_formats
+        else:
+            self.offset_formats = ['',
+                                   '%Y',
+                                   '%Y-%b',
+                                   '%Y-%b-%d',
+                                   '%Y-%b-%d',
+                                   '%Y-%b-%d %H:%M']
+        self.offset_string = ''
+        self.show_offset = show_offset
+        self._usetex = mpl._val_or_rc(usetex, 'text.usetex')
+
+    def __call__(self, x, pos=None):
+        formatter = DateFormatter(self.defaultfmt, self._tz,
+                                  usetex=self._usetex)
+        return formatter(x, pos=pos)
+
+    def format_ticks(self, values):
+        tickdatetime = [num2date(value, tz=self._tz) for value in values]
+        tickdate = np.array([tdt.timetuple()[:6] for tdt in tickdatetime])
+
+        # basic algorithm:
+        # 1) only display a part of the date if it changes over the ticks.
+        # 2) don't display the smaller part of the date if:
+        #    it is always the same or if it is the start of the
+        #    year, month, day etc.
+        # fmt for most ticks at this level
+        fmts = self.formats
+        # format beginnings of days, months, years, etc.
+        zerofmts = self.zero_formats
+        # offset fmt are for the offset in the upper left of the
+        # or lower right of the axis.
+        offsetfmts = self.offset_formats
+        show_offset = self.show_offset
+
+        # determine the level we will label at:
+        # mostly 0: years,  1: months,  2: days,
+        # 3: hours, 4: minutes, 5: seconds, 6: microseconds
+        for level in range(5, -1, -1):
+            unique = np.unique(tickdate[:, level])
+            if len(unique) > 1:
+                # if 1 is included in unique, the year is shown in ticks
+                if level < 2 and np.any(unique == 1):
+                    show_offset = False
+                break
+            elif level == 0:
+                # all tickdate are the same, so only micros might be different
+                # set to the most precise (6: microseconds doesn't exist...)
+                level = 5
+
+        # level is the basic level we will label at.
+        # now loop through and decide the actual ticklabels
+        zerovals = [0, 1, 1, 0, 0, 0, 0]
+        labels = [''] * len(tickdate)
+        for nn in range(len(tickdate)):
+            if level < 5:
+                if tickdate[nn][level] == zerovals[level]:
+                    fmt = zerofmts[level]
+                else:
+                    fmt = fmts[level]
+            else:
+                # special handling for seconds + microseconds
+                if (tickdatetime[nn].second == tickdatetime[nn].microsecond
+                        == 0):
+                    fmt = zerofmts[level]
+                else:
+                    fmt = fmts[level]
+            labels[nn] = tickdatetime[nn].strftime(fmt)
+
+        # special handling of seconds and microseconds:
+        # strip extra zeros and decimal if possible.
+        # this is complicated by two factors.  1) we have some level-4 strings
+        # here (i.e. 03:00, '0.50000', '1.000') 2) we would like to have the
+        # same number of decimals for each string (i.e. 0.5 and 1.0).
+        if level >= 5:
+            trailing_zeros = min(
+                (len(s) - len(s.rstrip('0')) for s in labels if '.' in s),
+                default=None)
+            if trailing_zeros:
+                for nn in range(len(labels)):
+                    if '.' in labels[nn]:
+                        labels[nn] = labels[nn][:-trailing_zeros].rstrip('.')
+
+        if show_offset:
+            # set the offset string:
+            if (self._locator.axis and
+                    self._locator.axis.__name__ in ('xaxis', 'yaxis')
+                    and self._locator.axis.get_inverted()):
+                self.offset_string = tickdatetime[0].strftime(offsetfmts[level])
+            else:
+                self.offset_string = tickdatetime[-1].strftime(offsetfmts[level])
+            if self._usetex:
+                self.offset_string = _wrap_in_tex(self.offset_string)
+        else:
+            self.offset_string = ''
+
+        if self._usetex:
+            return [_wrap_in_tex(l) for l in labels]
+        else:
+            return labels
+
+    def get_offset(self):
+        return self.offset_string
+
+    def format_data_short(self, value):
+        return num2date(value, tz=self._tz).strftime('%Y-%m-%d %H:%M:%S')
+
+
+class AutoDateFormatter(ticker.Formatter):
+    """
+    A `.Formatter` which attempts to figure out the best format to use.  This
+    is most useful when used with the `AutoDateLocator`.
+
+    `.AutoDateFormatter` has a ``.scale`` dictionary that maps tick scales (the
+    interval in days between one major tick) to format strings; this dictionary
+    defaults to ::
+
+        self.scaled = {
+            DAYS_PER_YEAR: rcParams['date.autoformatter.year'],
+            DAYS_PER_MONTH: rcParams['date.autoformatter.month'],
+            1: rcParams['date.autoformatter.day'],
+            1 / HOURS_PER_DAY: rcParams['date.autoformatter.hour'],
+            1 / MINUTES_PER_DAY: rcParams['date.autoformatter.minute'],
+            1 / SEC_PER_DAY: rcParams['date.autoformatter.second'],
+            1 / MUSECONDS_PER_DAY: rcParams['date.autoformatter.microsecond'],
+        }
+
+    The formatter uses the format string corresponding to the lowest key in
+    the dictionary that is greater or equal to the current scale.  Dictionary
+    entries can be customized::
+
+        locator = AutoDateLocator()
+        formatter = AutoDateFormatter(locator)
+        formatter.scaled[1/(24*60)] = '%M:%S' # only show min and sec
+
+    Custom callables can also be used instead of format strings.  The following
+    example shows how to use a custom format function to strip trailing zeros
+    from decimal seconds and adds the date to the first ticklabel::
+
+        def my_format_function(x, pos=None):
+            x = matplotlib.dates.num2date(x)
+            if pos == 0:
+                fmt = '%D %H:%M:%S.%f'
+            else:
+                fmt = '%H:%M:%S.%f'
+            label = x.strftime(fmt)
+            label = label.rstrip("0")
+            label = label.rstrip(".")
+            return label
+
+        formatter.scaled[1/(24*60)] = my_format_function
+    """
+
+    # This can be improved by providing some user-level direction on
+    # how to choose the best format (precedence, etc.).
+
+    # Perhaps a 'struct' that has a field for each time-type where a
+    # zero would indicate "don't show" and a number would indicate
+    # "show" with some sort of priority.  Same priorities could mean
+    # show all with the same priority.
+
+    # Or more simply, perhaps just a format string for each
+    # possibility...
+
+    def __init__(self, locator, tz=None, defaultfmt='%Y-%m-%d', *,
+                 usetex=None):
+        """
+        Autoformat the date labels.
+
+        Parameters
+        ----------
+        locator : `.ticker.Locator`
+            Locator that this axis is using.
+
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+
+        defaultfmt : str
+            The default format to use if none of the values in ``self.scaled``
+            are greater than the unit returned by ``locator._get_unit()``.
+
+        usetex : bool, default: :rc:`text.usetex`
+            To enable/disable the use of TeX's math mode for rendering the
+            results of the formatter. If any entries in ``self.scaled`` are set
+            as functions, then it is up to the customized function to enable or
+            disable TeX's math mode itself.
+        """
+        self._locator = locator
+        self._tz = tz
+        self.defaultfmt = defaultfmt
+        self._formatter = DateFormatter(self.defaultfmt, tz)
+        rcParams = mpl.rcParams
+        self._usetex = mpl._val_or_rc(usetex, 'text.usetex')
+        self.scaled = {
+            DAYS_PER_YEAR: rcParams['date.autoformatter.year'],
+            DAYS_PER_MONTH: rcParams['date.autoformatter.month'],
+            1: rcParams['date.autoformatter.day'],
+            1 / HOURS_PER_DAY: rcParams['date.autoformatter.hour'],
+            1 / MINUTES_PER_DAY: rcParams['date.autoformatter.minute'],
+            1 / SEC_PER_DAY: rcParams['date.autoformatter.second'],
+            1 / MUSECONDS_PER_DAY: rcParams['date.autoformatter.microsecond']
+        }
+
+    def _set_locator(self, locator):
+        self._locator = locator
+
+    def __call__(self, x, pos=None):
+        try:
+            locator_unit_scale = float(self._locator._get_unit())
+        except AttributeError:
+            locator_unit_scale = 1
+        # Pick the first scale which is greater than the locator unit.
+        fmt = next((fmt for scale, fmt in sorted(self.scaled.items())
+                    if scale >= locator_unit_scale),
+                   self.defaultfmt)
+
+        if isinstance(fmt, str):
+            self._formatter = DateFormatter(fmt, self._tz, usetex=self._usetex)
+            result = self._formatter(x, pos)
+        elif callable(fmt):
+            result = fmt(x, pos)
+        else:
+            raise TypeError(f'Unexpected type passed to {self!r}.')
+
+        return result
+
+
+class rrulewrapper:
+    """
+    A simple wrapper around a `dateutil.rrule` allowing flexible
+    date tick specifications.
+    """
+    def __init__(self, freq, tzinfo=None, **kwargs):
+        """
+        Parameters
+        ----------
+        freq : {YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY}
+            Tick frequency. These constants are defined in `dateutil.rrule`,
+            but they are accessible from `matplotlib.dates` as well.
+        tzinfo : `datetime.tzinfo`, optional
+            Time zone information. The default is None.
+        **kwargs
+            Additional keyword arguments are passed to the `dateutil.rrule`.
+        """
+        kwargs['freq'] = freq
+        self._base_tzinfo = tzinfo
+
+        self._update_rrule(**kwargs)
+
+    def set(self, **kwargs):
+        """Set parameters for an existing wrapper."""
+        self._construct.update(kwargs)
+
+        self._update_rrule(**self._construct)
+
+    def _update_rrule(self, **kwargs):
+        tzinfo = self._base_tzinfo
+
+        # rrule does not play nicely with timezones - especially pytz time
+        # zones, it's best to use naive zones and attach timezones once the
+        # datetimes are returned
+        if 'dtstart' in kwargs:
+            dtstart = kwargs['dtstart']
+            if dtstart.tzinfo is not None:
+                if tzinfo is None:
+                    tzinfo = dtstart.tzinfo
+                else:
+                    dtstart = dtstart.astimezone(tzinfo)
+
+                kwargs['dtstart'] = dtstart.replace(tzinfo=None)
+
+        if 'until' in kwargs:
+            until = kwargs['until']
+            if until.tzinfo is not None:
+                if tzinfo is not None:
+                    until = until.astimezone(tzinfo)
+                else:
+                    raise ValueError('until cannot be aware if dtstart '
+                                     'is naive and tzinfo is None')
+
+                kwargs['until'] = until.replace(tzinfo=None)
+
+        self._construct = kwargs.copy()
+        self._tzinfo = tzinfo
+        self._rrule = rrule(**self._construct)
+
+    def _attach_tzinfo(self, dt, tzinfo):
+        # pytz zones are attached by "localizing" the datetime
+        if hasattr(tzinfo, 'localize'):
+            return tzinfo.localize(dt, is_dst=True)
+
+        return dt.replace(tzinfo=tzinfo)
+
+    def _aware_return_wrapper(self, f, returns_list=False):
+        """Decorator function that allows rrule methods to handle tzinfo."""
+        # This is only necessary if we're actually attaching a tzinfo
+        if self._tzinfo is None:
+            return f
+
+        # All datetime arguments must be naive. If they are not naive, they are
+        # converted to the _tzinfo zone before dropping the zone.
+        def normalize_arg(arg):
+            if isinstance(arg, datetime.datetime) and arg.tzinfo is not None:
+                if arg.tzinfo is not self._tzinfo:
+                    arg = arg.astimezone(self._tzinfo)
+
+                return arg.replace(tzinfo=None)
+
+            return arg
+
+        def normalize_args(args, kwargs):
+            args = tuple(normalize_arg(arg) for arg in args)
+            kwargs = {kw: normalize_arg(arg) for kw, arg in kwargs.items()}
+
+            return args, kwargs
+
+        # There are two kinds of functions we care about - ones that return
+        # dates and ones that return lists of dates.
+        if not returns_list:
+            def inner_func(*args, **kwargs):
+                args, kwargs = normalize_args(args, kwargs)
+                dt = f(*args, **kwargs)
+                return self._attach_tzinfo(dt, self._tzinfo)
+        else:
+            def inner_func(*args, **kwargs):
+                args, kwargs = normalize_args(args, kwargs)
+                dts = f(*args, **kwargs)
+                return [self._attach_tzinfo(dt, self._tzinfo) for dt in dts]
+
+        return functools.wraps(f)(inner_func)
+
+    def __getattr__(self, name):
+        if name in self.__dict__:
+            return self.__dict__[name]
+
+        f = getattr(self._rrule, name)
+
+        if name in {'after', 'before'}:
+            return self._aware_return_wrapper(f)
+        elif name in {'xafter', 'xbefore', 'between'}:
+            return self._aware_return_wrapper(f, returns_list=True)
+        else:
+            return f
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+
+
+class DateLocator(ticker.Locator):
+    """
+    Determines the tick locations when plotting dates.
+
+    This class is subclassed by other Locators and
+    is not meant to be used on its own.
+    """
+    hms0d = {'byhour': 0, 'byminute': 0, 'bysecond': 0}
+
+    def __init__(self, tz=None):
+        """
+        Parameters
+        ----------
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        self.tz = _get_tzinfo(tz)
+
+    def set_tzinfo(self, tz):
+        """
+        Set timezone info.
+
+        Parameters
+        ----------
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        self.tz = _get_tzinfo(tz)
+
+    def datalim_to_dt(self):
+        """Convert axis data interval to datetime objects."""
+        dmin, dmax = self.axis.get_data_interval()
+        if dmin > dmax:
+            dmin, dmax = dmax, dmin
+
+        return num2date(dmin, self.tz), num2date(dmax, self.tz)
+
+    def viewlim_to_dt(self):
+        """Convert the view interval to datetime objects."""
+        vmin, vmax = self.axis.get_view_interval()
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+        return num2date(vmin, self.tz), num2date(vmax, self.tz)
+
+    def _get_unit(self):
+        """
+        Return how many days a unit of the locator is; used for
+        intelligent autoscaling.
+        """
+        return 1
+
+    def _get_interval(self):
+        """
+        Return the number of units for each tick.
+        """
+        return 1
+
+    def nonsingular(self, vmin, vmax):
+        """
+        Given the proposed upper and lower extent, adjust the range
+        if it is too close to being singular (i.e. a range of ~0).
+        """
+        if not np.isfinite(vmin) or not np.isfinite(vmax):
+            # Except if there is no data, then use 1970 as default.
+            return (date2num(datetime.date(1970, 1, 1)),
+                    date2num(datetime.date(1970, 1, 2)))
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        unit = self._get_unit()
+        interval = self._get_interval()
+        if abs(vmax - vmin) < 1e-6:
+            vmin -= 2 * unit * interval
+            vmax += 2 * unit * interval
+        return vmin, vmax
+
+
+class RRuleLocator(DateLocator):
+    # use the dateutil rrule instance
+
+    def __init__(self, o, tz=None):
+        super().__init__(tz)
+        self.rule = o
+
+    def __call__(self):
+        # if no data have been set, this will tank with a ValueError
+        try:
+            dmin, dmax = self.viewlim_to_dt()
+        except ValueError:
+            return []
+
+        return self.tick_values(dmin, dmax)
+
+    def tick_values(self, vmin, vmax):
+        start, stop = self._create_rrule(vmin, vmax)
+        dates = self.rule.between(start, stop, True)
+        if len(dates) == 0:
+            return date2num([vmin, vmax])
+        return self.raise_if_exceeds(date2num(dates))
+
+    def _create_rrule(self, vmin, vmax):
+        # set appropriate rrule dtstart and until and return
+        # start and end
+        delta = relativedelta(vmax, vmin)
+
+        # We need to cap at the endpoints of valid datetime
+        try:
+            start = vmin - delta
+        except (ValueError, OverflowError):
+            # cap
+            start = datetime.datetime(1, 1, 1, 0, 0, 0,
+                                      tzinfo=datetime.timezone.utc)
+
+        try:
+            stop = vmax + delta
+        except (ValueError, OverflowError):
+            # cap
+            stop = datetime.datetime(9999, 12, 31, 23, 59, 59,
+                                     tzinfo=datetime.timezone.utc)
+
+        self.rule.set(dtstart=start, until=stop)
+
+        return vmin, vmax
+
+    def _get_unit(self):
+        # docstring inherited
+        freq = self.rule._rrule._freq
+        return self.get_unit_generic(freq)
+
+    @staticmethod
+    def get_unit_generic(freq):
+        if freq == YEARLY:
+            return DAYS_PER_YEAR
+        elif freq == MONTHLY:
+            return DAYS_PER_MONTH
+        elif freq == WEEKLY:
+            return DAYS_PER_WEEK
+        elif freq == DAILY:
+            return 1.0
+        elif freq == HOURLY:
+            return 1.0 / HOURS_PER_DAY
+        elif freq == MINUTELY:
+            return 1.0 / MINUTES_PER_DAY
+        elif freq == SECONDLY:
+            return 1.0 / SEC_PER_DAY
+        else:
+            # error
+            return -1  # or should this just return '1'?
+
+    def _get_interval(self):
+        return self.rule._rrule._interval
+
+
+class AutoDateLocator(DateLocator):
+    """
+    On autoscale, this class picks the best `DateLocator` to set the view
+    limits and the tick locations.
+
+    Attributes
+    ----------
+    intervald : dict
+
+        Mapping of tick frequencies to multiples allowed for that ticking.
+        The default is ::
+
+            self.intervald = {
+                YEARLY  : [1, 2, 4, 5, 10, 20, 40, 50, 100, 200, 400, 500,
+                           1000, 2000, 4000, 5000, 10000],
+                MONTHLY : [1, 2, 3, 4, 6],
+                DAILY   : [1, 2, 3, 7, 14, 21],
+                HOURLY  : [1, 2, 3, 4, 6, 12],
+                MINUTELY: [1, 5, 10, 15, 30],
+                SECONDLY: [1, 5, 10, 15, 30],
+                MICROSECONDLY: [1, 2, 5, 10, 20, 50, 100, 200, 500,
+                                1000, 2000, 5000, 10000, 20000, 50000,
+                                100000, 200000, 500000, 1000000],
+            }
+
+        where the keys are defined in `dateutil.rrule`.
+
+        The interval is used to specify multiples that are appropriate for
+        the frequency of ticking. For instance, every 7 days is sensible
+        for daily ticks, but for minutes/seconds, 15 or 30 make sense.
+
+        When customizing, you should only modify the values for the existing
+        keys. You should not add or delete entries.
+
+        Example for forcing ticks every 3 hours::
+
+            locator = AutoDateLocator()
+            locator.intervald[HOURLY] = [3]  # only show every 3 hours
+    """
+
+    def __init__(self, tz=None, minticks=5, maxticks=None,
+                 interval_multiples=True):
+        """
+        Parameters
+        ----------
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        minticks : int
+            The minimum number of ticks desired; controls whether ticks occur
+            yearly, monthly, etc.
+        maxticks : int
+            The maximum number of ticks desired; controls the interval between
+            ticks (ticking every other, every 3, etc.).  For fine-grained
+            control, this can be a dictionary mapping individual rrule
+            frequency constants (YEARLY, MONTHLY, etc.) to their own maximum
+            number of ticks.  This can be used to keep the number of ticks
+            appropriate to the format chosen in `AutoDateFormatter`. Any
+            frequency not specified in this dictionary is given a default
+            value.
+        interval_multiples : bool, default: True
+            Whether ticks should be chosen to be multiple of the interval,
+            locking them to 'nicer' locations.  For example, this will force
+            the ticks to be at hours 0, 6, 12, 18 when hourly ticking is done
+            at 6 hour intervals.
+        """
+        super().__init__(tz=tz)
+        self._freq = YEARLY
+        self._freqs = [YEARLY, MONTHLY, DAILY, HOURLY, MINUTELY,
+                       SECONDLY, MICROSECONDLY]
+        self.minticks = minticks
+
+        self.maxticks = {YEARLY: 11, MONTHLY: 12, DAILY: 11, HOURLY: 12,
+                         MINUTELY: 11, SECONDLY: 11, MICROSECONDLY: 8}
+        if maxticks is not None:
+            try:
+                self.maxticks.update(maxticks)
+            except TypeError:
+                # Assume we were given an integer. Use this as the maximum
+                # number of ticks for every frequency and create a
+                # dictionary for this
+                self.maxticks = dict.fromkeys(self._freqs, maxticks)
+        self.interval_multiples = interval_multiples
+        self.intervald = {
+            YEARLY:   [1, 2, 4, 5, 10, 20, 40, 50, 100, 200, 400, 500,
+                       1000, 2000, 4000, 5000, 10000],
+            MONTHLY:  [1, 2, 3, 4, 6],
+            DAILY:    [1, 2, 3, 7, 14, 21],
+            HOURLY:   [1, 2, 3, 4, 6, 12],
+            MINUTELY: [1, 5, 10, 15, 30],
+            SECONDLY: [1, 5, 10, 15, 30],
+            MICROSECONDLY: [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000,
+                            5000, 10000, 20000, 50000, 100000, 200000, 500000,
+                            1000000],
+                            }
+        if interval_multiples:
+            # Swap "3" for "4" in the DAILY list; If we use 3 we get bad
+            # tick loc for months w/ 31 days: 1, 4, ..., 28, 31, 1
+            # If we use 4 then we get: 1, 5, ... 25, 29, 1
+            self.intervald[DAILY] = [1, 2, 4, 7, 14]
+
+        self._byranges = [None, range(1, 13), range(1, 32),
+                          range(0, 24), range(0, 60), range(0, 60), None]
+
+    def __call__(self):
+        # docstring inherited
+        dmin, dmax = self.viewlim_to_dt()
+        locator = self.get_locator(dmin, dmax)
+        return locator()
+
+    def tick_values(self, vmin, vmax):
+        return self.get_locator(vmin, vmax).tick_values(vmin, vmax)
+
+    def nonsingular(self, vmin, vmax):
+        # whatever is thrown at us, we can scale the unit.
+        # But default nonsingular date plots at an ~4 year period.
+        if not np.isfinite(vmin) or not np.isfinite(vmax):
+            # Except if there is no data, then use 1970 as default.
+            return (date2num(datetime.date(1970, 1, 1)),
+                    date2num(datetime.date(1970, 1, 2)))
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        if vmin == vmax:
+            vmin = vmin - DAYS_PER_YEAR * 2
+            vmax = vmax + DAYS_PER_YEAR * 2
+        return vmin, vmax
+
+    def _get_unit(self):
+        if self._freq in [MICROSECONDLY]:
+            return 1. / MUSECONDS_PER_DAY
+        else:
+            return RRuleLocator.get_unit_generic(self._freq)
+
+    def get_locator(self, dmin, dmax):
+        """Pick the best locator based on a distance."""
+        delta = relativedelta(dmax, dmin)
+        tdelta = dmax - dmin
+
+        # take absolute difference
+        if dmin > dmax:
+            delta = -delta
+            tdelta = -tdelta
+        # The following uses a mix of calls to relativedelta and timedelta
+        # methods because there is incomplete overlap in the functionality of
+        # these similar functions, and it's best to avoid doing our own math
+        # whenever possible.
+        numYears = float(delta.years)
+        numMonths = numYears * MONTHS_PER_YEAR + delta.months
+        numDays = tdelta.days  # Avoids estimates of days/month, days/year.
+        numHours = numDays * HOURS_PER_DAY + delta.hours
+        numMinutes = numHours * MIN_PER_HOUR + delta.minutes
+        numSeconds = np.floor(tdelta.total_seconds())
+        numMicroseconds = np.floor(tdelta.total_seconds() * 1e6)
+
+        nums = [numYears, numMonths, numDays, numHours, numMinutes,
+                numSeconds, numMicroseconds]
+
+        use_rrule_locator = [True] * 6 + [False]
+
+        # Default setting of bymonth, etc. to pass to rrule
+        # [unused (for year), bymonth, bymonthday, byhour, byminute,
+        #  bysecond, unused (for microseconds)]
+        byranges = [None, 1, 1, 0, 0, 0, None]
+
+        # Loop over all the frequencies and try to find one that gives at
+        # least a minticks tick positions.  Once this is found, look for
+        # an interval from a list specific to that frequency that gives no
+        # more than maxticks tick positions. Also, set up some ranges
+        # (bymonth, etc.) as appropriate to be passed to rrulewrapper.
+        for i, (freq, num) in enumerate(zip(self._freqs, nums)):
+            # If this particular frequency doesn't give enough ticks, continue
+            if num < self.minticks:
+                # Since we're not using this particular frequency, set
+                # the corresponding by_ to None so the rrule can act as
+                # appropriate
+                byranges[i] = None
+                continue
+
+            # Find the first available interval that doesn't give too many
+            # ticks
+            for interval in self.intervald[freq]:
+                if num <= interval * (self.maxticks[freq] - 1):
+                    break
+            else:
+                if not (self.interval_multiples and freq == DAILY):
+                    _api.warn_external(
+                        f"AutoDateLocator was unable to pick an appropriate "
+                        f"interval for this date range. It may be necessary "
+                        f"to add an interval value to the AutoDateLocator's "
+                        f"intervald dictionary. Defaulting to {interval}.")
+
+            # Set some parameters as appropriate
+            self._freq = freq
+
+            if self._byranges[i] and self.interval_multiples:
+                byranges[i] = self._byranges[i][::interval]
+                if i in (DAILY, WEEKLY):
+                    if interval == 14:
+                        # just make first and 15th.  Avoids 30th.
+                        byranges[i] = [1, 15]
+                    elif interval == 7:
+                        byranges[i] = [1, 8, 15, 22]
+
+                interval = 1
+            else:
+                byranges[i] = self._byranges[i]
+            break
+        else:
+            interval = 1
+
+        if (freq == YEARLY) and self.interval_multiples:
+            locator = YearLocator(interval, tz=self.tz)
+        elif use_rrule_locator[i]:
+            _, bymonth, bymonthday, byhour, byminute, bysecond, _ = byranges
+            rrule = rrulewrapper(self._freq, interval=interval,
+                                 dtstart=dmin, until=dmax,
+                                 bymonth=bymonth, bymonthday=bymonthday,
+                                 byhour=byhour, byminute=byminute,
+                                 bysecond=bysecond)
+
+            locator = RRuleLocator(rrule, tz=self.tz)
+        else:
+            locator = MicrosecondLocator(interval, tz=self.tz)
+            if date2num(dmin) > 70 * 365 and interval < 1000:
+                _api.warn_external(
+                    'Plotting microsecond time intervals for dates far from '
+                    f'the epoch (time origin: {get_epoch()}) is not well-'
+                    'supported. See matplotlib.dates.set_epoch to change the '
+                    'epoch.')
+
+        locator.set_axis(self.axis)
+        return locator
+
+
+class YearLocator(RRuleLocator):
+    """
+    Make ticks on a given day of each year that is a multiple of base.
+
+    Examples::
+
+      # Tick every year on Jan 1st
+      locator = YearLocator()
+
+      # Tick every 5 years on July 4th
+      locator = YearLocator(5, month=7, day=4)
+    """
+    def __init__(self, base=1, month=1, day=1, tz=None):
+        """
+        Parameters
+        ----------
+        base : int, default: 1
+            Mark ticks every *base* years.
+        month : int, default: 1
+            The month on which to place the ticks, starting from 1. Default is
+            January.
+        day : int, default: 1
+            The day on which to place the ticks.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        rule = rrulewrapper(YEARLY, interval=base, bymonth=month,
+                            bymonthday=day, **self.hms0d)
+        super().__init__(rule, tz=tz)
+        self.base = ticker._Edge_integer(base, 0)
+
+    def _create_rrule(self, vmin, vmax):
+        # 'start' needs to be a multiple of the interval to create ticks on
+        # interval multiples when the tick frequency is YEARLY
+        ymin = max(self.base.le(vmin.year) * self.base.step, 1)
+        ymax = min(self.base.ge(vmax.year) * self.base.step, 9999)
+
+        c = self.rule._construct
+        replace = {'year': ymin,
+                   'month': c.get('bymonth', 1),
+                   'day': c.get('bymonthday', 1),
+                   'hour': 0, 'minute': 0, 'second': 0}
+
+        start = vmin.replace(**replace)
+        stop = start.replace(year=ymax)
+        self.rule.set(dtstart=start, until=stop)
+
+        return start, stop
+
+
+class MonthLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each month, e.g., 1, 3, 12.
+    """
+    def __init__(self, bymonth=None, bymonthday=1, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        bymonth : int or list of int, default: all months
+            Ticks will be placed on every month in *bymonth*. Default is
+            ``range(1, 13)``, i.e. every month.
+        bymonthday : int, default: 1
+            The day on which to place the ticks.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        if bymonth is None:
+            bymonth = range(1, 13)
+
+        rule = rrulewrapper(MONTHLY, bymonth=bymonth, bymonthday=bymonthday,
+                            interval=interval, **self.hms0d)
+        super().__init__(rule, tz=tz)
+
+
+class WeekdayLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each weekday.
+    """
+
+    def __init__(self, byweekday=1, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        byweekday : int or list of int, default: all days
+            Ticks will be placed on every weekday in *byweekday*. Default is
+            every day.
+
+            Elements of *byweekday* must be one of MO, TU, WE, TH, FR, SA,
+            SU, the constants from :mod:`dateutil.rrule`, which have been
+            imported into the :mod:`matplotlib.dates` namespace.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        rule = rrulewrapper(DAILY, byweekday=byweekday,
+                            interval=interval, **self.hms0d)
+        super().__init__(rule, tz=tz)
+
+
+class DayLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each day of the month.  For example,
+    1, 15, 30.
+    """
+    def __init__(self, bymonthday=None, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        bymonthday : int or list of int, default: all days
+            Ticks will be placed on every day in *bymonthday*. Default is
+            ``bymonthday=range(1, 32)``, i.e., every day of the month.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        if interval != int(interval) or interval < 1:
+            raise ValueError("interval must be an integer greater than 0")
+        if bymonthday is None:
+            bymonthday = range(1, 32)
+
+        rule = rrulewrapper(DAILY, bymonthday=bymonthday,
+                            interval=interval, **self.hms0d)
+        super().__init__(rule, tz=tz)
+
+
+class HourLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each hour.
+    """
+    def __init__(self, byhour=None, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        byhour : int or list of int, default: all hours
+            Ticks will be placed on every hour in *byhour*. Default is
+            ``byhour=range(24)``, i.e., every hour.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        if byhour is None:
+            byhour = range(24)
+
+        rule = rrulewrapper(HOURLY, byhour=byhour, interval=interval,
+                            byminute=0, bysecond=0)
+        super().__init__(rule, tz=tz)
+
+
+class MinuteLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each minute.
+    """
+    def __init__(self, byminute=None, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        byminute : int or list of int, default: all minutes
+            Ticks will be placed on every minute in *byminute*. Default is
+            ``byminute=range(60)``, i.e., every minute.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        if byminute is None:
+            byminute = range(60)
+
+        rule = rrulewrapper(MINUTELY, byminute=byminute, interval=interval,
+                            bysecond=0)
+        super().__init__(rule, tz=tz)
+
+
+class SecondLocator(RRuleLocator):
+    """
+    Make ticks on occurrences of each second.
+    """
+    def __init__(self, bysecond=None, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        bysecond : int or list of int, default: all seconds
+            Ticks will be placed on every second in *bysecond*. Default is
+            ``bysecond = range(60)``, i.e., every second.
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        if bysecond is None:
+            bysecond = range(60)
+
+        rule = rrulewrapper(SECONDLY, bysecond=bysecond, interval=interval)
+        super().__init__(rule, tz=tz)
+
+
+class MicrosecondLocator(DateLocator):
+    """
+    Make ticks on regular intervals of one or more microsecond(s).
+
+    .. note::
+
+        By default, Matplotlib uses a floating point representation of time in
+        days since the epoch, so plotting data with
+        microsecond time resolution does not work well for
+        dates that are far (about 70 years) from the epoch (check with
+        `~.dates.get_epoch`).
+
+        If you want sub-microsecond resolution time plots, it is strongly
+        recommended to use floating point seconds, not datetime-like
+        time representation.
+
+        If you really must use datetime.datetime() or similar and still
+        need microsecond precision, change the time origin via
+        `.dates.set_epoch` to something closer to the dates being plotted.
+        See :doc:`/gallery/ticks/date_precision_and_epochs`.
+
+    """
+    def __init__(self, interval=1, tz=None):
+        """
+        Parameters
+        ----------
+        interval : int, default: 1
+            The interval between each iteration. For example, if
+            ``interval=2``, mark every second occurrence.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks timezone. If a string, *tz* is passed to `dateutil.tz`.
+        """
+        super().__init__(tz=tz)
+        self._interval = interval
+        self._wrapped_locator = ticker.MultipleLocator(interval)
+
+    def set_axis(self, axis):
+        self._wrapped_locator.set_axis(axis)
+        return super().set_axis(axis)
+
+    def __call__(self):
+        # if no data have been set, this will tank with a ValueError
+        try:
+            dmin, dmax = self.viewlim_to_dt()
+        except ValueError:
+            return []
+
+        return self.tick_values(dmin, dmax)
+
+    def tick_values(self, vmin, vmax):
+        nmin, nmax = date2num((vmin, vmax))
+        t0 = np.floor(nmin)
+        nmax = nmax - t0
+        nmin = nmin - t0
+        nmin *= MUSECONDS_PER_DAY
+        nmax *= MUSECONDS_PER_DAY
+
+        ticks = self._wrapped_locator.tick_values(nmin, nmax)
+
+        ticks = ticks / MUSECONDS_PER_DAY + t0
+        return ticks
+
+    def _get_unit(self):
+        # docstring inherited
+        return 1. / MUSECONDS_PER_DAY
+
+    def _get_interval(self):
+        # docstring inherited
+        return self._interval
+
+
+class DateConverter(units.ConversionInterface):
+    """
+    Converter for `datetime.date` and `datetime.datetime` data, or for
+    date/time data represented as it would be converted by `date2num`.
+
+    The 'unit' tag for such data is None or a `~datetime.tzinfo` instance.
+    """
+
+    def __init__(self, *, interval_multiples=True):
+        self._interval_multiples = interval_multiples
+        super().__init__()
+
+    def axisinfo(self, unit, axis):
+        """
+        Return the `~matplotlib.units.AxisInfo` for *unit*.
+
+        *unit* is a `~datetime.tzinfo` instance or None.
+        The *axis* argument is required but not used.
+        """
+        tz = unit
+
+        majloc = AutoDateLocator(tz=tz,
+                                 interval_multiples=self._interval_multiples)
+        majfmt = AutoDateFormatter(majloc, tz=tz)
+        datemin = datetime.date(1970, 1, 1)
+        datemax = datetime.date(1970, 1, 2)
+
+        return units.AxisInfo(majloc=majloc, majfmt=majfmt, label='',
+                              default_limits=(datemin, datemax))
+
+    @staticmethod
+    def convert(value, unit, axis):
+        """
+        If *value* is not already a number or sequence of numbers, convert it
+        with `date2num`.
+
+        The *unit* and *axis* arguments are not used.
+        """
+        return date2num(value)
+
+    @staticmethod
+    def default_units(x, axis):
+        """
+        Return the `~datetime.tzinfo` instance of *x* or of its first element,
+        or None
+        """
+        if isinstance(x, np.ndarray):
+            x = x.ravel()
+
+        try:
+            x = cbook._safe_first_finite(x)
+        except (TypeError, StopIteration):
+            pass
+
+        try:
+            return x.tzinfo
+        except AttributeError:
+            pass
+        return None
+
+
+class ConciseDateConverter(DateConverter):
+    # docstring inherited
+
+    def __init__(self, formats=None, zero_formats=None, offset_formats=None,
+                 show_offset=True, *, interval_multiples=True):
+        self._formats = formats
+        self._zero_formats = zero_formats
+        self._offset_formats = offset_formats
+        self._show_offset = show_offset
+        self._interval_multiples = interval_multiples
+        super().__init__()
+
+    def axisinfo(self, unit, axis):
+        # docstring inherited
+        tz = unit
+        majloc = AutoDateLocator(tz=tz,
+                                 interval_multiples=self._interval_multiples)
+        majfmt = ConciseDateFormatter(majloc, tz=tz, formats=self._formats,
+                                      zero_formats=self._zero_formats,
+                                      offset_formats=self._offset_formats,
+                                      show_offset=self._show_offset)
+        datemin = datetime.date(1970, 1, 1)
+        datemax = datetime.date(1970, 1, 2)
+        return units.AxisInfo(majloc=majloc, majfmt=majfmt, label='',
+                              default_limits=(datemin, datemax))
+
+
+class _SwitchableDateConverter:
+    """
+    Helper converter-like object that generates and dispatches to
+    temporary ConciseDateConverter or DateConverter instances based on
+    :rc:`date.converter` and :rc:`date.interval_multiples`.
+    """
+
+    @staticmethod
+    def _get_converter():
+        converter_cls = {
+            "concise": ConciseDateConverter, "auto": DateConverter}[
+                mpl.rcParams["date.converter"]]
+        interval_multiples = mpl.rcParams["date.interval_multiples"]
+        return converter_cls(interval_multiples=interval_multiples)
+
+    def axisinfo(self, *args, **kwargs):
+        return self._get_converter().axisinfo(*args, **kwargs)
+
+    def default_units(self, *args, **kwargs):
+        return self._get_converter().default_units(*args, **kwargs)
+
+    def convert(self, *args, **kwargs):
+        return self._get_converter().convert(*args, **kwargs)
+
+
+units.registry[np.datetime64] = \
+    units.registry[datetime.date] = \
+    units.registry[datetime.datetime] = \
+    _SwitchableDateConverter()
diff --git a/lib/python3.12/site-packages/matplotlib/figure.pyi b/lib/python3.12/site-packages/matplotlib/figure.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..064503c91384a6f5af15cccd736c817283ce77e0
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/figure.pyi
@@ -0,0 +1,423 @@
+from collections.abc import Callable, Hashable, Iterable, Sequence
+import os
+from typing import Any, IO, Literal, TypeVar, overload
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from matplotlib.artist import Artist
+from matplotlib.axes import Axes
+from matplotlib.backend_bases import (
+    FigureCanvasBase,
+    MouseButton,
+    MouseEvent,
+    RendererBase,
+)
+from matplotlib.colors import Colormap, Normalize
+from matplotlib.colorbar import Colorbar
+from matplotlib.colorizer import ColorizingArtist, Colorizer
+from matplotlib.cm import ScalarMappable
+from matplotlib.gridspec import GridSpec, SubplotSpec, SubplotParams as SubplotParams
+from matplotlib.image import _ImageBase, FigureImage
+from matplotlib.layout_engine import LayoutEngine
+from matplotlib.legend import Legend
+from matplotlib.lines import Line2D
+from matplotlib.patches import Rectangle, Patch
+from matplotlib.text import Text
+from matplotlib.transforms import Affine2D, Bbox, BboxBase, Transform
+from .typing import ColorType, HashableList
+
+_T = TypeVar("_T")
+
+class FigureBase(Artist):
+    artists: list[Artist]
+    lines: list[Line2D]
+    patches: list[Patch]
+    texts: list[Text]
+    images: list[_ImageBase]
+    legends: list[Legend]
+    subfigs: list[SubFigure]
+    stale: bool
+    suppressComposite: bool | None
+    def __init__(self, **kwargs) -> None: ...
+    def autofmt_xdate(
+        self,
+        bottom: float = ...,
+        rotation: int = ...,
+        ha: Literal["left", "center", "right"] = ...,
+        which: Literal["major", "minor", "both"] = ...,
+    ) -> None: ...
+    def get_children(self) -> list[Artist]: ...
+    def contains(self, mouseevent: MouseEvent) -> tuple[bool, dict[Any, Any]]: ...
+    def suptitle(self, t: str, **kwargs) -> Text: ...
+    def get_suptitle(self) -> str: ...
+    def supxlabel(self, t: str, **kwargs) -> Text: ...
+    def get_supxlabel(self) -> str: ...
+    def supylabel(self, t: str, **kwargs) -> Text: ...
+    def get_supylabel(self) -> str: ...
+    def get_edgecolor(self) -> ColorType: ...
+    def get_facecolor(self) -> ColorType: ...
+    def get_frameon(self) -> bool: ...
+    def set_linewidth(self, linewidth: float) -> None: ...
+    def get_linewidth(self) -> float: ...
+    def set_edgecolor(self, color: ColorType) -> None: ...
+    def set_facecolor(self, color: ColorType) -> None: ...
+    @overload
+    def get_figure(self, root: Literal[True]) -> Figure: ...
+    @overload
+    def get_figure(self, root: Literal[False]) -> Figure | SubFigure: ...
+    @overload
+    def get_figure(self, root: bool = ...) -> Figure | SubFigure: ...
+    def set_frameon(self, b: bool) -> None: ...
+    @property
+    def frameon(self) -> bool: ...
+    @frameon.setter
+    def frameon(self, b: bool) -> None: ...
+    def add_artist(self, artist: Artist, clip: bool = ...) -> Artist: ...
+    @overload
+    def add_axes(self, ax: Axes) -> Axes: ...
+    @overload
+    def add_axes(
+        self,
+        rect: tuple[float, float, float, float],
+        projection: None | str = ...,
+        polar: bool = ...,
+        **kwargs
+    ) -> Axes: ...
+
+    # TODO: docstring indicates SubplotSpec a valid arg, but none of the listed signatures appear to be that
+    @overload
+    def add_subplot(
+        self, nrows: int, ncols: int, index: int | tuple[int, int], **kwargs
+    ) -> Axes: ...
+    @overload
+    def add_subplot(self, pos: int, **kwargs) -> Axes: ...
+    @overload
+    def add_subplot(self, ax: Axes, **kwargs) -> Axes: ...
+    @overload
+    def add_subplot(self, ax: SubplotSpec, **kwargs) -> Axes: ...
+    @overload
+    def add_subplot(self, **kwargs) -> Axes: ...
+    @overload
+    def subplots(
+        self,
+        nrows: Literal[1] = ...,
+        ncols: Literal[1] = ...,
+        *,
+        sharex: bool | Literal["none", "all", "row", "col"] = ...,
+        sharey: bool | Literal["none", "all", "row", "col"] = ...,
+        squeeze: Literal[True] = ...,
+        width_ratios: Sequence[float] | None = ...,
+        height_ratios: Sequence[float] | None = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> Axes: ...
+    @overload
+    def subplots(
+        self,
+        nrows: int = ...,
+        ncols: int = ...,
+        *,
+        sharex: bool | Literal["none", "all", "row", "col"] = ...,
+        sharey: bool | Literal["none", "all", "row", "col"] = ...,
+        squeeze: Literal[False],
+        width_ratios: Sequence[float] | None = ...,
+        height_ratios: Sequence[float] | None = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> np.ndarray: ...  # TODO numpy/numpy#24738
+    @overload
+    def subplots(
+        self,
+        nrows: int = ...,
+        ncols: int = ...,
+        *,
+        sharex: bool | Literal["none", "all", "row", "col"] = ...,
+        sharey: bool | Literal["none", "all", "row", "col"] = ...,
+        squeeze: bool = ...,
+        width_ratios: Sequence[float] | None = ...,
+        height_ratios: Sequence[float] | None = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> Any: ...
+    def delaxes(self, ax: Axes) -> None: ...
+    def clear(self, keep_observers: bool = ...) -> None: ...
+    def clf(self, keep_observers: bool = ...) -> None: ...
+
+    @overload
+    def legend(self) -> Legend: ...
+    @overload
+    def legend(self, handles: Iterable[Artist], labels: Iterable[str], **kwargs) -> Legend: ...
+    @overload
+    def legend(self, *, handles: Iterable[Artist], **kwargs) -> Legend: ...
+    @overload
+    def legend(self, labels: Iterable[str], **kwargs) -> Legend: ...
+    @overload
+    def legend(self, **kwargs) -> Legend: ...
+
+    def text(
+        self,
+        x: float,
+        y: float,
+        s: str,
+        fontdict: dict[str, Any] | None = ...,
+        **kwargs
+    ) -> Text: ...
+    def colorbar(
+        self,
+        mappable: ScalarMappable | ColorizingArtist,
+        cax: Axes | None = ...,
+        ax: Axes | Iterable[Axes] | None = ...,
+        use_gridspec: bool = ...,
+        **kwargs
+    ) -> Colorbar: ...
+    def subplots_adjust(
+        self,
+        left: float | None = ...,
+        bottom: float | None = ...,
+        right: float | None = ...,
+        top: float | None = ...,
+        wspace: float | None = ...,
+        hspace: float | None = ...,
+    ) -> None: ...
+    def align_xlabels(self, axs: Iterable[Axes] | None = ...) -> None: ...
+    def align_ylabels(self, axs: Iterable[Axes] | None = ...) -> None: ...
+    def align_titles(self, axs: Iterable[Axes] | None = ...) -> None: ...
+    def align_labels(self, axs: Iterable[Axes] | None = ...) -> None: ...
+    def add_gridspec(self, nrows: int = ..., ncols: int = ..., **kwargs) -> GridSpec: ...
+    @overload
+    def subfigures(
+        self,
+        nrows: int = ...,
+        ncols: int = ...,
+        squeeze: Literal[False] = ...,
+        wspace: float | None = ...,
+        hspace: float | None = ...,
+        width_ratios: ArrayLike | None = ...,
+        height_ratios: ArrayLike | None = ...,
+        **kwargs
+    ) -> np.ndarray: ...
+    @overload
+    def subfigures(
+        self,
+        nrows: int = ...,
+        ncols: int = ...,
+        squeeze: Literal[True] = ...,
+        wspace: float | None = ...,
+        hspace: float | None = ...,
+        width_ratios: ArrayLike | None = ...,
+        height_ratios: ArrayLike | None = ...,
+        **kwargs
+    ) -> np.ndarray | SubFigure: ...
+    def add_subfigure(self, subplotspec: SubplotSpec, **kwargs) -> SubFigure: ...
+    def sca(self, a: Axes) -> Axes: ...
+    def gca(self) -> Axes: ...
+    def _gci(self) -> ColorizingArtist | None: ...
+    def _process_projection_requirements(
+        self, *, axes_class=None, polar=False, projection=None, **kwargs
+    ) -> tuple[type[Axes], dict[str, Any]]: ...
+    def get_default_bbox_extra_artists(self) -> list[Artist]: ...
+    def get_tightbbox(
+        self,
+        renderer: RendererBase | None = ...,
+        *,
+        bbox_extra_artists: Iterable[Artist] | None = ...,
+    ) -> Bbox: ...
+    @overload
+    def subplot_mosaic(
+        self,
+        mosaic: str,
+        *,
+        sharex: bool = ...,
+        sharey: bool = ...,
+        width_ratios: ArrayLike | None = ...,
+        height_ratios: ArrayLike | None = ...,
+        empty_sentinel: str = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        per_subplot_kw: dict[str | tuple[str, ...], dict[str, Any]] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> dict[str, Axes]: ...
+    @overload
+    def subplot_mosaic(
+        self,
+        mosaic: list[HashableList[_T]],
+        *,
+        sharex: bool = ...,
+        sharey: bool = ...,
+        width_ratios: ArrayLike | None = ...,
+        height_ratios: ArrayLike | None = ...,
+        empty_sentinel: _T = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        per_subplot_kw: dict[_T | tuple[_T, ...], dict[str, Any]] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> dict[_T, Axes]: ...
+    @overload
+    def subplot_mosaic(
+        self,
+        mosaic: list[HashableList[Hashable]],
+        *,
+        sharex: bool = ...,
+        sharey: bool = ...,
+        width_ratios: ArrayLike | None = ...,
+        height_ratios: ArrayLike | None = ...,
+        empty_sentinel: Any = ...,
+        subplot_kw: dict[str, Any] | None = ...,
+        per_subplot_kw: dict[Hashable | tuple[Hashable, ...], dict[str, Any]] | None = ...,
+        gridspec_kw: dict[str, Any] | None = ...,
+    ) -> dict[Hashable, Axes]: ...
+
+class SubFigure(FigureBase):
+    @property
+    def figure(self) -> Figure: ...
+    subplotpars: SubplotParams
+    dpi_scale_trans: Affine2D
+    transFigure: Transform
+    bbox_relative: Bbox
+    figbbox: BboxBase
+    bbox: BboxBase
+    transSubfigure: Transform
+    patch: Rectangle
+    def __init__(
+        self,
+        parent: Figure | SubFigure,
+        subplotspec: SubplotSpec,
+        *,
+        facecolor: ColorType | None = ...,
+        edgecolor: ColorType | None = ...,
+        linewidth: float = ...,
+        frameon: bool | None = ...,
+        **kwargs
+    ) -> None: ...
+    @property
+    def canvas(self) -> FigureCanvasBase: ...
+    @property
+    def dpi(self) -> float: ...
+    @dpi.setter
+    def dpi(self, value: float) -> None: ...
+    def get_dpi(self) -> float: ...
+    def set_dpi(self, val) -> None: ...
+    def get_constrained_layout(self) -> bool: ...
+    def get_constrained_layout_pads(
+        self, relative: bool = ...
+    ) -> tuple[float, float, float, float]: ...
+    def get_layout_engine(self) -> LayoutEngine: ...
+    @property  # type: ignore[misc]
+    def axes(self) -> list[Axes]: ...  # type: ignore[override]
+    def get_axes(self) -> list[Axes]: ...
+
+class Figure(FigureBase):
+    @property
+    def figure(self) -> Figure: ...
+    bbox_inches: Bbox
+    dpi_scale_trans: Affine2D
+    bbox: BboxBase
+    figbbox: BboxBase
+    transFigure: Transform
+    transSubfigure: Transform
+    patch: Rectangle
+    subplotpars: SubplotParams
+    def __init__(
+        self,
+        figsize: tuple[float, float] | None = ...,
+        dpi: float | None = ...,
+        *,
+        facecolor: ColorType | None = ...,
+        edgecolor: ColorType | None = ...,
+        linewidth: float = ...,
+        frameon: bool | None = ...,
+        subplotpars: SubplotParams | None = ...,
+        tight_layout: bool | dict[str, Any] | None = ...,
+        constrained_layout: bool | dict[str, Any] | None = ...,
+        layout: Literal["constrained", "compressed", "tight"]
+        | LayoutEngine
+        | None = ...,
+        **kwargs
+    ) -> None: ...
+    def pick(self, mouseevent: MouseEvent) -> None: ...
+    def set_layout_engine(
+        self,
+        layout: Literal["constrained", "compressed", "tight", "none"]
+        | LayoutEngine
+        | None = ...,
+        **kwargs
+    ) -> None: ...
+    def get_layout_engine(self) -> LayoutEngine | None: ...
+    def _repr_html_(self) -> str | None: ...
+    def show(self, warn: bool = ...) -> None: ...
+    @property
+    def number(self) -> int | str: ...
+    @number.setter
+    def number(self, num: int | str) -> None: ...
+    @property  # type: ignore[misc]
+    def axes(self) -> list[Axes]: ...  # type: ignore[override]
+    def get_axes(self) -> list[Axes]: ...
+    @property
+    def dpi(self) -> float: ...
+    @dpi.setter
+    def dpi(self, dpi: float) -> None: ...
+    def get_tight_layout(self) -> bool: ...
+    def get_constrained_layout_pads(
+        self, relative: bool = ...
+    ) -> tuple[float, float, float, float]: ...
+    def get_constrained_layout(self) -> bool: ...
+    canvas: FigureCanvasBase
+    def set_canvas(self, canvas: FigureCanvasBase) -> None: ...
+    def figimage(
+        self,
+        X: ArrayLike,
+        xo: int = ...,
+        yo: int = ...,
+        alpha: float | None = ...,
+        norm: str | Normalize | None = ...,
+        cmap: str | Colormap | None = ...,
+        vmin: float | None = ...,
+        vmax: float | None = ...,
+        origin: Literal["upper", "lower"] | None = ...,
+        resize: bool = ...,
+        *,
+        colorizer: Colorizer | None = ...,
+        **kwargs
+    ) -> FigureImage: ...
+    def set_size_inches(
+        self, w: float | tuple[float, float], h: float | None = ..., forward: bool = ...
+    ) -> None: ...
+    def get_size_inches(self) -> np.ndarray: ...
+    def get_figwidth(self) -> float: ...
+    def get_figheight(self) -> float: ...
+    def get_dpi(self) -> float: ...
+    def set_dpi(self, val: float) -> None: ...
+    def set_figwidth(self, val: float, forward: bool = ...) -> None: ...
+    def set_figheight(self, val: float, forward: bool = ...) -> None: ...
+    def clear(self, keep_observers: bool = ...) -> None: ...
+    def draw_without_rendering(self) -> None: ...
+    def draw_artist(self, a: Artist) -> None: ...
+    def add_axobserver(self, func: Callable[[Figure], Any]) -> None: ...
+    def savefig(
+        self,
+        fname: str | os.PathLike | IO,
+        *,
+        transparent: bool | None = ...,
+        **kwargs
+    ) -> None: ...
+    def ginput(
+        self,
+        n: int = ...,
+        timeout: float = ...,
+        show_clicks: bool = ...,
+        mouse_add: MouseButton = ...,
+        mouse_pop: MouseButton = ...,
+        mouse_stop: MouseButton = ...,
+    ) -> list[tuple[int, int]]: ...
+    def waitforbuttonpress(self, timeout: float = ...) -> None | bool: ...
+    def tight_layout(
+        self,
+        *,
+        pad: float = ...,
+        h_pad: float | None = ...,
+        w_pad: float | None = ...,
+        rect: tuple[float, float, float, float] | None = ...
+    ) -> None: ...
+
+def figaspect(
+    arg: float | ArrayLike,
+) -> np.ndarray[tuple[Literal[2]], np.dtype[np.float64]]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/font_manager.py b/lib/python3.12/site-packages/matplotlib/font_manager.py
new file mode 100644
index 0000000000000000000000000000000000000000..9aa8dccde444b8998f34ded5cd9cfe07e7b46f6a
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/font_manager.py
@@ -0,0 +1,1645 @@
+"""
+A module for finding, managing, and using fonts across platforms.
+
+This module provides a single `FontManager` instance, ``fontManager``, that can
+be shared across backends and platforms.  The `findfont`
+function returns the best TrueType (TTF) font file in the local or
+system font path that matches the specified `FontProperties`
+instance.  The `FontManager` also handles Adobe Font Metrics
+(AFM) font files for use by the PostScript backend.
+The `FontManager.addfont` function adds a custom font from a file without
+installing it into your operating system.
+
+The design is based on the `W3C Cascading Style Sheet, Level 1 (CSS1)
+font specification <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_.
+Future versions may implement the Level 2 or 2.1 specifications.
+"""
+
+# KNOWN ISSUES
+#
+#   - documentation
+#   - font variant is untested
+#   - font stretch is incomplete
+#   - font size is incomplete
+#   - default font algorithm needs improvement and testing
+#   - setWeights function needs improvement
+#   - 'light' is an invalid weight value, remove it.
+
+from __future__ import annotations
+
+from base64 import b64encode
+import copy
+import dataclasses
+from functools import lru_cache
+import functools
+from io import BytesIO
+import json
+import logging
+from numbers import Number
+import os
+from pathlib import Path
+import plistlib
+import re
+import subprocess
+import sys
+import threading
+
+import matplotlib as mpl
+from matplotlib import _api, _afm, cbook, ft2font
+from matplotlib._fontconfig_pattern import (
+    parse_fontconfig_pattern, generate_fontconfig_pattern)
+from matplotlib.rcsetup import _validators
+
+_log = logging.getLogger(__name__)
+
+font_scalings = {
+    'xx-small': 0.579,
+    'x-small':  0.694,
+    'small':    0.833,
+    'medium':   1.0,
+    'large':    1.200,
+    'x-large':  1.440,
+    'xx-large': 1.728,
+    'larger':   1.2,
+    'smaller':  0.833,
+    None:       1.0,
+}
+stretch_dict = {
+    'ultra-condensed': 100,
+    'extra-condensed': 200,
+    'condensed':       300,
+    'semi-condensed':  400,
+    'normal':          500,
+    'semi-expanded':   600,
+    'semi-extended':   600,
+    'expanded':        700,
+    'extended':        700,
+    'extra-expanded':  800,
+    'extra-extended':  800,
+    'ultra-expanded':  900,
+    'ultra-extended':  900,
+}
+weight_dict = {
+    'ultralight': 100,
+    'light':      200,
+    'normal':     400,
+    'regular':    400,
+    'book':       400,
+    'medium':     500,
+    'roman':      500,
+    'semibold':   600,
+    'demibold':   600,
+    'demi':       600,
+    'bold':       700,
+    'heavy':      800,
+    'extra bold': 800,
+    'black':      900,
+}
+_weight_regexes = [
+    # From fontconfig's FcFreeTypeQueryFaceInternal; not the same as
+    # weight_dict!
+    ("thin", 100),
+    ("extralight", 200),
+    ("ultralight", 200),
+    ("demilight", 350),
+    ("semilight", 350),
+    ("light", 300),  # Needs to come *after* demi/semilight!
+    ("book", 380),
+    ("regular", 400),
+    ("normal", 400),
+    ("medium", 500),
+    ("demibold", 600),
+    ("demi", 600),
+    ("semibold", 600),
+    ("extrabold", 800),
+    ("superbold", 800),
+    ("ultrabold", 800),
+    ("bold", 700),  # Needs to come *after* extra/super/ultrabold!
+    ("ultrablack", 1000),
+    ("superblack", 1000),
+    ("extrablack", 1000),
+    (r"\bultra", 1000),
+    ("black", 900),  # Needs to come *after* ultra/super/extrablack!
+    ("heavy", 900),
+]
+font_family_aliases = {
+    'serif',
+    'sans-serif',
+    'sans serif',
+    'cursive',
+    'fantasy',
+    'monospace',
+    'sans',
+}
+
+# OS Font paths
+try:
+    _HOME = Path.home()
+except Exception:  # Exceptions thrown by home() are not specified...
+    _HOME = Path(os.devnull)  # Just an arbitrary path with no children.
+MSFolders = \
+    r'Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders'
+MSFontDirectories = [
+    r'SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts',
+    r'SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts']
+MSUserFontDirectories = [
+    str(_HOME / 'AppData/Local/Microsoft/Windows/Fonts'),
+    str(_HOME / 'AppData/Roaming/Microsoft/Windows/Fonts'),
+]
+X11FontDirectories = [
+    # an old standard installation point
+    "/usr/X11R6/lib/X11/fonts/TTF/",
+    "/usr/X11/lib/X11/fonts",
+    # here is the new standard location for fonts
+    "/usr/share/fonts/",
+    # documented as a good place to install new fonts
+    "/usr/local/share/fonts/",
+    # common application, not really useful
+    "/usr/lib/openoffice/share/fonts/truetype/",
+    # user fonts
+    str((Path(os.environ.get('XDG_DATA_HOME') or _HOME / ".local/share"))
+        / "fonts"),
+    str(_HOME / ".fonts"),
+]
+OSXFontDirectories = [
+    "/Library/Fonts/",
+    "/Network/Library/Fonts/",
+    "/System/Library/Fonts/",
+    # fonts installed via MacPorts
+    "/opt/local/share/fonts",
+    # user fonts
+    str(_HOME / "Library/Fonts"),
+]
+
+
+def get_fontext_synonyms(fontext):
+    """
+    Return a list of file extensions that are synonyms for
+    the given file extension *fileext*.
+    """
+    return {
+        'afm': ['afm'],
+        'otf': ['otf', 'ttc', 'ttf'],
+        'ttc': ['otf', 'ttc', 'ttf'],
+        'ttf': ['otf', 'ttc', 'ttf'],
+    }[fontext]
+
+
+def list_fonts(directory, extensions):
+    """
+    Return a list of all fonts matching any of the extensions, found
+    recursively under the directory.
+    """
+    extensions = ["." + ext for ext in extensions]
+    return [os.path.join(dirpath, filename)
+            # os.walk ignores access errors, unlike Path.glob.
+            for dirpath, _, filenames in os.walk(directory)
+            for filename in filenames
+            if Path(filename).suffix.lower() in extensions]
+
+
+def win32FontDirectory():
+    r"""
+    Return the user-specified font directory for Win32.  This is
+    looked up from the registry key ::
+
+      \\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Fonts
+
+    If the key is not found, ``%WINDIR%\Fonts`` will be returned.
+    """  # noqa: E501
+    import winreg
+    try:
+        with winreg.OpenKey(winreg.HKEY_CURRENT_USER, MSFolders) as user:
+            return winreg.QueryValueEx(user, 'Fonts')[0]
+    except OSError:
+        return os.path.join(os.environ['WINDIR'], 'Fonts')
+
+
+def _get_win32_installed_fonts():
+    """List the font paths known to the Windows registry."""
+    import winreg
+    items = set()
+    # Search and resolve fonts listed in the registry.
+    for domain, base_dirs in [
+            (winreg.HKEY_LOCAL_MACHINE, [win32FontDirectory()]),  # System.
+            (winreg.HKEY_CURRENT_USER, MSUserFontDirectories),  # User.
+    ]:
+        for base_dir in base_dirs:
+            for reg_path in MSFontDirectories:
+                try:
+                    with winreg.OpenKey(domain, reg_path) as local:
+                        for j in range(winreg.QueryInfoKey(local)[1]):
+                            # value may contain the filename of the font or its
+                            # absolute path.
+                            key, value, tp = winreg.EnumValue(local, j)
+                            if not isinstance(value, str):
+                                continue
+                            try:
+                                # If value contains already an absolute path,
+                                # then it is not changed further.
+                                path = Path(base_dir, value).resolve()
+                            except RuntimeError:
+                                # Don't fail with invalid entries.
+                                continue
+                            items.add(path)
+                except (OSError, MemoryError):
+                    continue
+    return items
+
+
+@lru_cache
+def _get_fontconfig_fonts():
+    """Cache and list the font paths known to ``fc-list``."""
+    try:
+        if b'--format' not in subprocess.check_output(['fc-list', '--help']):
+            _log.warning(  # fontconfig 2.7 implemented --format.
+                'Matplotlib needs fontconfig>=2.7 to query system fonts.')
+            return []
+        out = subprocess.check_output(['fc-list', '--format=%{file}\\n'])
+    except (OSError, subprocess.CalledProcessError):
+        return []
+    return [Path(os.fsdecode(fname)) for fname in out.split(b'\n')]
+
+
+@lru_cache
+def _get_macos_fonts():
+    """Cache and list the font paths known to ``system_profiler SPFontsDataType``."""
+    try:
+        d, = plistlib.loads(
+            subprocess.check_output(["system_profiler", "-xml", "SPFontsDataType"]))
+    except (OSError, subprocess.CalledProcessError, plistlib.InvalidFileException):
+        return []
+    return [Path(entry["path"]) for entry in d["_items"]]
+
+
+def findSystemFonts(fontpaths=None, fontext='ttf'):
+    """
+    Search for fonts in the specified font paths.  If no paths are
+    given, will use a standard set of system paths, as well as the
+    list of fonts tracked by fontconfig if fontconfig is installed and
+    available.  A list of TrueType fonts are returned by default with
+    AFM fonts as an option.
+    """
+    fontfiles = set()
+    fontexts = get_fontext_synonyms(fontext)
+
+    if fontpaths is None:
+        if sys.platform == 'win32':
+            installed_fonts = _get_win32_installed_fonts()
+            fontpaths = []
+        else:
+            installed_fonts = _get_fontconfig_fonts()
+            if sys.platform == 'darwin':
+                installed_fonts += _get_macos_fonts()
+                fontpaths = [*X11FontDirectories, *OSXFontDirectories]
+            else:
+                fontpaths = X11FontDirectories
+        fontfiles.update(str(path) for path in installed_fonts
+                         if path.suffix.lower()[1:] in fontexts)
+
+    elif isinstance(fontpaths, str):
+        fontpaths = [fontpaths]
+
+    for path in fontpaths:
+        fontfiles.update(map(os.path.abspath, list_fonts(path, fontexts)))
+
+    return [fname for fname in fontfiles if os.path.exists(fname)]
+
+
+@dataclasses.dataclass(frozen=True)
+class FontEntry:
+    """
+    A class for storing Font properties.
+
+    It is used when populating the font lookup dictionary.
+    """
+
+    fname: str = ''
+    name: str = ''
+    style: str = 'normal'
+    variant: str = 'normal'
+    weight: str | int = 'normal'
+    stretch: str = 'normal'
+    size: str = 'medium'
+
+    def _repr_html_(self) -> str:
+        png_stream = self._repr_png_()
+        png_b64 = b64encode(png_stream).decode()
+        return f"<img src=\"data:image/png;base64, {png_b64}\" />"
+
+    def _repr_png_(self) -> bytes:
+        from matplotlib.figure import Figure  # Circular import.
+        fig = Figure()
+        font_path = Path(self.fname) if self.fname != '' else None
+        fig.text(0, 0, self.name, font=font_path)
+        with BytesIO() as buf:
+            fig.savefig(buf, bbox_inches='tight', transparent=True)
+            return buf.getvalue()
+
+
+def ttfFontProperty(font):
+    """
+    Extract information from a TrueType font file.
+
+    Parameters
+    ----------
+    font : `.FT2Font`
+        The TrueType font file from which information will be extracted.
+
+    Returns
+    -------
+    `FontEntry`
+        The extracted font properties.
+
+    """
+    name = font.family_name
+
+    #  Styles are: italic, oblique, and normal (default)
+
+    sfnt = font.get_sfnt()
+    mac_key = (1,  # platform: macintosh
+               0,  # id: roman
+               0)  # langid: english
+    ms_key = (3,  # platform: microsoft
+              1,  # id: unicode_cs
+              0x0409)  # langid: english_united_states
+
+    # These tables are actually mac_roman-encoded, but mac_roman support may be
+    # missing in some alternative Python implementations and we are only going
+    # to look for ASCII substrings, where any ASCII-compatible encoding works
+    # - or big-endian UTF-16, since important Microsoft fonts use that.
+    sfnt2 = (sfnt.get((*mac_key, 2), b'').decode('latin-1').lower() or
+             sfnt.get((*ms_key, 2), b'').decode('utf_16_be').lower())
+    sfnt4 = (sfnt.get((*mac_key, 4), b'').decode('latin-1').lower() or
+             sfnt.get((*ms_key, 4), b'').decode('utf_16_be').lower())
+
+    if sfnt4.find('oblique') >= 0:
+        style = 'oblique'
+    elif sfnt4.find('italic') >= 0:
+        style = 'italic'
+    elif sfnt2.find('regular') >= 0:
+        style = 'normal'
+    elif ft2font.StyleFlags.ITALIC in font.style_flags:
+        style = 'italic'
+    else:
+        style = 'normal'
+
+    #  Variants are: small-caps and normal (default)
+
+    #  !!!!  Untested
+    if name.lower() in ['capitals', 'small-caps']:
+        variant = 'small-caps'
+    else:
+        variant = 'normal'
+
+    # The weight-guessing algorithm is directly translated from fontconfig
+    # 2.13.1's FcFreeTypeQueryFaceInternal (fcfreetype.c).
+    wws_subfamily = 22
+    typographic_subfamily = 16
+    font_subfamily = 2
+    styles = [
+        sfnt.get((*mac_key, wws_subfamily), b'').decode('latin-1'),
+        sfnt.get((*mac_key, typographic_subfamily), b'').decode('latin-1'),
+        sfnt.get((*mac_key, font_subfamily), b'').decode('latin-1'),
+        sfnt.get((*ms_key, wws_subfamily), b'').decode('utf-16-be'),
+        sfnt.get((*ms_key, typographic_subfamily), b'').decode('utf-16-be'),
+        sfnt.get((*ms_key, font_subfamily), b'').decode('utf-16-be'),
+    ]
+    styles = [*filter(None, styles)] or [font.style_name]
+
+    def get_weight():  # From fontconfig's FcFreeTypeQueryFaceInternal.
+        # OS/2 table weight.
+        os2 = font.get_sfnt_table("OS/2")
+        if os2 and os2["version"] != 0xffff:
+            return os2["usWeightClass"]
+        # PostScript font info weight.
+        try:
+            ps_font_info_weight = (
+                font.get_ps_font_info()["weight"].replace(" ", "") or "")
+        except ValueError:
+            pass
+        else:
+            for regex, weight in _weight_regexes:
+                if re.fullmatch(regex, ps_font_info_weight, re.I):
+                    return weight
+        # Style name weight.
+        for style in styles:
+            style = style.replace(" ", "")
+            for regex, weight in _weight_regexes:
+                if re.search(regex, style, re.I):
+                    return weight
+        if ft2font.StyleFlags.BOLD in font.style_flags:
+            return 700  # "bold"
+        return 500  # "medium", not "regular"!
+
+    weight = int(get_weight())
+
+    #  Stretch can be absolute and relative
+    #  Absolute stretches are: ultra-condensed, extra-condensed, condensed,
+    #    semi-condensed, normal, semi-expanded, expanded, extra-expanded,
+    #    and ultra-expanded.
+    #  Relative stretches are: wider, narrower
+    #  Child value is: inherit
+
+    if any(word in sfnt4 for word in ['narrow', 'condensed', 'cond']):
+        stretch = 'condensed'
+    elif 'demi cond' in sfnt4:
+        stretch = 'semi-condensed'
+    elif any(word in sfnt4 for word in ['wide', 'expanded', 'extended']):
+        stretch = 'expanded'
+    else:
+        stretch = 'normal'
+
+    #  Sizes can be absolute and relative.
+    #  Absolute sizes are: xx-small, x-small, small, medium, large, x-large,
+    #    and xx-large.
+    #  Relative sizes are: larger, smaller
+    #  Length value is an absolute font size, e.g., 12pt
+    #  Percentage values are in 'em's.  Most robust specification.
+
+    if not font.scalable:
+        raise NotImplementedError("Non-scalable fonts are not supported")
+    size = 'scalable'
+
+    return FontEntry(font.fname, name, style, variant, weight, stretch, size)
+
+
+def afmFontProperty(fontpath, font):
+    """
+    Extract information from an AFM font file.
+
+    Parameters
+    ----------
+    fontpath : str
+        The filename corresponding to *font*.
+    font : AFM
+        The AFM font file from which information will be extracted.
+
+    Returns
+    -------
+    `FontEntry`
+        The extracted font properties.
+    """
+
+    name = font.get_familyname()
+    fontname = font.get_fontname().lower()
+
+    #  Styles are: italic, oblique, and normal (default)
+
+    if font.get_angle() != 0 or 'italic' in name.lower():
+        style = 'italic'
+    elif 'oblique' in name.lower():
+        style = 'oblique'
+    else:
+        style = 'normal'
+
+    #  Variants are: small-caps and normal (default)
+
+    # !!!!  Untested
+    if name.lower() in ['capitals', 'small-caps']:
+        variant = 'small-caps'
+    else:
+        variant = 'normal'
+
+    weight = font.get_weight().lower()
+    if weight not in weight_dict:
+        weight = 'normal'
+
+    #  Stretch can be absolute and relative
+    #  Absolute stretches are: ultra-condensed, extra-condensed, condensed,
+    #    semi-condensed, normal, semi-expanded, expanded, extra-expanded,
+    #    and ultra-expanded.
+    #  Relative stretches are: wider, narrower
+    #  Child value is: inherit
+    if 'demi cond' in fontname:
+        stretch = 'semi-condensed'
+    elif any(word in fontname for word in ['narrow', 'cond']):
+        stretch = 'condensed'
+    elif any(word in fontname for word in ['wide', 'expanded', 'extended']):
+        stretch = 'expanded'
+    else:
+        stretch = 'normal'
+
+    #  Sizes can be absolute and relative.
+    #  Absolute sizes are: xx-small, x-small, small, medium, large, x-large,
+    #    and xx-large.
+    #  Relative sizes are: larger, smaller
+    #  Length value is an absolute font size, e.g., 12pt
+    #  Percentage values are in 'em's.  Most robust specification.
+
+    #  All AFM fonts are apparently scalable.
+
+    size = 'scalable'
+
+    return FontEntry(fontpath, name, style, variant, weight, stretch, size)
+
+
+def _cleanup_fontproperties_init(init_method):
+    """
+    A decorator to limit the call signature to single a positional argument
+    or alternatively only keyword arguments.
+
+    We still accept but deprecate all other call signatures.
+
+    When the deprecation expires we can switch the signature to::
+
+        __init__(self, pattern=None, /, *, family=None, style=None, ...)
+
+    plus a runtime check that pattern is not used alongside with the
+    keyword arguments. This results eventually in the two possible
+    call signatures::
+
+        FontProperties(pattern)
+        FontProperties(family=..., size=..., ...)
+
+    """
+    @functools.wraps(init_method)
+    def wrapper(self, *args, **kwargs):
+        # multiple args with at least some positional ones
+        if len(args) > 1 or len(args) == 1 and kwargs:
+            # Note: Both cases were previously handled as individual properties.
+            # Therefore, we do not mention the case of font properties here.
+            _api.warn_deprecated(
+                "3.10",
+                message="Passing individual properties to FontProperties() "
+                        "positionally was deprecated in Matplotlib %(since)s and "
+                        "will be removed in %(removal)s. Please pass all properties "
+                        "via keyword arguments."
+            )
+        # single non-string arg -> clearly a family not a pattern
+        if len(args) == 1 and not kwargs and not cbook.is_scalar_or_string(args[0]):
+            # Case font-family list passed as single argument
+            _api.warn_deprecated(
+                "3.10",
+                message="Passing family as positional argument to FontProperties() "
+                        "was deprecated in Matplotlib %(since)s and will be removed "
+                        "in %(removal)s. Please pass family names as keyword"
+                        "argument."
+            )
+        # Note on single string arg:
+        # This has been interpreted as pattern so far. We are already raising if a
+        # non-pattern compatible family string was given. Therefore, we do not need
+        # to warn for this case.
+        return init_method(self, *args, **kwargs)
+
+    return wrapper
+
+
+class FontProperties:
+    """
+    A class for storing and manipulating font properties.
+
+    The font properties are the six properties described in the
+    `W3C Cascading Style Sheet, Level 1
+    <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_ font
+    specification and *math_fontfamily* for math fonts:
+
+    - family: A list of font names in decreasing order of priority.
+      The items may include a generic font family name, either 'sans-serif',
+      'serif', 'cursive', 'fantasy', or 'monospace'.  In that case, the actual
+      font to be used will be looked up from the associated rcParam during the
+      search process in `.findfont`. Default: :rc:`font.family`
+
+    - style: Either 'normal', 'italic' or 'oblique'.
+      Default: :rc:`font.style`
+
+    - variant: Either 'normal' or 'small-caps'.
+      Default: :rc:`font.variant`
+
+    - stretch: A numeric value in the range 0-1000 or one of
+      'ultra-condensed', 'extra-condensed', 'condensed',
+      'semi-condensed', 'normal', 'semi-expanded', 'expanded',
+      'extra-expanded' or 'ultra-expanded'. Default: :rc:`font.stretch`
+
+    - weight: A numeric value in the range 0-1000 or one of
+      'ultralight', 'light', 'normal', 'regular', 'book', 'medium',
+      'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy',
+      'extra bold', 'black'. Default: :rc:`font.weight`
+
+    - size: Either a relative value of 'xx-small', 'x-small',
+      'small', 'medium', 'large', 'x-large', 'xx-large' or an
+      absolute font size, e.g., 10. Default: :rc:`font.size`
+
+    - math_fontfamily: The family of fonts used to render math text.
+      Supported values are: 'dejavusans', 'dejavuserif', 'cm',
+      'stix', 'stixsans' and 'custom'. Default: :rc:`mathtext.fontset`
+
+    Alternatively, a font may be specified using the absolute path to a font
+    file, by using the *fname* kwarg.  However, in this case, it is typically
+    simpler to just pass the path (as a `pathlib.Path`, not a `str`) to the
+    *font* kwarg of the `.Text` object.
+
+    The preferred usage of font sizes is to use the relative values,
+    e.g.,  'large', instead of absolute font sizes, e.g., 12.  This
+    approach allows all text sizes to be made larger or smaller based
+    on the font manager's default font size.
+
+    This class accepts a single positional string as fontconfig_ pattern_,
+    or alternatively individual properties as keyword arguments::
+
+        FontProperties(pattern)
+        FontProperties(*, family=None, style=None, variant=None, ...)
+
+    This support does not depend on fontconfig; we are merely borrowing its
+    pattern syntax for use here.
+
+    .. _fontconfig: https://www.freedesktop.org/wiki/Software/fontconfig/
+    .. _pattern:
+       https://www.freedesktop.org/software/fontconfig/fontconfig-user.html
+
+    Note that Matplotlib's internal font manager and fontconfig use a
+    different algorithm to lookup fonts, so the results of the same pattern
+    may be different in Matplotlib than in other applications that use
+    fontconfig.
+    """
+
+    @_cleanup_fontproperties_init
+    def __init__(self, family=None, style=None, variant=None, weight=None,
+                 stretch=None, size=None,
+                 fname=None,  # if set, it's a hardcoded filename to use
+                 math_fontfamily=None):
+        self.set_family(family)
+        self.set_style(style)
+        self.set_variant(variant)
+        self.set_weight(weight)
+        self.set_stretch(stretch)
+        self.set_file(fname)
+        self.set_size(size)
+        self.set_math_fontfamily(math_fontfamily)
+        # Treat family as a fontconfig pattern if it is the only parameter
+        # provided.  Even in that case, call the other setters first to set
+        # attributes not specified by the pattern to the rcParams defaults.
+        if (isinstance(family, str)
+                and style is None and variant is None and weight is None
+                and stretch is None and size is None and fname is None):
+            self.set_fontconfig_pattern(family)
+
+    @classmethod
+    def _from_any(cls, arg):
+        """
+        Generic constructor which can build a `.FontProperties` from any of the
+        following:
+
+        - a `.FontProperties`: it is passed through as is;
+        - `None`: a `.FontProperties` using rc values is used;
+        - an `os.PathLike`: it is used as path to the font file;
+        - a `str`: it is parsed as a fontconfig pattern;
+        - a `dict`: it is passed as ``**kwargs`` to `.FontProperties`.
+        """
+        if arg is None:
+            return cls()
+        elif isinstance(arg, cls):
+            return arg
+        elif isinstance(arg, os.PathLike):
+            return cls(fname=arg)
+        elif isinstance(arg, str):
+            return cls(arg)
+        else:
+            return cls(**arg)
+
+    def __hash__(self):
+        l = (tuple(self.get_family()),
+             self.get_slant(),
+             self.get_variant(),
+             self.get_weight(),
+             self.get_stretch(),
+             self.get_size(),
+             self.get_file(),
+             self.get_math_fontfamily())
+        return hash(l)
+
+    def __eq__(self, other):
+        return hash(self) == hash(other)
+
+    def __str__(self):
+        return self.get_fontconfig_pattern()
+
+    def get_family(self):
+        """
+        Return a list of individual font family names or generic family names.
+
+        The font families or generic font families (which will be resolved
+        from their respective rcParams when searching for a matching font) in
+        the order of preference.
+        """
+        return self._family
+
+    def get_name(self):
+        """
+        Return the name of the font that best matches the font properties.
+        """
+        return get_font(findfont(self)).family_name
+
+    def get_style(self):
+        """
+        Return the font style.  Values are: 'normal', 'italic' or 'oblique'.
+        """
+        return self._slant
+
+    def get_variant(self):
+        """
+        Return the font variant.  Values are: 'normal' or 'small-caps'.
+        """
+        return self._variant
+
+    def get_weight(self):
+        """
+        Set the font weight.  Options are: A numeric value in the
+        range 0-1000 or one of 'light', 'normal', 'regular', 'book',
+        'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold',
+        'heavy', 'extra bold', 'black'
+        """
+        return self._weight
+
+    def get_stretch(self):
+        """
+        Return the font stretch or width.  Options are: 'ultra-condensed',
+        'extra-condensed', 'condensed', 'semi-condensed', 'normal',
+        'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'.
+        """
+        return self._stretch
+
+    def get_size(self):
+        """
+        Return the font size.
+        """
+        return self._size
+
+    def get_file(self):
+        """
+        Return the filename of the associated font.
+        """
+        return self._file
+
+    def get_fontconfig_pattern(self):
+        """
+        Get a fontconfig_ pattern_ suitable for looking up the font as
+        specified with fontconfig's ``fc-match`` utility.
+
+        This support does not depend on fontconfig; we are merely borrowing its
+        pattern syntax for use here.
+        """
+        return generate_fontconfig_pattern(self)
+
+    def set_family(self, family):
+        """
+        Change the font family.  Can be either an alias (generic name
+        is CSS parlance), such as: 'serif', 'sans-serif', 'cursive',
+        'fantasy', or 'monospace', a real font name or a list of real
+        font names.  Real font names are not supported when
+        :rc:`text.usetex` is `True`. Default: :rc:`font.family`
+        """
+        if family is None:
+            family = mpl.rcParams['font.family']
+        if isinstance(family, str):
+            family = [family]
+        self._family = family
+
+    def set_style(self, style):
+        """
+        Set the font style.
+
+        Parameters
+        ----------
+        style : {'normal', 'italic', 'oblique'}, default: :rc:`font.style`
+        """
+        if style is None:
+            style = mpl.rcParams['font.style']
+        _api.check_in_list(['normal', 'italic', 'oblique'], style=style)
+        self._slant = style
+
+    def set_variant(self, variant):
+        """
+        Set the font variant.
+
+        Parameters
+        ----------
+        variant : {'normal', 'small-caps'}, default: :rc:`font.variant`
+        """
+        if variant is None:
+            variant = mpl.rcParams['font.variant']
+        _api.check_in_list(['normal', 'small-caps'], variant=variant)
+        self._variant = variant
+
+    def set_weight(self, weight):
+        """
+        Set the font weight.
+
+        Parameters
+        ----------
+        weight : int or {'ultralight', 'light', 'normal', 'regular', 'book', \
+'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', \
+'extra bold', 'black'}, default: :rc:`font.weight`
+            If int, must be in the range  0-1000.
+        """
+        if weight is None:
+            weight = mpl.rcParams['font.weight']
+        if weight in weight_dict:
+            self._weight = weight
+            return
+        try:
+            weight = int(weight)
+        except ValueError:
+            pass
+        else:
+            if 0 <= weight <= 1000:
+                self._weight = weight
+                return
+        raise ValueError(f"{weight=} is invalid")
+
+    def set_stretch(self, stretch):
+        """
+        Set the font stretch or width.
+
+        Parameters
+        ----------
+        stretch : int or {'ultra-condensed', 'extra-condensed', 'condensed', \
+'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', \
+'ultra-expanded'}, default: :rc:`font.stretch`
+            If int, must be in the range  0-1000.
+        """
+        if stretch is None:
+            stretch = mpl.rcParams['font.stretch']
+        if stretch in stretch_dict:
+            self._stretch = stretch
+            return
+        try:
+            stretch = int(stretch)
+        except ValueError:
+            pass
+        else:
+            if 0 <= stretch <= 1000:
+                self._stretch = stretch
+                return
+        raise ValueError(f"{stretch=} is invalid")
+
+    def set_size(self, size):
+        """
+        Set the font size.
+
+        Parameters
+        ----------
+        size : float or {'xx-small', 'x-small', 'small', 'medium', \
+'large', 'x-large', 'xx-large'}, default: :rc:`font.size`
+            If a float, the font size in points. The string values denote
+            sizes relative to the default font size.
+        """
+        if size is None:
+            size = mpl.rcParams['font.size']
+        try:
+            size = float(size)
+        except ValueError:
+            try:
+                scale = font_scalings[size]
+            except KeyError as err:
+                raise ValueError(
+                    "Size is invalid. Valid font size are "
+                    + ", ".join(map(str, font_scalings))) from err
+            else:
+                size = scale * FontManager.get_default_size()
+        if size < 1.0:
+            _log.info('Fontsize %1.2f < 1.0 pt not allowed by FreeType. '
+                      'Setting fontsize = 1 pt', size)
+            size = 1.0
+        self._size = size
+
+    def set_file(self, file):
+        """
+        Set the filename of the fontfile to use.  In this case, all
+        other properties will be ignored.
+        """
+        self._file = os.fspath(file) if file is not None else None
+
+    def set_fontconfig_pattern(self, pattern):
+        """
+        Set the properties by parsing a fontconfig_ *pattern*.
+
+        This support does not depend on fontconfig; we are merely borrowing its
+        pattern syntax for use here.
+        """
+        for key, val in parse_fontconfig_pattern(pattern).items():
+            if type(val) is list:
+                getattr(self, "set_" + key)(val[0])
+            else:
+                getattr(self, "set_" + key)(val)
+
+    def get_math_fontfamily(self):
+        """
+        Return the name of the font family used for math text.
+
+        The default font is :rc:`mathtext.fontset`.
+        """
+        return self._math_fontfamily
+
+    def set_math_fontfamily(self, fontfamily):
+        """
+        Set the font family for text in math mode.
+
+        If not set explicitly, :rc:`mathtext.fontset` will be used.
+
+        Parameters
+        ----------
+        fontfamily : str
+            The name of the font family.
+
+            Available font families are defined in the
+            :ref:`default matplotlibrc file <customizing-with-matplotlibrc-files>`.
+
+        See Also
+        --------
+        .text.Text.get_math_fontfamily
+        """
+        if fontfamily is None:
+            fontfamily = mpl.rcParams['mathtext.fontset']
+        else:
+            valid_fonts = _validators['mathtext.fontset'].valid.values()
+            # _check_in_list() Validates the parameter math_fontfamily as
+            # if it were passed to rcParams['mathtext.fontset']
+            _api.check_in_list(valid_fonts, math_fontfamily=fontfamily)
+        self._math_fontfamily = fontfamily
+
+    def copy(self):
+        """Return a copy of self."""
+        return copy.copy(self)
+
+    # Aliases
+    set_name = set_family
+    get_slant = get_style
+    set_slant = set_style
+    get_size_in_points = get_size
+
+
+class _JSONEncoder(json.JSONEncoder):
+    def default(self, o):
+        if isinstance(o, FontManager):
+            return dict(o.__dict__, __class__='FontManager')
+        elif isinstance(o, FontEntry):
+            d = dict(o.__dict__, __class__='FontEntry')
+            try:
+                # Cache paths of fonts shipped with Matplotlib relative to the
+                # Matplotlib data path, which helps in the presence of venvs.
+                d["fname"] = str(Path(d["fname"]).relative_to(mpl.get_data_path()))
+            except ValueError:
+                pass
+            return d
+        else:
+            return super().default(o)
+
+
+def _json_decode(o):
+    cls = o.pop('__class__', None)
+    if cls is None:
+        return o
+    elif cls == 'FontManager':
+        r = FontManager.__new__(FontManager)
+        r.__dict__.update(o)
+        return r
+    elif cls == 'FontEntry':
+        if not os.path.isabs(o['fname']):
+            o['fname'] = os.path.join(mpl.get_data_path(), o['fname'])
+        r = FontEntry(**o)
+        return r
+    else:
+        raise ValueError("Don't know how to deserialize __class__=%s" % cls)
+
+
+def json_dump(data, filename):
+    """
+    Dump `FontManager` *data* as JSON to the file named *filename*.
+
+    See Also
+    --------
+    json_load
+
+    Notes
+    -----
+    File paths that are children of the Matplotlib data path (typically, fonts
+    shipped with Matplotlib) are stored relative to that data path (to remain
+    valid across virtualenvs).
+
+    This function temporarily locks the output file to prevent multiple
+    processes from overwriting one another's output.
+    """
+    try:
+        with cbook._lock_path(filename), open(filename, 'w') as fh:
+            json.dump(data, fh, cls=_JSONEncoder, indent=2)
+    except OSError as e:
+        _log.warning('Could not save font_manager cache %s', e)
+
+
+def json_load(filename):
+    """
+    Load a `FontManager` from the JSON file named *filename*.
+
+    See Also
+    --------
+    json_dump
+    """
+    with open(filename) as fh:
+        return json.load(fh, object_hook=_json_decode)
+
+
+class FontManager:
+    """
+    On import, the `FontManager` singleton instance creates a list of ttf and
+    afm fonts and caches their `FontProperties`.  The `FontManager.findfont`
+    method does a nearest neighbor search to find the font that most closely
+    matches the specification.  If no good enough match is found, the default
+    font is returned.
+
+    Fonts added with the `FontManager.addfont` method will not persist in the
+    cache; therefore, `addfont` will need to be called every time Matplotlib is
+    imported. This method should only be used if and when a font cannot be
+    installed on your operating system by other means.
+
+    Notes
+    -----
+    The `FontManager.addfont` method must be called on the global `FontManager`
+    instance.
+
+    Example usage::
+
+        import matplotlib.pyplot as plt
+        from matplotlib import font_manager
+
+        font_dirs = ["/resources/fonts"]  # The path to the custom font file.
+        font_files = font_manager.findSystemFonts(fontpaths=font_dirs)
+
+        for font_file in font_files:
+            font_manager.fontManager.addfont(font_file)
+    """
+    # Increment this version number whenever the font cache data
+    # format or behavior has changed and requires an existing font
+    # cache files to be rebuilt.
+    __version__ = 390
+
+    def __init__(self, size=None, weight='normal'):
+        self._version = self.__version__
+
+        self.__default_weight = weight
+        self.default_size = size
+
+        # Create list of font paths.
+        paths = [cbook._get_data_path('fonts', subdir)
+                 for subdir in ['ttf', 'afm', 'pdfcorefonts']]
+        _log.debug('font search path %s', paths)
+
+        self.defaultFamily = {
+            'ttf': 'DejaVu Sans',
+            'afm': 'Helvetica'}
+
+        self.afmlist = []
+        self.ttflist = []
+
+        # Delay the warning by 5s.
+        timer = threading.Timer(5, lambda: _log.warning(
+            'Matplotlib is building the font cache; this may take a moment.'))
+        timer.start()
+        try:
+            for fontext in ["afm", "ttf"]:
+                for path in [*findSystemFonts(paths, fontext=fontext),
+                             *findSystemFonts(fontext=fontext)]:
+                    try:
+                        self.addfont(path)
+                    except OSError as exc:
+                        _log.info("Failed to open font file %s: %s", path, exc)
+                    except Exception as exc:
+                        _log.info("Failed to extract font properties from %s: "
+                                  "%s", path, exc)
+        finally:
+            timer.cancel()
+
+    def addfont(self, path):
+        """
+        Cache the properties of the font at *path* to make it available to the
+        `FontManager`.  The type of font is inferred from the path suffix.
+
+        Parameters
+        ----------
+        path : str or path-like
+
+        Notes
+        -----
+        This method is useful for adding a custom font without installing it in
+        your operating system. See the `FontManager` singleton instance for
+        usage and caveats about this function.
+        """
+        # Convert to string in case of a path as
+        # afmFontProperty and FT2Font expect this
+        path = os.fsdecode(path)
+        if Path(path).suffix.lower() == ".afm":
+            with open(path, "rb") as fh:
+                font = _afm.AFM(fh)
+            prop = afmFontProperty(path, font)
+            self.afmlist.append(prop)
+        else:
+            font = ft2font.FT2Font(path)
+            prop = ttfFontProperty(font)
+            self.ttflist.append(prop)
+        self._findfont_cached.cache_clear()
+
+    @property
+    def defaultFont(self):
+        # Lazily evaluated (findfont then caches the result) to avoid including
+        # the venv path in the json serialization.
+        return {ext: self.findfont(family, fontext=ext)
+                for ext, family in self.defaultFamily.items()}
+
+    def get_default_weight(self):
+        """
+        Return the default font weight.
+        """
+        return self.__default_weight
+
+    @staticmethod
+    def get_default_size():
+        """
+        Return the default font size.
+        """
+        return mpl.rcParams['font.size']
+
+    def set_default_weight(self, weight):
+        """
+        Set the default font weight.  The initial value is 'normal'.
+        """
+        self.__default_weight = weight
+
+    @staticmethod
+    def _expand_aliases(family):
+        if family in ('sans', 'sans serif'):
+            family = 'sans-serif'
+        return mpl.rcParams['font.' + family]
+
+    # Each of the scoring functions below should return a value between
+    # 0.0 (perfect match) and 1.0 (terrible match)
+    def score_family(self, families, family2):
+        """
+        Return a match score between the list of font families in
+        *families* and the font family name *family2*.
+
+        An exact match at the head of the list returns 0.0.
+
+        A match further down the list will return between 0 and 1.
+
+        No match will return 1.0.
+        """
+        if not isinstance(families, (list, tuple)):
+            families = [families]
+        elif len(families) == 0:
+            return 1.0
+        family2 = family2.lower()
+        step = 1 / len(families)
+        for i, family1 in enumerate(families):
+            family1 = family1.lower()
+            if family1 in font_family_aliases:
+                options = [*map(str.lower, self._expand_aliases(family1))]
+                if family2 in options:
+                    idx = options.index(family2)
+                    return (i + (idx / len(options))) * step
+            elif family1 == family2:
+                # The score should be weighted by where in the
+                # list the font was found.
+                return i * step
+        return 1.0
+
+    def score_style(self, style1, style2):
+        """
+        Return a match score between *style1* and *style2*.
+
+        An exact match returns 0.0.
+
+        A match between 'italic' and 'oblique' returns 0.1.
+
+        No match returns 1.0.
+        """
+        if style1 == style2:
+            return 0.0
+        elif (style1 in ('italic', 'oblique')
+              and style2 in ('italic', 'oblique')):
+            return 0.1
+        return 1.0
+
+    def score_variant(self, variant1, variant2):
+        """
+        Return a match score between *variant1* and *variant2*.
+
+        An exact match returns 0.0, otherwise 1.0.
+        """
+        if variant1 == variant2:
+            return 0.0
+        else:
+            return 1.0
+
+    def score_stretch(self, stretch1, stretch2):
+        """
+        Return a match score between *stretch1* and *stretch2*.
+
+        The result is the absolute value of the difference between the
+        CSS numeric values of *stretch1* and *stretch2*, normalized
+        between 0.0 and 1.0.
+        """
+        try:
+            stretchval1 = int(stretch1)
+        except ValueError:
+            stretchval1 = stretch_dict.get(stretch1, 500)
+        try:
+            stretchval2 = int(stretch2)
+        except ValueError:
+            stretchval2 = stretch_dict.get(stretch2, 500)
+        return abs(stretchval1 - stretchval2) / 1000.0
+
+    def score_weight(self, weight1, weight2):
+        """
+        Return a match score between *weight1* and *weight2*.
+
+        The result is 0.0 if both weight1 and weight 2 are given as strings
+        and have the same value.
+
+        Otherwise, the result is the absolute value of the difference between
+        the CSS numeric values of *weight1* and *weight2*, normalized between
+        0.05 and 1.0.
+        """
+        # exact match of the weight names, e.g. weight1 == weight2 == "regular"
+        if cbook._str_equal(weight1, weight2):
+            return 0.0
+        w1 = weight1 if isinstance(weight1, Number) else weight_dict[weight1]
+        w2 = weight2 if isinstance(weight2, Number) else weight_dict[weight2]
+        return 0.95 * (abs(w1 - w2) / 1000) + 0.05
+
+    def score_size(self, size1, size2):
+        """
+        Return a match score between *size1* and *size2*.
+
+        If *size2* (the size specified in the font file) is 'scalable', this
+        function always returns 0.0, since any font size can be generated.
+
+        Otherwise, the result is the absolute distance between *size1* and
+        *size2*, normalized so that the usual range of font sizes (6pt -
+        72pt) will lie between 0.0 and 1.0.
+        """
+        if size2 == 'scalable':
+            return 0.0
+        # Size value should have already been
+        try:
+            sizeval1 = float(size1)
+        except ValueError:
+            sizeval1 = self.default_size * font_scalings[size1]
+        try:
+            sizeval2 = float(size2)
+        except ValueError:
+            return 1.0
+        return abs(sizeval1 - sizeval2) / 72
+
+    def findfont(self, prop, fontext='ttf', directory=None,
+                 fallback_to_default=True, rebuild_if_missing=True):
+        """
+        Find the path to the font file most closely matching the given font properties.
+
+        Parameters
+        ----------
+        prop : str or `~matplotlib.font_manager.FontProperties`
+            The font properties to search for. This can be either a
+            `.FontProperties` object or a string defining a
+            `fontconfig patterns`_.
+
+        fontext : {'ttf', 'afm'}, default: 'ttf'
+            The extension of the font file:
+
+            - 'ttf': TrueType and OpenType fonts (.ttf, .ttc, .otf)
+            - 'afm': Adobe Font Metrics (.afm)
+
+        directory : str, optional
+            If given, only search this directory and its subdirectories.
+
+        fallback_to_default : bool
+            If True, will fall back to the default font family (usually
+            "DejaVu Sans" or "Helvetica") if the first lookup hard-fails.
+
+        rebuild_if_missing : bool
+            Whether to rebuild the font cache and search again if the first
+            match appears to point to a nonexisting font (i.e., the font cache
+            contains outdated entries).
+
+        Returns
+        -------
+        str
+            The filename of the best matching font.
+
+        Notes
+        -----
+        This performs a nearest neighbor search.  Each font is given a
+        similarity score to the target font properties.  The first font with
+        the highest score is returned.  If no matches below a certain
+        threshold are found, the default font (usually DejaVu Sans) is
+        returned.
+
+        The result is cached, so subsequent lookups don't have to
+        perform the O(n) nearest neighbor search.
+
+        See the `W3C Cascading Style Sheet, Level 1
+        <http://www.w3.org/TR/1998/REC-CSS2-19980512/>`_ documentation
+        for a description of the font finding algorithm.
+
+        .. _fontconfig patterns:
+           https://www.freedesktop.org/software/fontconfig/fontconfig-user.html
+        """
+        # Pass the relevant rcParams (and the font manager, as `self`) to
+        # _findfont_cached so to prevent using a stale cache entry after an
+        # rcParam was changed.
+        rc_params = tuple(tuple(mpl.rcParams[key]) for key in [
+            "font.serif", "font.sans-serif", "font.cursive", "font.fantasy",
+            "font.monospace"])
+        ret = self._findfont_cached(
+            prop, fontext, directory, fallback_to_default, rebuild_if_missing,
+            rc_params)
+        if isinstance(ret, cbook._ExceptionInfo):
+            raise ret.to_exception()
+        return ret
+
+    def get_font_names(self):
+        """Return the list of available fonts."""
+        return list({font.name for font in self.ttflist})
+
+    def _find_fonts_by_props(self, prop, fontext='ttf', directory=None,
+                             fallback_to_default=True, rebuild_if_missing=True):
+        """
+        Find the paths to the font files most closely matching the given properties.
+
+        Parameters
+        ----------
+        prop : str or `~matplotlib.font_manager.FontProperties`
+            The font properties to search for. This can be either a
+            `.FontProperties` object or a string defining a
+            `fontconfig patterns`_.
+
+        fontext : {'ttf', 'afm'}, default: 'ttf'
+            The extension of the font file:
+
+            - 'ttf': TrueType and OpenType fonts (.ttf, .ttc, .otf)
+            - 'afm': Adobe Font Metrics (.afm)
+
+        directory : str, optional
+            If given, only search this directory and its subdirectories.
+
+        fallback_to_default : bool
+            If True, will fall back to the default font family (usually
+            "DejaVu Sans" or "Helvetica") if none of the families were found.
+
+        rebuild_if_missing : bool
+            Whether to rebuild the font cache and search again if the first
+            match appears to point to a nonexisting font (i.e., the font cache
+            contains outdated entries).
+
+        Returns
+        -------
+        list[str]
+            The paths of the fonts found.
+
+        Notes
+        -----
+        This is an extension/wrapper of the original findfont API, which only
+        returns a single font for given font properties. Instead, this API
+        returns a list of filepaths of multiple fonts which closely match the
+        given font properties.  Since this internally uses the original API,
+        there's no change to the logic of performing the nearest neighbor
+        search.  See `findfont` for more details.
+        """
+
+        prop = FontProperties._from_any(prop)
+
+        fpaths = []
+        for family in prop.get_family():
+            cprop = prop.copy()
+            cprop.set_family(family)  # set current prop's family
+
+            try:
+                fpaths.append(
+                    self.findfont(
+                        cprop, fontext, directory,
+                        fallback_to_default=False,  # don't fallback to default
+                        rebuild_if_missing=rebuild_if_missing,
+                    )
+                )
+            except ValueError:
+                if family in font_family_aliases:
+                    _log.warning(
+                        "findfont: Generic family %r not found because "
+                        "none of the following families were found: %s",
+                        family, ", ".join(self._expand_aliases(family))
+                    )
+                else:
+                    _log.warning("findfont: Font family %r not found.", family)
+
+        # only add default family if no other font was found and
+        # fallback_to_default is enabled
+        if not fpaths:
+            if fallback_to_default:
+                dfamily = self.defaultFamily[fontext]
+                cprop = prop.copy()
+                cprop.set_family(dfamily)
+                fpaths.append(
+                    self.findfont(
+                        cprop, fontext, directory,
+                        fallback_to_default=True,
+                        rebuild_if_missing=rebuild_if_missing,
+                    )
+                )
+            else:
+                raise ValueError("Failed to find any font, and fallback "
+                                 "to the default font was disabled")
+
+        return fpaths
+
+    @lru_cache(1024)
+    def _findfont_cached(self, prop, fontext, directory, fallback_to_default,
+                         rebuild_if_missing, rc_params):
+
+        prop = FontProperties._from_any(prop)
+
+        fname = prop.get_file()
+        if fname is not None:
+            return fname
+
+        if fontext == 'afm':
+            fontlist = self.afmlist
+        else:
+            fontlist = self.ttflist
+
+        best_score = 1e64
+        best_font = None
+
+        _log.debug('findfont: Matching %s.', prop)
+        for font in fontlist:
+            if (directory is not None and
+                    Path(directory) not in Path(font.fname).parents):
+                continue
+            # Matching family should have top priority, so multiply it by 10.
+            score = (self.score_family(prop.get_family(), font.name) * 10
+                     + self.score_style(prop.get_style(), font.style)
+                     + self.score_variant(prop.get_variant(), font.variant)
+                     + self.score_weight(prop.get_weight(), font.weight)
+                     + self.score_stretch(prop.get_stretch(), font.stretch)
+                     + self.score_size(prop.get_size(), font.size))
+            _log.debug('findfont: score(%s) = %s', font, score)
+            if score < best_score:
+                best_score = score
+                best_font = font
+            if score == 0:
+                break
+
+        if best_font is None or best_score >= 10.0:
+            if fallback_to_default:
+                _log.warning(
+                    'findfont: Font family %s not found. Falling back to %s.',
+                    prop.get_family(), self.defaultFamily[fontext])
+                for family in map(str.lower, prop.get_family()):
+                    if family in font_family_aliases:
+                        _log.warning(
+                            "findfont: Generic family %r not found because "
+                            "none of the following families were found: %s",
+                            family, ", ".join(self._expand_aliases(family)))
+                default_prop = prop.copy()
+                default_prop.set_family(self.defaultFamily[fontext])
+                return self.findfont(default_prop, fontext, directory,
+                                     fallback_to_default=False)
+            else:
+                # This return instead of raise is intentional, as we wish to
+                # cache that it was not found, which will not occur if it was
+                # actually raised.
+                return cbook._ExceptionInfo(
+                    ValueError,
+                    f"Failed to find font {prop}, and fallback to the default font was "
+                    f"disabled"
+                )
+        else:
+            _log.debug('findfont: Matching %s to %s (%r) with score of %f.',
+                       prop, best_font.name, best_font.fname, best_score)
+            result = best_font.fname
+
+        if not os.path.isfile(result):
+            if rebuild_if_missing:
+                _log.info(
+                    'findfont: Found a missing font file.  Rebuilding cache.')
+                new_fm = _load_fontmanager(try_read_cache=False)
+                # Replace self by the new fontmanager, because users may have
+                # a reference to this specific instance.
+                # TODO: _load_fontmanager should really be (used by) a method
+                # modifying the instance in place.
+                vars(self).update(vars(new_fm))
+                return self.findfont(
+                    prop, fontext, directory, rebuild_if_missing=False)
+            else:
+                # This return instead of raise is intentional, as we wish to
+                # cache that it was not found, which will not occur if it was
+                # actually raised.
+                return cbook._ExceptionInfo(ValueError, "No valid font could be found")
+
+        return _cached_realpath(result)
+
+
+@lru_cache
+def is_opentype_cff_font(filename):
+    """
+    Return whether the given font is a Postscript Compact Font Format Font
+    embedded in an OpenType wrapper.  Used by the PostScript and PDF backends
+    that cannot subset these fonts.
+    """
+    if os.path.splitext(filename)[1].lower() == '.otf':
+        with open(filename, 'rb') as fd:
+            return fd.read(4) == b"OTTO"
+    else:
+        return False
+
+
+@lru_cache(64)
+def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id):
+    first_fontpath, *rest = font_filepaths
+    return ft2font.FT2Font(
+        first_fontpath, hinting_factor,
+        _fallback_list=[
+            ft2font.FT2Font(
+                fpath, hinting_factor,
+                _kerning_factor=_kerning_factor
+            )
+            for fpath in rest
+        ],
+        _kerning_factor=_kerning_factor
+    )
+
+
+# FT2Font objects cannot be used across fork()s because they reference the same
+# FT_Library object.  While invalidating *all* existing FT2Fonts after a fork
+# would be too complicated to be worth it, the main way FT2Fonts get reused is
+# via the cache of _get_font, which we can empty upon forking (not on Windows,
+# which has no fork() or register_at_fork()).
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_get_font.cache_clear)
+
+
+@lru_cache(64)
+def _cached_realpath(path):
+    # Resolving the path avoids embedding the font twice in pdf/ps output if a
+    # single font is selected using two different relative paths.
+    return os.path.realpath(path)
+
+
+def get_font(font_filepaths, hinting_factor=None):
+    """
+    Get an `.ft2font.FT2Font` object given a list of file paths.
+
+    Parameters
+    ----------
+    font_filepaths : Iterable[str, Path, bytes], str, Path, bytes
+        Relative or absolute paths to the font files to be used.
+
+        If a single string, bytes, or `pathlib.Path`, then it will be treated
+        as a list with that entry only.
+
+        If more than one filepath is passed, then the returned FT2Font object
+        will fall back through the fonts, in the order given, to find a needed
+        glyph.
+
+    Returns
+    -------
+    `.ft2font.FT2Font`
+
+    """
+    if isinstance(font_filepaths, (str, Path, bytes)):
+        paths = (_cached_realpath(font_filepaths),)
+    else:
+        paths = tuple(_cached_realpath(fname) for fname in font_filepaths)
+
+    if hinting_factor is None:
+        hinting_factor = mpl.rcParams['text.hinting_factor']
+
+    return _get_font(
+        # must be a tuple to be cached
+        paths,
+        hinting_factor,
+        _kerning_factor=mpl.rcParams['text.kerning_factor'],
+        # also key on the thread ID to prevent segfaults with multi-threading
+        thread_id=threading.get_ident()
+    )
+
+
+def _load_fontmanager(*, try_read_cache=True):
+    fm_path = Path(
+        mpl.get_cachedir(), f"fontlist-v{FontManager.__version__}.json")
+    if try_read_cache:
+        try:
+            fm = json_load(fm_path)
+        except Exception:
+            pass
+        else:
+            if getattr(fm, "_version", object()) == FontManager.__version__:
+                _log.debug("Using fontManager instance from %s", fm_path)
+                return fm
+    fm = FontManager()
+    json_dump(fm, fm_path)
+    _log.info("generated new fontManager")
+    return fm
+
+
+fontManager = _load_fontmanager()
+findfont = fontManager.findfont
+get_font_names = fontManager.get_font_names
diff --git a/lib/python3.12/site-packages/matplotlib/font_manager.pyi b/lib/python3.12/site-packages/matplotlib/font_manager.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..48d0e362d5994923e4b6e9e963e96177c8bc7fcb
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/font_manager.pyi
@@ -0,0 +1,136 @@
+from dataclasses import dataclass
+import os
+
+from matplotlib._afm import AFM
+from matplotlib import ft2font
+
+from pathlib import Path
+
+from collections.abc import Iterable
+from typing import Any, Literal
+
+font_scalings: dict[str | None, float]
+stretch_dict: dict[str, int]
+weight_dict: dict[str, int]
+font_family_aliases: set[str]
+MSFolders: str
+MSFontDirectories: list[str]
+MSUserFontDirectories: list[str]
+X11FontDirectories: list[str]
+OSXFontDirectories: list[str]
+
+def get_fontext_synonyms(fontext: str) -> list[str]: ...
+def list_fonts(directory: str, extensions: Iterable[str]) -> list[str]: ...
+def win32FontDirectory() -> str: ...
+def _get_fontconfig_fonts() -> list[Path]: ...
+def findSystemFonts(
+    fontpaths: Iterable[str | os.PathLike | Path] | None = ..., fontext: str = ...
+) -> list[str]: ...
+@dataclass
+class FontEntry:
+    fname: str = ...
+    name: str = ...
+    style: str = ...
+    variant: str = ...
+    weight: str | int = ...
+    stretch: str = ...
+    size: str = ...
+    def _repr_html_(self) -> str: ...
+    def _repr_png_(self) -> bytes: ...
+
+def ttfFontProperty(font: ft2font.FT2Font) -> FontEntry: ...
+def afmFontProperty(fontpath: str, font: AFM) -> FontEntry: ...
+
+class FontProperties:
+    def __init__(
+        self,
+        family: str | Iterable[str] | None = ...,
+        style: Literal["normal", "italic", "oblique"] | None = ...,
+        variant: Literal["normal", "small-caps"] | None = ...,
+        weight: int | str | None = ...,
+        stretch: int | str | None = ...,
+        size: float | str | None = ...,
+        fname: str | os.PathLike | Path | None = ...,
+        math_fontfamily: str | None = ...,
+    ) -> None: ...
+    def __hash__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def get_family(self) -> list[str]: ...
+    def get_name(self) -> str: ...
+    def get_style(self) -> Literal["normal", "italic", "oblique"]: ...
+    def get_variant(self) -> Literal["normal", "small-caps"]: ...
+    def get_weight(self) -> int | str: ...
+    def get_stretch(self) -> int | str: ...
+    def get_size(self) -> float: ...
+    def get_file(self) -> str | bytes | None: ...
+    def get_fontconfig_pattern(self) -> dict[str, list[Any]]: ...
+    def set_family(self, family: str | Iterable[str] | None) -> None: ...
+    def set_style(
+        self, style: Literal["normal", "italic", "oblique"] | None
+    ) -> None: ...
+    def set_variant(self, variant: Literal["normal", "small-caps"] | None) -> None: ...
+    def set_weight(self, weight: int | str | None) -> None: ...
+    def set_stretch(self, stretch: int | str | None) -> None: ...
+    def set_size(self, size: float | str | None) -> None: ...
+    def set_file(self, file: str | os.PathLike | Path | None) -> None: ...
+    def set_fontconfig_pattern(self, pattern: str) -> None: ...
+    def get_math_fontfamily(self) -> str: ...
+    def set_math_fontfamily(self, fontfamily: str | None) -> None: ...
+    def copy(self) -> FontProperties: ...
+    # Aliases
+    set_name = set_family
+    get_slant = get_style
+    set_slant = set_style
+    get_size_in_points = get_size
+
+def json_dump(data: FontManager, filename: str | Path | os.PathLike) -> None: ...
+def json_load(filename: str | Path | os.PathLike) -> FontManager: ...
+
+class FontManager:
+    __version__: int
+    default_size: float | None
+    defaultFamily: dict[str, str]
+    afmlist: list[FontEntry]
+    ttflist: list[FontEntry]
+    def __init__(self, size: float | None = ..., weight: str = ...) -> None: ...
+    def addfont(self, path: str | Path | os.PathLike) -> None: ...
+    @property
+    def defaultFont(self) -> dict[str, str]: ...
+    def get_default_weight(self) -> str: ...
+    @staticmethod
+    def get_default_size() -> float: ...
+    def set_default_weight(self, weight: str) -> None: ...
+    def score_family(
+        self, families: str | list[str] | tuple[str], family2: str
+    ) -> float: ...
+    def score_style(self, style1: str, style2: str) -> float: ...
+    def score_variant(self, variant1: str, variant2: str) -> float: ...
+    def score_stretch(self, stretch1: str | int, stretch2: str | int) -> float: ...
+    def score_weight(self, weight1: str | float, weight2: str | float) -> float: ...
+    def score_size(self, size1: str | float, size2: str | float) -> float: ...
+    def findfont(
+        self,
+        prop: str | FontProperties,
+        fontext: Literal["ttf", "afm"] = ...,
+        directory: str | None = ...,
+        fallback_to_default: bool = ...,
+        rebuild_if_missing: bool = ...,
+    ) -> str: ...
+    def get_font_names(self) -> list[str]: ...
+
+def is_opentype_cff_font(filename: str) -> bool: ...
+def get_font(
+    font_filepaths: Iterable[str | Path | bytes] | str | Path | bytes,
+    hinting_factor: int | None = ...,
+) -> ft2font.FT2Font: ...
+
+fontManager: FontManager
+
+def findfont(
+    prop: str | FontProperties,
+    fontext: Literal["ttf", "afm"] = ...,
+    directory: str | None = ...,
+    fallback_to_default: bool = ...,
+    rebuild_if_missing: bool = ...,
+) -> str: ...
+def get_font_names() -> list[str]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/ft2font.pyi b/lib/python3.12/site-packages/matplotlib/ft2font.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..37281afeaafa751790af911a422aedebece7133e
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/ft2font.pyi
@@ -0,0 +1,312 @@
+from enum import Enum, Flag
+import sys
+from typing import BinaryIO, Literal, TypedDict, final, overload, cast
+from typing_extensions import Buffer  # < Py 3.12
+
+import numpy as np
+from numpy.typing import NDArray
+
+__freetype_build_type__: str
+__freetype_version__: str
+
+class FaceFlags(Flag):
+    SCALABLE = cast(int, ...)
+    FIXED_SIZES = cast(int, ...)
+    FIXED_WIDTH = cast(int, ...)
+    SFNT = cast(int, ...)
+    HORIZONTAL = cast(int, ...)
+    VERTICAL = cast(int, ...)
+    KERNING = cast(int, ...)
+    FAST_GLYPHS = cast(int, ...)
+    MULTIPLE_MASTERS = cast(int, ...)
+    GLYPH_NAMES = cast(int, ...)
+    EXTERNAL_STREAM = cast(int, ...)
+    HINTER = cast(int, ...)
+    CID_KEYED = cast(int, ...)
+    TRICKY = cast(int, ...)
+    COLOR = cast(int, ...)
+    # VARIATION = cast(int, ...)  # FT 2.9
+    # SVG = cast(int, ...)  # FT 2.12
+    # SBIX = cast(int, ...)  # FT 2.12
+    # SBIX_OVERLAY = cast(int, ...)  # FT 2.12
+
+class Kerning(Enum):
+    DEFAULT = cast(int, ...)
+    UNFITTED = cast(int, ...)
+    UNSCALED = cast(int, ...)
+
+class LoadFlags(Flag):
+    DEFAULT = cast(int, ...)
+    NO_SCALE = cast(int, ...)
+    NO_HINTING = cast(int, ...)
+    RENDER = cast(int, ...)
+    NO_BITMAP = cast(int, ...)
+    VERTICAL_LAYOUT = cast(int, ...)
+    FORCE_AUTOHINT = cast(int, ...)
+    CROP_BITMAP = cast(int, ...)
+    PEDANTIC = cast(int, ...)
+    IGNORE_GLOBAL_ADVANCE_WIDTH = cast(int, ...)
+    NO_RECURSE = cast(int, ...)
+    IGNORE_TRANSFORM = cast(int, ...)
+    MONOCHROME = cast(int, ...)
+    LINEAR_DESIGN = cast(int, ...)
+    NO_AUTOHINT = cast(int, ...)
+    COLOR = cast(int, ...)
+    COMPUTE_METRICS = cast(int, ...)  # FT 2.6.1
+    # BITMAP_METRICS_ONLY = cast(int, ...)  # FT 2.7.1
+    # NO_SVG = cast(int, ...)  # FT 2.13.1
+    # The following should be unique, but the above can be OR'd together.
+    TARGET_NORMAL = cast(int, ...)
+    TARGET_LIGHT = cast(int, ...)
+    TARGET_MONO = cast(int, ...)
+    TARGET_LCD = cast(int, ...)
+    TARGET_LCD_V = cast(int, ...)
+
+class StyleFlags(Flag):
+    NORMAL = cast(int, ...)
+    ITALIC = cast(int, ...)
+    BOLD = cast(int, ...)
+
+class _SfntHeadDict(TypedDict):
+    version: tuple[int, int]
+    fontRevision: tuple[int, int]
+    checkSumAdjustment: int
+    magicNumber: int
+    flags: int
+    unitsPerEm: int
+    created: tuple[int, int]
+    modified: tuple[int, int]
+    xMin: int
+    yMin: int
+    xMax: int
+    yMax: int
+    macStyle: int
+    lowestRecPPEM: int
+    fontDirectionHint: int
+    indexToLocFormat: int
+    glyphDataFormat: int
+
+class _SfntMaxpDict(TypedDict):
+    version: tuple[int, int]
+    numGlyphs: int
+    maxPoints: int
+    maxContours: int
+    maxComponentPoints: int
+    maxComponentContours: int
+    maxZones: int
+    maxTwilightPoints: int
+    maxStorage: int
+    maxFunctionDefs: int
+    maxInstructionDefs: int
+    maxStackElements: int
+    maxSizeOfInstructions: int
+    maxComponentElements: int
+    maxComponentDepth: int
+
+class _SfntOs2Dict(TypedDict):
+    version: int
+    xAvgCharWidth: int
+    usWeightClass: int
+    usWidthClass: int
+    fsType: int
+    ySubscriptXSize: int
+    ySubscriptYSize: int
+    ySubscriptXOffset: int
+    ySubscriptYOffset: int
+    ySuperscriptXSize: int
+    ySuperscriptYSize: int
+    ySuperscriptXOffset: int
+    ySuperscriptYOffset: int
+    yStrikeoutSize: int
+    yStrikeoutPosition: int
+    sFamilyClass: int
+    panose: bytes
+    ulCharRange: tuple[int, int, int, int]
+    achVendID: bytes
+    fsSelection: int
+    fsFirstCharIndex: int
+    fsLastCharIndex: int
+
+class _SfntHheaDict(TypedDict):
+    version: tuple[int, int]
+    ascent: int
+    descent: int
+    lineGap: int
+    advanceWidthMax: int
+    minLeftBearing: int
+    minRightBearing: int
+    xMaxExtent: int
+    caretSlopeRise: int
+    caretSlopeRun: int
+    caretOffset: int
+    metricDataFormat: int
+    numOfLongHorMetrics: int
+
+class _SfntVheaDict(TypedDict):
+    version: tuple[int, int]
+    vertTypoAscender: int
+    vertTypoDescender: int
+    vertTypoLineGap: int
+    advanceHeightMax: int
+    minTopSideBearing: int
+    minBottomSizeBearing: int
+    yMaxExtent: int
+    caretSlopeRise: int
+    caretSlopeRun: int
+    caretOffset: int
+    metricDataFormat: int
+    numOfLongVerMetrics: int
+
+class _SfntPostDict(TypedDict):
+    format: tuple[int, int]
+    italicAngle: tuple[int, int]
+    underlinePosition: int
+    underlineThickness: int
+    isFixedPitch: int
+    minMemType42: int
+    maxMemType42: int
+    minMemType1: int
+    maxMemType1: int
+
+class _SfntPcltDict(TypedDict):
+    version: tuple[int, int]
+    fontNumber: int
+    pitch: int
+    xHeight: int
+    style: int
+    typeFamily: int
+    capHeight: int
+    symbolSet: int
+    typeFace: bytes
+    characterComplement: bytes
+    strokeWeight: int
+    widthType: int
+    serifStyle: int
+
+@final
+class FT2Font(Buffer):
+    def __init__(
+        self,
+        filename: str | BinaryIO,
+        hinting_factor: int = ...,
+        *,
+        _fallback_list: list[FT2Font] | None = ...,
+        _kerning_factor: int = ...
+    ) -> None: ...
+    if sys.version_info[:2] >= (3, 12):
+        def __buffer__(self, flags: int) -> memoryview: ...
+    def _get_fontmap(self, string: str) -> dict[str, FT2Font]: ...
+    def clear(self) -> None: ...
+    def draw_glyph_to_bitmap(
+        self, image: FT2Image, x: int, y: int, glyph: Glyph, antialiased: bool = ...
+    ) -> None: ...
+    def draw_glyphs_to_bitmap(self, antialiased: bool = ...) -> None: ...
+    def get_bitmap_offset(self) -> tuple[int, int]: ...
+    def get_char_index(self, codepoint: int) -> int: ...
+    def get_charmap(self) -> dict[int, int]: ...
+    def get_descent(self) -> int: ...
+    def get_glyph_name(self, index: int) -> str: ...
+    def get_image(self) -> NDArray[np.uint8]: ...
+    def get_kerning(self, left: int, right: int, mode: Kerning) -> int: ...
+    def get_name_index(self, name: str) -> int: ...
+    def get_num_glyphs(self) -> int: ...
+    def get_path(self) -> tuple[NDArray[np.float64], NDArray[np.int8]]: ...
+    def get_ps_font_info(
+        self,
+    ) -> tuple[str, str, str, str, str, int, int, int, int]: ...
+    def get_sfnt(self) -> dict[tuple[int, int, int, int], bytes]: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["head"]) -> _SfntHeadDict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["maxp"]) -> _SfntMaxpDict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["OS/2"]) -> _SfntOs2Dict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["hhea"]) -> _SfntHheaDict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["vhea"]) -> _SfntVheaDict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["post"]) -> _SfntPostDict | None: ...
+    @overload
+    def get_sfnt_table(self, name: Literal["pclt"]) -> _SfntPcltDict | None: ...
+    def get_width_height(self) -> tuple[int, int]: ...
+    def load_char(self, charcode: int, flags: LoadFlags = ...) -> Glyph: ...
+    def load_glyph(self, glyphindex: int, flags: LoadFlags = ...) -> Glyph: ...
+    def select_charmap(self, i: int) -> None: ...
+    def set_charmap(self, i: int) -> None: ...
+    def set_size(self, ptsize: float, dpi: float) -> None: ...
+    def set_text(
+        self, string: str, angle: float = ..., flags: LoadFlags = ...
+    ) -> NDArray[np.float64]: ...
+    @property
+    def ascender(self) -> int: ...
+    @property
+    def bbox(self) -> tuple[int, int, int, int]: ...
+    @property
+    def descender(self) -> int: ...
+    @property
+    def face_flags(self) -> FaceFlags: ...
+    @property
+    def family_name(self) -> str: ...
+    @property
+    def fname(self) -> str: ...
+    @property
+    def height(self) -> int: ...
+    @property
+    def max_advance_height(self) -> int: ...
+    @property
+    def max_advance_width(self) -> int: ...
+    @property
+    def num_charmaps(self) -> int: ...
+    @property
+    def num_faces(self) -> int: ...
+    @property
+    def num_fixed_sizes(self) -> int: ...
+    @property
+    def num_glyphs(self) -> int: ...
+    @property
+    def num_named_instances(self) -> int: ...
+    @property
+    def postscript_name(self) -> str: ...
+    @property
+    def scalable(self) -> bool: ...
+    @property
+    def style_flags(self) -> StyleFlags: ...
+    @property
+    def style_name(self) -> str: ...
+    @property
+    def underline_position(self) -> int: ...
+    @property
+    def underline_thickness(self) -> int: ...
+    @property
+    def units_per_EM(self) -> int: ...
+
+@final
+class FT2Image(Buffer):
+    def __init__(self, width: int, height: int) -> None: ...
+    def draw_rect_filled(self, x0: int, y0: int, x1: int, y1: int) -> None: ...
+    if sys.version_info[:2] >= (3, 12):
+        def __buffer__(self, flags: int) -> memoryview: ...
+
+@final
+class Glyph:
+    @property
+    def width(self) -> int: ...
+    @property
+    def height(self) -> int: ...
+    @property
+    def horiBearingX(self) -> int: ...
+    @property
+    def horiBearingY(self) -> int: ...
+    @property
+    def horiAdvance(self) -> int: ...
+    @property
+    def linearHoriAdvance(self) -> int: ...
+    @property
+    def vertBearingX(self) -> int: ...
+    @property
+    def vertBearingY(self) -> int: ...
+    @property
+    def vertAdvance(self) -> int: ...
+    @property
+    def bbox(self) -> tuple[int, int, int, int]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/gridspec.py b/lib/python3.12/site-packages/matplotlib/gridspec.py
new file mode 100644
index 0000000000000000000000000000000000000000..06f0b2f7f781d291ca6159fd7ad8333d75dc6abb
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/gridspec.py
@@ -0,0 +1,788 @@
+r"""
+:mod:`~matplotlib.gridspec` contains classes that help to layout multiple
+`~.axes.Axes` in a grid-like pattern within a figure.
+
+The `GridSpec` specifies the overall grid structure. Individual cells within
+the grid are referenced by `SubplotSpec`\s.
+
+Often, users need not access this module directly, and can use higher-level
+methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and
+`~.Figure.subfigures`. See the tutorial :ref:`arranging_axes` for a guide.
+"""
+
+import copy
+import logging
+from numbers import Integral
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib import _api, _pylab_helpers, _tight_layout
+from matplotlib.transforms import Bbox
+
+_log = logging.getLogger(__name__)
+
+
+class GridSpecBase:
+    """
+    A base class of GridSpec that specifies the geometry of the grid
+    that a subplot will be placed.
+    """
+
+    def __init__(self, nrows, ncols, height_ratios=None, width_ratios=None):
+        """
+        Parameters
+        ----------
+        nrows, ncols : int
+            The number of rows and columns of the grid.
+        width_ratios : array-like of length *ncols*, optional
+            Defines the relative widths of the columns. Each column gets a
+            relative width of ``width_ratios[i] / sum(width_ratios)``.
+            If not given, all columns will have the same width.
+        height_ratios : array-like of length *nrows*, optional
+            Defines the relative heights of the rows. Each row gets a
+            relative height of ``height_ratios[i] / sum(height_ratios)``.
+            If not given, all rows will have the same height.
+        """
+        if not isinstance(nrows, Integral) or nrows <= 0:
+            raise ValueError(
+                f"Number of rows must be a positive integer, not {nrows!r}")
+        if not isinstance(ncols, Integral) or ncols <= 0:
+            raise ValueError(
+                f"Number of columns must be a positive integer, not {ncols!r}")
+        self._nrows, self._ncols = nrows, ncols
+        self.set_height_ratios(height_ratios)
+        self.set_width_ratios(width_ratios)
+
+    def __repr__(self):
+        height_arg = (f', height_ratios={self._row_height_ratios!r}'
+                      if len(set(self._row_height_ratios)) != 1 else '')
+        width_arg = (f', width_ratios={self._col_width_ratios!r}'
+                     if len(set(self._col_width_ratios)) != 1 else '')
+        return '{clsname}({nrows}, {ncols}{optionals})'.format(
+            clsname=self.__class__.__name__,
+            nrows=self._nrows,
+            ncols=self._ncols,
+            optionals=height_arg + width_arg,
+            )
+
+    nrows = property(lambda self: self._nrows,
+                     doc="The number of rows in the grid.")
+    ncols = property(lambda self: self._ncols,
+                     doc="The number of columns in the grid.")
+
+    def get_geometry(self):
+        """
+        Return a tuple containing the number of rows and columns in the grid.
+        """
+        return self._nrows, self._ncols
+
+    def get_subplot_params(self, figure=None):
+        # Must be implemented in subclasses
+        pass
+
+    def new_subplotspec(self, loc, rowspan=1, colspan=1):
+        """
+        Create and return a `.SubplotSpec` instance.
+
+        Parameters
+        ----------
+        loc : (int, int)
+            The position of the subplot in the grid as
+            ``(row_index, column_index)``.
+        rowspan, colspan : int, default: 1
+            The number of rows and columns the subplot should span in the grid.
+        """
+        loc1, loc2 = loc
+        subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
+        return subplotspec
+
+    def set_width_ratios(self, width_ratios):
+        """
+        Set the relative widths of the columns.
+
+        *width_ratios* must be of length *ncols*. Each column gets a relative
+        width of ``width_ratios[i] / sum(width_ratios)``.
+        """
+        if width_ratios is None:
+            width_ratios = [1] * self._ncols
+        elif len(width_ratios) != self._ncols:
+            raise ValueError('Expected the given number of width ratios to '
+                             'match the number of columns of the grid')
+        self._col_width_ratios = width_ratios
+
+    def get_width_ratios(self):
+        """
+        Return the width ratios.
+
+        This is *None* if no width ratios have been set explicitly.
+        """
+        return self._col_width_ratios
+
+    def set_height_ratios(self, height_ratios):
+        """
+        Set the relative heights of the rows.
+
+        *height_ratios* must be of length *nrows*. Each row gets a relative
+        height of ``height_ratios[i] / sum(height_ratios)``.
+        """
+        if height_ratios is None:
+            height_ratios = [1] * self._nrows
+        elif len(height_ratios) != self._nrows:
+            raise ValueError('Expected the given number of height ratios to '
+                             'match the number of rows of the grid')
+        self._row_height_ratios = height_ratios
+
+    def get_height_ratios(self):
+        """
+        Return the height ratios.
+
+        This is *None* if no height ratios have been set explicitly.
+        """
+        return self._row_height_ratios
+
+    def get_grid_positions(self, fig):
+        """
+        Return the positions of the grid cells in figure coordinates.
+
+        Parameters
+        ----------
+        fig : `~matplotlib.figure.Figure`
+            The figure the grid should be applied to. The subplot parameters
+            (margins and spacing between subplots) are taken from *fig*.
+
+        Returns
+        -------
+        bottoms, tops, lefts, rights : array
+            The bottom, top, left, right positions of the grid cells in
+            figure coordinates.
+        """
+        nrows, ncols = self.get_geometry()
+        subplot_params = self.get_subplot_params(fig)
+        left = subplot_params.left
+        right = subplot_params.right
+        bottom = subplot_params.bottom
+        top = subplot_params.top
+        wspace = subplot_params.wspace
+        hspace = subplot_params.hspace
+        tot_width = right - left
+        tot_height = top - bottom
+
+        # calculate accumulated heights of columns
+        cell_h = tot_height / (nrows + hspace*(nrows-1))
+        sep_h = hspace * cell_h
+        norm = cell_h * nrows / sum(self._row_height_ratios)
+        cell_heights = [r * norm for r in self._row_height_ratios]
+        sep_heights = [0] + ([sep_h] * (nrows-1))
+        cell_hs = np.cumsum(np.column_stack([sep_heights, cell_heights]).flat)
+
+        # calculate accumulated widths of rows
+        cell_w = tot_width / (ncols + wspace*(ncols-1))
+        sep_w = wspace * cell_w
+        norm = cell_w * ncols / sum(self._col_width_ratios)
+        cell_widths = [r * norm for r in self._col_width_ratios]
+        sep_widths = [0] + ([sep_w] * (ncols-1))
+        cell_ws = np.cumsum(np.column_stack([sep_widths, cell_widths]).flat)
+
+        fig_tops, fig_bottoms = (top - cell_hs).reshape((-1, 2)).T
+        fig_lefts, fig_rights = (left + cell_ws).reshape((-1, 2)).T
+        return fig_bottoms, fig_tops, fig_lefts, fig_rights
+
+    @staticmethod
+    def _check_gridspec_exists(figure, nrows, ncols):
+        """
+        Check if the figure already has a gridspec with these dimensions,
+        or create a new one
+        """
+        for ax in figure.get_axes():
+            gs = ax.get_gridspec()
+            if gs is not None:
+                if hasattr(gs, 'get_topmost_subplotspec'):
+                    # This is needed for colorbar gridspec layouts.
+                    # This is probably OK because this whole logic tree
+                    # is for when the user is doing simple things with the
+                    # add_subplot command.  For complicated layouts
+                    # like subgridspecs the proper gridspec is passed in...
+                    gs = gs.get_topmost_subplotspec().get_gridspec()
+                if gs.get_geometry() == (nrows, ncols):
+                    return gs
+        # else gridspec not found:
+        return GridSpec(nrows, ncols, figure=figure)
+
+    def __getitem__(self, key):
+        """Create and return a `.SubplotSpec` instance."""
+        nrows, ncols = self.get_geometry()
+
+        def _normalize(key, size, axis):  # Includes last index.
+            orig_key = key
+            if isinstance(key, slice):
+                start, stop, _ = key.indices(size)
+                if stop > start:
+                    return start, stop - 1
+                raise IndexError("GridSpec slice would result in no space "
+                                 "allocated for subplot")
+            else:
+                if key < 0:
+                    key = key + size
+                if 0 <= key < size:
+                    return key, key
+                elif axis is not None:
+                    raise IndexError(f"index {orig_key} is out of bounds for "
+                                     f"axis {axis} with size {size}")
+                else:  # flat index
+                    raise IndexError(f"index {orig_key} is out of bounds for "
+                                     f"GridSpec with size {size}")
+
+        if isinstance(key, tuple):
+            try:
+                k1, k2 = key
+            except ValueError as err:
+                raise ValueError("Unrecognized subplot spec") from err
+            num1, num2 = np.ravel_multi_index(
+                [_normalize(k1, nrows, 0), _normalize(k2, ncols, 1)],
+                (nrows, ncols))
+        else:  # Single key
+            num1, num2 = _normalize(key, nrows * ncols, None)
+
+        return SubplotSpec(self, num1, num2)
+
+    def subplots(self, *, sharex=False, sharey=False, squeeze=True,
+                 subplot_kw=None):
+        """
+        Add all subplots specified by this `GridSpec` to its parent figure.
+
+        See `.Figure.subplots` for detailed documentation.
+        """
+
+        figure = self.figure
+
+        if figure is None:
+            raise ValueError("GridSpec.subplots() only works for GridSpecs "
+                             "created with a parent figure")
+
+        if not isinstance(sharex, str):
+            sharex = "all" if sharex else "none"
+        if not isinstance(sharey, str):
+            sharey = "all" if sharey else "none"
+
+        _api.check_in_list(["all", "row", "col", "none", False, True],
+                           sharex=sharex, sharey=sharey)
+        if subplot_kw is None:
+            subplot_kw = {}
+        # don't mutate kwargs passed by user...
+        subplot_kw = subplot_kw.copy()
+
+        # Create array to hold all Axes.
+        axarr = np.empty((self._nrows, self._ncols), dtype=object)
+        for row in range(self._nrows):
+            for col in range(self._ncols):
+                shared_with = {"none": None, "all": axarr[0, 0],
+                               "row": axarr[row, 0], "col": axarr[0, col]}
+                subplot_kw["sharex"] = shared_with[sharex]
+                subplot_kw["sharey"] = shared_with[sharey]
+                axarr[row, col] = figure.add_subplot(
+                    self[row, col], **subplot_kw)
+
+        # turn off redundant tick labeling
+        if sharex in ["col", "all"]:
+            for ax in axarr.flat:
+                ax._label_outer_xaxis(skip_non_rectangular_axes=True)
+        if sharey in ["row", "all"]:
+            for ax in axarr.flat:
+                ax._label_outer_yaxis(skip_non_rectangular_axes=True)
+
+        if squeeze:
+            # Discarding unneeded dimensions that equal 1.  If we only have one
+            # subplot, just return it instead of a 1-element array.
+            return axarr.item() if axarr.size == 1 else axarr.squeeze()
+        else:
+            # Returned axis array will be always 2-d, even if nrows=ncols=1.
+            return axarr
+
+
+class GridSpec(GridSpecBase):
+    """
+    A grid layout to place subplots within a figure.
+
+    The location of the grid cells is determined in a similar way to
+    `.SubplotParams` using *left*, *right*, *top*, *bottom*, *wspace*
+    and *hspace*.
+
+    Indexing a GridSpec instance returns a `.SubplotSpec`.
+    """
+    def __init__(self, nrows, ncols, figure=None,
+                 left=None, bottom=None, right=None, top=None,
+                 wspace=None, hspace=None,
+                 width_ratios=None, height_ratios=None):
+        """
+        Parameters
+        ----------
+        nrows, ncols : int
+            The number of rows and columns of the grid.
+
+        figure : `.Figure`, optional
+            Only used for constrained layout to create a proper layoutgrid.
+
+        left, right, top, bottom : float, optional
+            Extent of the subplots as a fraction of figure width or height.
+            Left cannot be larger than right, and bottom cannot be larger than
+            top. If not given, the values will be inferred from a figure or
+            rcParams at draw time. See also `GridSpec.get_subplot_params`.
+
+        wspace : float, optional
+            The amount of width reserved for space between subplots,
+            expressed as a fraction of the average axis width.
+            If not given, the values will be inferred from a figure or
+            rcParams when necessary. See also `GridSpec.get_subplot_params`.
+
+        hspace : float, optional
+            The amount of height reserved for space between subplots,
+            expressed as a fraction of the average axis height.
+            If not given, the values will be inferred from a figure or
+            rcParams when necessary. See also `GridSpec.get_subplot_params`.
+
+        width_ratios : array-like of length *ncols*, optional
+            Defines the relative widths of the columns. Each column gets a
+            relative width of ``width_ratios[i] / sum(width_ratios)``.
+            If not given, all columns will have the same width.
+
+        height_ratios : array-like of length *nrows*, optional
+            Defines the relative heights of the rows. Each row gets a
+            relative height of ``height_ratios[i] / sum(height_ratios)``.
+            If not given, all rows will have the same height.
+
+        """
+        self.left = left
+        self.bottom = bottom
+        self.right = right
+        self.top = top
+        self.wspace = wspace
+        self.hspace = hspace
+        self.figure = figure
+
+        super().__init__(nrows, ncols,
+                         width_ratios=width_ratios,
+                         height_ratios=height_ratios)
+
+    _AllowedKeys = ["left", "bottom", "right", "top", "wspace", "hspace"]
+
+    def update(self, **kwargs):
+        """
+        Update the subplot parameters of the grid.
+
+        Parameters that are not explicitly given are not changed. Setting a
+        parameter to *None* resets it to :rc:`figure.subplot.*`.
+
+        Parameters
+        ----------
+        left, right, top, bottom : float or None, optional
+            Extent of the subplots as a fraction of figure width or height.
+        wspace, hspace : float, optional
+            Spacing between the subplots as a fraction of the average subplot
+            width / height.
+        """
+        for k, v in kwargs.items():
+            if k in self._AllowedKeys:
+                setattr(self, k, v)
+            else:
+                raise AttributeError(f"{k} is an unknown keyword")
+        for figmanager in _pylab_helpers.Gcf.figs.values():
+            for ax in figmanager.canvas.figure.axes:
+                if ax.get_subplotspec() is not None:
+                    ss = ax.get_subplotspec().get_topmost_subplotspec()
+                    if ss.get_gridspec() == self:
+                        fig = ax.get_figure(root=False)
+                        ax._set_position(ax.get_subplotspec().get_position(fig))
+
+    def get_subplot_params(self, figure=None):
+        """
+        Return the `.SubplotParams` for the GridSpec.
+
+        In order of precedence the values are taken from
+
+        - non-*None* attributes of the GridSpec
+        - the provided *figure*
+        - :rc:`figure.subplot.*`
+
+        Note that the ``figure`` attribute of the GridSpec is always ignored.
+        """
+        if figure is None:
+            kw = {k: mpl.rcParams["figure.subplot."+k]
+                  for k in self._AllowedKeys}
+            subplotpars = SubplotParams(**kw)
+        else:
+            subplotpars = copy.copy(figure.subplotpars)
+
+        subplotpars.update(**{k: getattr(self, k) for k in self._AllowedKeys})
+
+        return subplotpars
+
+    def locally_modified_subplot_params(self):
+        """
+        Return a list of the names of the subplot parameters explicitly set
+        in the GridSpec.
+
+        This is a subset of the attributes of `.SubplotParams`.
+        """
+        return [k for k in self._AllowedKeys if getattr(self, k)]
+
+    def tight_layout(self, figure, renderer=None,
+                     pad=1.08, h_pad=None, w_pad=None, rect=None):
+        """
+        Adjust subplot parameters to give specified padding.
+
+        Parameters
+        ----------
+        figure : `.Figure`
+            The figure.
+        renderer :  `.RendererBase` subclass, optional
+            The renderer to be used.
+        pad : float
+            Padding between the figure edge and the edges of subplots, as a
+            fraction of the font-size.
+        h_pad, w_pad : float, optional
+            Padding (height/width) between edges of adjacent subplots.
+            Defaults to *pad*.
+        rect : tuple (left, bottom, right, top), default: None
+            (left, bottom, right, top) rectangle in normalized figure
+            coordinates that the whole subplots area (including labels) will
+            fit into. Default (None) is the whole figure.
+        """
+        if renderer is None:
+            renderer = figure._get_renderer()
+        kwargs = _tight_layout.get_tight_layout_figure(
+            figure, figure.axes,
+            _tight_layout.get_subplotspec_list(figure.axes, grid_spec=self),
+            renderer, pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)
+        if kwargs:
+            self.update(**kwargs)
+
+
+class GridSpecFromSubplotSpec(GridSpecBase):
+    """
+    GridSpec whose subplot layout parameters are inherited from the
+    location specified by a given SubplotSpec.
+    """
+    def __init__(self, nrows, ncols,
+                 subplot_spec,
+                 wspace=None, hspace=None,
+                 height_ratios=None, width_ratios=None):
+        """
+        Parameters
+        ----------
+        nrows, ncols : int
+            Number of rows and number of columns of the grid.
+        subplot_spec : SubplotSpec
+            Spec from which the layout parameters are inherited.
+        wspace, hspace : float, optional
+            See `GridSpec` for more details. If not specified default values
+            (from the figure or rcParams) are used.
+        height_ratios : array-like of length *nrows*, optional
+            See `GridSpecBase` for details.
+        width_ratios : array-like of length *ncols*, optional
+            See `GridSpecBase` for details.
+        """
+        self._wspace = wspace
+        self._hspace = hspace
+        if isinstance(subplot_spec, SubplotSpec):
+            self._subplot_spec = subplot_spec
+        else:
+            raise TypeError(
+                            "subplot_spec must be type SubplotSpec, "
+                            "usually from GridSpec, or axes.get_subplotspec.")
+        self.figure = self._subplot_spec.get_gridspec().figure
+        super().__init__(nrows, ncols,
+                         width_ratios=width_ratios,
+                         height_ratios=height_ratios)
+
+    def get_subplot_params(self, figure=None):
+        """Return a dictionary of subplot layout parameters."""
+        hspace = (self._hspace if self._hspace is not None
+                  else figure.subplotpars.hspace if figure is not None
+                  else mpl.rcParams["figure.subplot.hspace"])
+        wspace = (self._wspace if self._wspace is not None
+                  else figure.subplotpars.wspace if figure is not None
+                  else mpl.rcParams["figure.subplot.wspace"])
+
+        figbox = self._subplot_spec.get_position(figure)
+        left, bottom, right, top = figbox.extents
+
+        return SubplotParams(left=left, right=right,
+                             bottom=bottom, top=top,
+                             wspace=wspace, hspace=hspace)
+
+    def get_topmost_subplotspec(self):
+        """
+        Return the topmost `.SubplotSpec` instance associated with the subplot.
+        """
+        return self._subplot_spec.get_topmost_subplotspec()
+
+
+class SubplotSpec:
+    """
+    The location of a subplot in a `GridSpec`.
+
+    .. note::
+
+        Likely, you will never instantiate a `SubplotSpec` yourself. Instead,
+        you will typically obtain one from a `GridSpec` using item-access.
+
+    Parameters
+    ----------
+    gridspec : `~matplotlib.gridspec.GridSpec`
+        The GridSpec, which the subplot is referencing.
+    num1, num2 : int
+        The subplot will occupy the *num1*-th cell of the given
+        *gridspec*.  If *num2* is provided, the subplot will span between
+        *num1*-th cell and *num2*-th cell **inclusive**.
+
+        The index starts from 0.
+    """
+    def __init__(self, gridspec, num1, num2=None):
+        self._gridspec = gridspec
+        self.num1 = num1
+        self.num2 = num2
+
+    def __repr__(self):
+        return (f"{self.get_gridspec()}["
+                f"{self.rowspan.start}:{self.rowspan.stop}, "
+                f"{self.colspan.start}:{self.colspan.stop}]")
+
+    @staticmethod
+    def _from_subplot_args(figure, args):
+        """
+        Construct a `.SubplotSpec` from a parent `.Figure` and either
+
+        - a `.SubplotSpec` -- returned as is;
+        - one or three numbers -- a MATLAB-style subplot specifier.
+        """
+        if len(args) == 1:
+            arg, = args
+            if isinstance(arg, SubplotSpec):
+                return arg
+            elif not isinstance(arg, Integral):
+                raise ValueError(
+                    f"Single argument to subplot must be a three-digit "
+                    f"integer, not {arg!r}")
+            try:
+                rows, cols, num = map(int, str(arg))
+            except ValueError:
+                raise ValueError(
+                    f"Single argument to subplot must be a three-digit "
+                    f"integer, not {arg!r}") from None
+        elif len(args) == 3:
+            rows, cols, num = args
+        else:
+            raise _api.nargs_error("subplot", takes="1 or 3", given=len(args))
+
+        gs = GridSpec._check_gridspec_exists(figure, rows, cols)
+        if gs is None:
+            gs = GridSpec(rows, cols, figure=figure)
+        if isinstance(num, tuple) and len(num) == 2:
+            if not all(isinstance(n, Integral) for n in num):
+                raise ValueError(
+                    f"Subplot specifier tuple must contain integers, not {num}"
+                )
+            i, j = num
+        else:
+            if not isinstance(num, Integral) or num < 1 or num > rows*cols:
+                raise ValueError(
+                    f"num must be an integer with 1 <= num <= {rows*cols}, "
+                    f"not {num!r}"
+                )
+            i = j = num
+        return gs[i-1:j]
+
+    # num2 is a property only to handle the case where it is None and someone
+    # mutates num1.
+
+    @property
+    def num2(self):
+        return self.num1 if self._num2 is None else self._num2
+
+    @num2.setter
+    def num2(self, value):
+        self._num2 = value
+
+    def get_gridspec(self):
+        return self._gridspec
+
+    def get_geometry(self):
+        """
+        Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``.
+
+        The indices *start* and *stop* define the range of the subplot within
+        the `GridSpec`. *stop* is inclusive (i.e. for a single cell
+        ``start == stop``).
+        """
+        rows, cols = self.get_gridspec().get_geometry()
+        return rows, cols, self.num1, self.num2
+
+    @property
+    def rowspan(self):
+        """The rows spanned by this subplot, as a `range` object."""
+        ncols = self.get_gridspec().ncols
+        return range(self.num1 // ncols, self.num2 // ncols + 1)
+
+    @property
+    def colspan(self):
+        """The columns spanned by this subplot, as a `range` object."""
+        ncols = self.get_gridspec().ncols
+        # We explicitly support num2 referring to a column on num1's *left*, so
+        # we must sort the column indices here so that the range makes sense.
+        c1, c2 = sorted([self.num1 % ncols, self.num2 % ncols])
+        return range(c1, c2 + 1)
+
+    def is_first_row(self):
+        return self.rowspan.start == 0
+
+    def is_last_row(self):
+        return self.rowspan.stop == self.get_gridspec().nrows
+
+    def is_first_col(self):
+        return self.colspan.start == 0
+
+    def is_last_col(self):
+        return self.colspan.stop == self.get_gridspec().ncols
+
+    def get_position(self, figure):
+        """
+        Update the subplot position from ``figure.subplotpars``.
+        """
+        gridspec = self.get_gridspec()
+        nrows, ncols = gridspec.get_geometry()
+        rows, cols = np.unravel_index([self.num1, self.num2], (nrows, ncols))
+        fig_bottoms, fig_tops, fig_lefts, fig_rights = \
+            gridspec.get_grid_positions(figure)
+
+        fig_bottom = fig_bottoms[rows].min()
+        fig_top = fig_tops[rows].max()
+        fig_left = fig_lefts[cols].min()
+        fig_right = fig_rights[cols].max()
+        return Bbox.from_extents(fig_left, fig_bottom, fig_right, fig_top)
+
+    def get_topmost_subplotspec(self):
+        """
+        Return the topmost `SubplotSpec` instance associated with the subplot.
+        """
+        gridspec = self.get_gridspec()
+        if hasattr(gridspec, "get_topmost_subplotspec"):
+            return gridspec.get_topmost_subplotspec()
+        else:
+            return self
+
+    def __eq__(self, other):
+        """
+        Two SubplotSpecs are considered equal if they refer to the same
+        position(s) in the same `GridSpec`.
+        """
+        # other may not even have the attributes we are checking.
+        return ((self._gridspec, self.num1, self.num2)
+                == (getattr(other, "_gridspec", object()),
+                    getattr(other, "num1", object()),
+                    getattr(other, "num2", object())))
+
+    def __hash__(self):
+        return hash((self._gridspec, self.num1, self.num2))
+
+    def subgridspec(self, nrows, ncols, **kwargs):
+        """
+        Create a GridSpec within this subplot.
+
+        The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as
+        a parent.
+
+        Parameters
+        ----------
+        nrows : int
+            Number of rows in grid.
+
+        ncols : int
+            Number of columns in grid.
+
+        Returns
+        -------
+        `.GridSpecFromSubplotSpec`
+
+        Other Parameters
+        ----------------
+        **kwargs
+            All other parameters are passed to `.GridSpecFromSubplotSpec`.
+
+        See Also
+        --------
+        matplotlib.pyplot.subplots
+
+        Examples
+        --------
+        Adding three subplots in the space occupied by a single subplot::
+
+            fig = plt.figure()
+            gs0 = fig.add_gridspec(3, 1)
+            ax1 = fig.add_subplot(gs0[0])
+            ax2 = fig.add_subplot(gs0[1])
+            gssub = gs0[2].subgridspec(1, 3)
+            for i in range(3):
+                fig.add_subplot(gssub[0, i])
+        """
+        return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs)
+
+
+class SubplotParams:
+    """
+    Parameters defining the positioning of a subplots grid in a figure.
+    """
+
+    def __init__(self, left=None, bottom=None, right=None, top=None,
+                 wspace=None, hspace=None):
+        """
+        Defaults are given by :rc:`figure.subplot.[name]`.
+
+        Parameters
+        ----------
+        left : float
+            The position of the left edge of the subplots,
+            as a fraction of the figure width.
+        right : float
+            The position of the right edge of the subplots,
+            as a fraction of the figure width.
+        bottom : float
+            The position of the bottom edge of the subplots,
+            as a fraction of the figure height.
+        top : float
+            The position of the top edge of the subplots,
+            as a fraction of the figure height.
+        wspace : float
+            The width of the padding between subplots,
+            as a fraction of the average Axes width.
+        hspace : float
+            The height of the padding between subplots,
+            as a fraction of the average Axes height.
+        """
+        for key in ["left", "bottom", "right", "top", "wspace", "hspace"]:
+            setattr(self, key, mpl.rcParams[f"figure.subplot.{key}"])
+        self.update(left, bottom, right, top, wspace, hspace)
+
+    def update(self, left=None, bottom=None, right=None, top=None,
+               wspace=None, hspace=None):
+        """
+        Update the dimensions of the passed parameters. *None* means unchanged.
+        """
+        if ((left if left is not None else self.left)
+                >= (right if right is not None else self.right)):
+            raise ValueError('left cannot be >= right')
+        if ((bottom if bottom is not None else self.bottom)
+                >= (top if top is not None else self.top)):
+            raise ValueError('bottom cannot be >= top')
+        if left is not None:
+            self.left = left
+        if right is not None:
+            self.right = right
+        if bottom is not None:
+            self.bottom = bottom
+        if top is not None:
+            self.top = top
+        if wspace is not None:
+            self.wspace = wspace
+        if hspace is not None:
+            self.hspace = hspace
diff --git a/lib/python3.12/site-packages/matplotlib/image.pyi b/lib/python3.12/site-packages/matplotlib/image.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..1fcc1a710bfd68cad1d5d28f7d57912f83534404
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/image.pyi
@@ -0,0 +1,215 @@
+from collections.abc import Callable, Sequence
+import os
+import pathlib
+from typing import Any, BinaryIO, Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+import PIL.Image
+
+from matplotlib.axes import Axes
+from matplotlib import colorizer
+from matplotlib.backend_bases import RendererBase, MouseEvent
+from matplotlib.colorizer import Colorizer
+from matplotlib.colors import Colormap, Normalize
+from matplotlib.figure import Figure
+from matplotlib.transforms import Affine2D, BboxBase, Bbox, Transform
+
+#
+# These names are re-exported from matplotlib._image.
+#
+
+BESSEL: int
+BICUBIC: int
+BILINEAR: int
+BLACKMAN: int
+CATROM: int
+GAUSSIAN: int
+HAMMING: int
+HANNING: int
+HERMITE: int
+KAISER: int
+LANCZOS: int
+MITCHELL: int
+NEAREST: int
+QUADRIC: int
+SINC: int
+SPLINE16: int
+SPLINE36: int
+
+def resample(
+    input_array: NDArray[np.float32] | NDArray[np.float64] | NDArray[np.int8],
+    output_array: NDArray[np.float32] | NDArray[np.float64] | NDArray[np.int8],
+    transform: Transform,
+    interpolation: int = ...,
+    resample: bool = ...,
+    alpha: float = ...,
+    norm: bool = ...,
+    radius: float = ...,
+) -> None: ...
+
+#
+# END names re-exported from matplotlib._image.
+#
+
+interpolations_names: set[str]
+
+def composite_images(
+    images: Sequence[_ImageBase], renderer: RendererBase, magnification: float = ...
+) -> tuple[np.ndarray, float, float]: ...
+
+class _ImageBase(colorizer.ColorizingArtist):
+    zorder: float
+    origin: Literal["upper", "lower"]
+    axes: Axes
+    def __init__(
+        self,
+        ax: Axes,
+        cmap: str | Colormap | None = ...,
+        norm: str | Normalize | None = ...,
+        colorizer: Colorizer | None = ...,
+        interpolation: str | None = ...,
+        origin: Literal["upper", "lower"] | None = ...,
+        filternorm: bool = ...,
+        filterrad: float = ...,
+        resample: bool | None = ...,
+        *,
+        interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
+        **kwargs
+    ) -> None: ...
+    def get_size(self) -> tuple[int, int]: ...
+    def set_alpha(self, alpha: float | ArrayLike | None) -> None: ...
+    def changed(self) -> None: ...
+    def make_image(
+        self, renderer: RendererBase, magnification: float = ..., unsampled: bool = ...
+    ) -> tuple[np.ndarray, float, float, Affine2D]: ...
+    def draw(self, renderer: RendererBase) -> None: ...
+    def write_png(self, fname: str | pathlib.Path | BinaryIO) -> None: ...
+    def set_data(self, A: ArrayLike | None) -> None: ...
+    def set_array(self, A: ArrayLike | None) -> None: ...
+    def get_shape(self) -> tuple[int, int, int]: ...
+    def get_interpolation(self) -> str: ...
+    def set_interpolation(self, s: str | None) -> None: ...
+    def get_interpolation_stage(self) -> Literal["data", "rgba", "auto"]: ...
+    def set_interpolation_stage(self, s: Literal["data", "rgba", "auto"]) -> None: ...
+    def can_composite(self) -> bool: ...
+    def set_resample(self, v: bool | None) -> None: ...
+    def get_resample(self) -> bool: ...
+    def set_filternorm(self, filternorm: bool) -> None: ...
+    def get_filternorm(self) -> bool: ...
+    def set_filterrad(self, filterrad: float) -> None: ...
+    def get_filterrad(self) -> float: ...
+
+class AxesImage(_ImageBase):
+    def __init__(
+        self,
+        ax: Axes,
+        *,
+        cmap: str | Colormap | None = ...,
+        norm: str | Normalize | None = ...,
+        colorizer: Colorizer | None = ...,
+        interpolation: str | None = ...,
+        origin: Literal["upper", "lower"] | None = ...,
+        extent: tuple[float, float, float, float] | None = ...,
+        filternorm: bool = ...,
+        filterrad: float = ...,
+        resample: bool = ...,
+        interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
+        **kwargs
+    ) -> None: ...
+    def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...
+    def make_image(
+        self, renderer: RendererBase, magnification: float = ..., unsampled: bool = ...
+    ) -> tuple[np.ndarray, float, float, Affine2D]: ...
+    def set_extent(
+        self, extent: tuple[float, float, float, float], **kwargs
+    ) -> None: ...
+    def get_extent(self) -> tuple[float, float, float, float]: ...
+    def get_cursor_data(self, event: MouseEvent) -> None | float: ...
+
+class NonUniformImage(AxesImage):
+    mouseover: bool
+    def __init__(
+        self, ax: Axes, *, interpolation: Literal["nearest", "bilinear"] = ..., **kwargs
+    ) -> None: ...
+    def set_data(self, x: ArrayLike, y: ArrayLike, A: ArrayLike) -> None: ...  # type: ignore[override]
+    # more limited interpolation available here than base class
+    def set_interpolation(self, s: Literal["nearest", "bilinear"]) -> None: ...  # type: ignore[override]
+
+class PcolorImage(AxesImage):
+    def __init__(
+        self,
+        ax: Axes,
+        x: ArrayLike | None = ...,
+        y: ArrayLike | None = ...,
+        A: ArrayLike | None = ...,
+        *,
+        cmap: str | Colormap | None = ...,
+        norm: str | Normalize | None = ...,
+        colorizer: Colorizer | None = ...,
+        **kwargs
+    ) -> None: ...
+    def set_data(self, x: ArrayLike, y: ArrayLike, A: ArrayLike) -> None: ...  # type: ignore[override]
+
+class FigureImage(_ImageBase):
+    zorder: float
+    figure: Figure
+    ox: float
+    oy: float
+    magnification: float
+    def __init__(
+        self,
+        fig: Figure,
+        *,
+        cmap: str | Colormap | None = ...,
+        norm: str | Normalize | None = ...,
+        colorizer: Colorizer | None = ...,
+        offsetx: int = ...,
+        offsety: int = ...,
+        origin: Literal["upper", "lower"] | None = ...,
+        **kwargs
+    ) -> None: ...
+    def get_extent(self) -> tuple[float, float, float, float]: ...
+
+class BboxImage(_ImageBase):
+    bbox: BboxBase
+    def __init__(
+        self,
+        bbox: BboxBase | Callable[[RendererBase | None], Bbox],
+        *,
+        cmap: str | Colormap | None = ...,
+        norm: str | Normalize | None = ...,
+        colorizer: Colorizer | None = ...,
+        interpolation: str | None = ...,
+        origin: Literal["upper", "lower"] | None = ...,
+        filternorm: bool = ...,
+        filterrad: float = ...,
+        resample: bool = ...,
+        **kwargs
+    ) -> None: ...
+    def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...
+
+def imread(
+    fname: str | pathlib.Path | BinaryIO, format: str | None = ...
+) -> np.ndarray: ...
+def imsave(
+    fname: str | os.PathLike | BinaryIO,
+    arr: ArrayLike,
+    vmin: float | None = ...,
+    vmax: float | None = ...,
+    cmap: str | Colormap | None = ...,
+    format: str | None = ...,
+    origin: Literal["upper", "lower"] | None = ...,
+    dpi: float = ...,
+    *,
+    metadata: dict[str, str] | None = ...,
+    pil_kwargs: dict[str, Any] | None = ...
+) -> None: ...
+def pil_to_array(pilImage: PIL.Image.Image) -> np.ndarray: ...
+def thumbnail(
+    infile: str | BinaryIO,
+    thumbfile: str | BinaryIO,
+    scale: float = ...,
+    interpolation: str = ...,
+    preview: bool = ...,
+) -> Figure: ...
diff --git a/lib/python3.12/site-packages/matplotlib/layout_engine.pyi b/lib/python3.12/site-packages/matplotlib/layout_engine.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..5b8c812ff47f53913ff2812b58fcaf3652985a86
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/layout_engine.pyi
@@ -0,0 +1,62 @@
+from matplotlib.figure import Figure
+
+from typing import Any
+
+class LayoutEngine:
+    def __init__(self, **kwargs: Any) -> None: ...
+    def set(self) -> None: ...
+    @property
+    def colorbar_gridspec(self) -> bool: ...
+    @property
+    def adjust_compatible(self) -> bool: ...
+    def get(self) -> dict[str, Any]: ...
+    def execute(self, fig: Figure) -> None: ...
+
+class PlaceHolderLayoutEngine(LayoutEngine):
+    def __init__(
+        self, adjust_compatible: bool, colorbar_gridspec: bool, **kwargs: Any
+    ) -> None: ...
+    def execute(self, fig: Figure) -> None: ...
+
+class TightLayoutEngine(LayoutEngine):
+    def __init__(
+        self,
+        *,
+        pad: float = ...,
+        h_pad: float | None = ...,
+        w_pad: float | None = ...,
+        rect: tuple[float, float, float, float] = ...,
+        **kwargs: Any
+    ) -> None: ...
+    def execute(self, fig: Figure) -> None: ...
+    def set(
+        self,
+        *,
+        pad: float | None = ...,
+        w_pad: float | None = ...,
+        h_pad: float | None = ...,
+        rect: tuple[float, float, float, float] | None = ...
+    ) -> None: ...
+
+class ConstrainedLayoutEngine(LayoutEngine):
+    def __init__(
+        self,
+        *,
+        h_pad: float | None = ...,
+        w_pad: float | None = ...,
+        hspace: float | None = ...,
+        wspace: float | None = ...,
+        rect: tuple[float, float, float, float] = ...,
+        compress: bool = ...,
+        **kwargs: Any
+    ) -> None: ...
+    def execute(self, fig: Figure) -> Any: ...
+    def set(
+        self,
+        *,
+        h_pad: float | None = ...,
+        w_pad: float | None = ...,
+        hspace: float | None = ...,
+        wspace: float | None = ...,
+        rect: tuple[float, float, float, float] | None = ...
+    ) -> None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/legend.pyi b/lib/python3.12/site-packages/matplotlib/legend.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..dde5882da69d0c866586ad199ed4c3012adc1f01
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/legend.pyi
@@ -0,0 +1,152 @@
+from matplotlib.axes import Axes
+from matplotlib.artist import Artist
+from matplotlib.backend_bases import MouseEvent
+from matplotlib.figure import Figure
+from matplotlib.font_manager import FontProperties
+from matplotlib.legend_handler import HandlerBase
+from matplotlib.lines import Line2D
+from matplotlib.offsetbox import (
+    DraggableOffsetBox,
+)
+from matplotlib.patches import FancyBboxPatch, Patch, Rectangle
+from matplotlib.text import Text
+from matplotlib.transforms import (
+    BboxBase,
+    Transform,
+)
+
+
+import pathlib
+from collections.abc import Iterable
+from typing import Any, Literal, overload
+from .typing import ColorType
+
+class DraggableLegend(DraggableOffsetBox):
+    legend: Legend
+    def __init__(
+        self, legend: Legend, use_blit: bool = ..., update: Literal["loc", "bbox"] = ...
+    ) -> None: ...
+    def finalize_offset(self) -> None: ...
+
+class Legend(Artist):
+    codes: dict[str, int]
+    zorder: float
+    prop: FontProperties
+    texts: list[Text]
+    legend_handles: list[Artist | None]
+    numpoints: int
+    markerscale: float
+    scatterpoints: int
+    borderpad: float
+    labelspacing: float
+    handlelength: float
+    handleheight: float
+    handletextpad: float
+    borderaxespad: float
+    columnspacing: float
+    shadow: bool
+    isaxes: bool
+    axes: Axes
+    parent: Axes | Figure
+    legendPatch: FancyBboxPatch
+    def __init__(
+        self,
+        parent: Axes | Figure,
+        handles: Iterable[Artist | tuple[Artist, ...]],
+        labels: Iterable[str],
+        *,
+        loc: str | tuple[float, float] | int | None = ...,
+        numpoints: int | None = ...,
+        markerscale: float | None = ...,
+        markerfirst: bool = ...,
+        reverse: bool = ...,
+        scatterpoints: int | None = ...,
+        scatteryoffsets: Iterable[float] | None = ...,
+        prop: FontProperties | dict[str, Any] | None = ...,
+        fontsize: float | str | None = ...,
+        labelcolor: ColorType
+        | Iterable[ColorType]
+        | Literal["linecolor", "markerfacecolor", "mfc", "markeredgecolor", "mec"]
+        | None = ...,
+        borderpad: float | None = ...,
+        labelspacing: float | None = ...,
+        handlelength: float | None = ...,
+        handleheight: float | None = ...,
+        handletextpad: float | None = ...,
+        borderaxespad: float | None = ...,
+        columnspacing: float | None = ...,
+        ncols: int = ...,
+        mode: Literal["expand"] | None = ...,
+        fancybox: bool | None = ...,
+        shadow: bool | dict[str, Any] | None = ...,
+        title: str | None = ...,
+        title_fontsize: float | None = ...,
+        framealpha: float | None = ...,
+        edgecolor: Literal["inherit"] | ColorType | None = ...,
+        facecolor: Literal["inherit"] | ColorType | None = ...,
+        bbox_to_anchor: BboxBase
+        | tuple[float, float]
+        | tuple[float, float, float, float]
+        | None = ...,
+        bbox_transform: Transform | None = ...,
+        frameon: bool | None = ...,
+        handler_map: dict[Artist | type, HandlerBase] | None = ...,
+        title_fontproperties: FontProperties | dict[str, Any] | None = ...,
+        alignment: Literal["center", "left", "right"] = ...,
+        ncol: int = ...,
+        draggable: bool = ...
+    ) -> None: ...
+    def contains(self, mouseevent: MouseEvent) -> tuple[bool, dict[Any, Any]]: ...
+    def set_ncols(self, ncols: int) -> None: ...
+    @classmethod
+    def get_default_handler_map(cls) -> dict[type, HandlerBase]: ...
+    @classmethod
+    def set_default_handler_map(cls, handler_map: dict[type, HandlerBase]) -> None: ...
+    @classmethod
+    def update_default_handler_map(
+        cls, handler_map: dict[type, HandlerBase]
+    ) -> None: ...
+    def get_legend_handler_map(self) -> dict[type, HandlerBase]: ...
+    @staticmethod
+    def get_legend_handler(
+        legend_handler_map: dict[type, HandlerBase], orig_handle: Any
+    ) -> HandlerBase | None: ...
+    def get_children(self) -> list[Artist]: ...
+    def get_frame(self) -> Rectangle: ...
+    def get_lines(self) -> list[Line2D]: ...
+    def get_patches(self) -> list[Patch]: ...
+    def get_texts(self) -> list[Text]: ...
+    def set_alignment(self, alignment: Literal["center", "left", "right"]) -> None: ...
+    def get_alignment(self) -> Literal["center", "left", "right"]: ...
+    def set_loc(self, loc: str | tuple[float, float] | int | None = ...) -> None: ...
+    def set_title(
+        self, title: str, prop: FontProperties | str | pathlib.Path | None = ...
+    ) -> None: ...
+    def get_title(self) -> Text: ...
+    def get_frame_on(self) -> bool: ...
+    def set_frame_on(self, b: bool) -> None: ...
+    draw_frame = set_frame_on
+    def get_bbox_to_anchor(self) -> BboxBase: ...
+    def set_bbox_to_anchor(
+        self,
+        bbox: BboxBase
+        | tuple[float, float]
+        | tuple[float, float, float, float]
+        | None,
+        transform: Transform | None = ...
+    ) -> None: ...
+    @overload
+    def set_draggable(
+        self,
+        state: Literal[True],
+        use_blit: bool = ...,
+        update: Literal["loc", "bbox"] = ...,
+    ) -> DraggableLegend: ...
+    @overload
+    def set_draggable(
+        self,
+        state: Literal[False],
+        use_blit: bool = ...,
+        update: Literal["loc", "bbox"] = ...,
+    ) -> None: ...
+    def get_draggable(self) -> bool: ...
diff --git a/lib/python3.12/site-packages/matplotlib/lines.pyi b/lib/python3.12/site-packages/matplotlib/lines.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..7989a03dae3a0680f63511a0d5347517753a2d1e
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/lines.pyi
@@ -0,0 +1,153 @@
+from .artist import Artist
+from .axes import Axes
+from .backend_bases import MouseEvent, FigureCanvasBase
+from .path import Path
+from .transforms import Bbox
+
+from collections.abc import Callable, Sequence
+from typing import Any, Literal, overload
+from .typing import (
+    ColorType,
+    DrawStyleType,
+    FillStyleType,
+    LineStyleType,
+    CapStyleType,
+    JoinStyleType,
+    MarkEveryType,
+    MarkerType,
+)
+from numpy.typing import ArrayLike
+
+def segment_hits(
+    cx: ArrayLike, cy: ArrayLike, x: ArrayLike, y: ArrayLike, radius: ArrayLike
+) -> ArrayLike: ...
+
+class Line2D(Artist):
+    lineStyles: dict[str, str]
+    drawStyles: dict[str, str]
+    drawStyleKeys: list[str]
+    markers: dict[str | int, str]
+    filled_markers: tuple[str, ...]
+    fillStyles: tuple[str, ...]
+    zorder: float
+    ind_offset: float
+    def __init__(
+        self,
+        xdata: ArrayLike,
+        ydata: ArrayLike,
+        *,
+        linewidth: float | None = ...,
+        linestyle: LineStyleType | None = ...,
+        color: ColorType | None = ...,
+        gapcolor: ColorType | None = ...,
+        marker: MarkerType | None = ...,
+        markersize: float | None = ...,
+        markeredgewidth: float | None = ...,
+        markeredgecolor: ColorType | None = ...,
+        markerfacecolor: ColorType | None = ...,
+        markerfacecoloralt: ColorType = ...,
+        fillstyle: FillStyleType | None = ...,
+        antialiased: bool | None = ...,
+        dash_capstyle: CapStyleType | None = ...,
+        solid_capstyle: CapStyleType | None = ...,
+        dash_joinstyle: JoinStyleType | None = ...,
+        solid_joinstyle: JoinStyleType | None = ...,
+        pickradius: float = ...,
+        drawstyle: DrawStyleType | None = ...,
+        markevery: MarkEveryType | None = ...,
+        **kwargs
+    ) -> None: ...
+    def contains(self, mouseevent: MouseEvent) -> tuple[bool, dict]: ...
+    def get_pickradius(self) -> float: ...
+    def set_pickradius(self, pickradius: float) -> None: ...
+    pickradius: float
+    def get_fillstyle(self) -> FillStyleType: ...
+    stale: bool
+    def set_fillstyle(self, fs: FillStyleType) -> None: ...
+    def set_markevery(self, every: MarkEveryType) -> None: ...
+    def get_markevery(self) -> MarkEveryType: ...
+    def set_picker(
+        self, p: None | bool | float | Callable[[Artist, MouseEvent], tuple[bool, dict]]
+    ) -> None: ...
+    def get_bbox(self) -> Bbox: ...
+    @overload
+    def set_data(self, args: ArrayLike) -> None: ...
+    @overload
+    def set_data(self, x: ArrayLike, y: ArrayLike) -> None: ...
+    def recache_always(self) -> None: ...
+    def recache(self, always: bool = ...) -> None: ...
+    def get_antialiased(self) -> bool: ...
+    def get_color(self) -> ColorType: ...
+    def get_drawstyle(self) -> DrawStyleType: ...
+    def get_gapcolor(self) -> ColorType: ...
+    def get_linestyle(self) -> LineStyleType: ...
+    def get_linewidth(self) -> float: ...
+    def get_marker(self) -> MarkerType: ...
+    def get_markeredgecolor(self) -> ColorType: ...
+    def get_markeredgewidth(self) -> float: ...
+    def get_markerfacecolor(self) -> ColorType: ...
+    def get_markerfacecoloralt(self) -> ColorType: ...
+    def get_markersize(self) -> float: ...
+    def get_data(self, orig: bool = ...) -> tuple[ArrayLike, ArrayLike]: ...
+    def get_xdata(self, orig: bool = ...) -> ArrayLike: ...
+    def get_ydata(self, orig: bool = ...) -> ArrayLike: ...
+    def get_path(self) -> Path: ...
+    def get_xydata(self) -> ArrayLike: ...
+    def set_antialiased(self, b: bool) -> None: ...
+    def set_color(self, color: ColorType) -> None: ...
+    def set_drawstyle(self, drawstyle: DrawStyleType | None) -> None: ...
+    def set_gapcolor(self, gapcolor: ColorType | None) -> None: ...
+    def set_linewidth(self, w: float) -> None: ...
+    def set_linestyle(self, ls: LineStyleType) -> None: ...
+    def set_marker(self, marker: MarkerType) -> None: ...
+    def set_markeredgecolor(self, ec: ColorType | None) -> None: ...
+    def set_markerfacecolor(self, fc: ColorType | None) -> None: ...
+    def set_markerfacecoloralt(self, fc: ColorType | None) -> None: ...
+    def set_markeredgewidth(self, ew: float | None) -> None: ...
+    def set_markersize(self, sz: float) -> None: ...
+    def set_xdata(self, x: ArrayLike) -> None: ...
+    def set_ydata(self, y: ArrayLike) -> None: ...
+    def set_dashes(self, seq: Sequence[float] | tuple[None, None]) -> None: ...
+    def update_from(self, other: Artist) -> None: ...
+    def set_dash_joinstyle(self, s: JoinStyleType) -> None: ...
+    def set_solid_joinstyle(self, s: JoinStyleType) -> None: ...
+    def get_dash_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def get_solid_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def set_dash_capstyle(self, s: CapStyleType) -> None: ...
+    def set_solid_capstyle(self, s: CapStyleType) -> None: ...
+    def get_dash_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def get_solid_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def is_dashed(self) -> bool: ...
+
+class AxLine(Line2D):
+    def __init__(
+        self,
+        xy1: tuple[float, float],
+        xy2: tuple[float, float] | None,
+        slope: float | None,
+        **kwargs
+    ) -> None: ...
+    def get_xy1(self) -> tuple[float, float] | None: ...
+    def get_xy2(self) -> tuple[float, float] | None: ...
+    def get_slope(self) -> float: ...
+    def set_xy1(self, xy1: tuple[float, float]) -> None: ...
+    def set_xy2(self, xy2: tuple[float, float]) -> None: ...
+    def set_slope(self, slope: float) -> None: ...
+
+class VertexSelector:
+    axes: Axes
+    line: Line2D
+    cid: int
+    ind: set[int]
+    def __init__(self, line: Line2D) -> None: ...
+    @property
+    def canvas(self) -> FigureCanvasBase: ...
+    def process_selected(
+        self, ind: Sequence[int], xs: ArrayLike, ys: ArrayLike
+    ) -> None: ...
+    def onpick(self, event: Any) -> None: ...
+
+lineStyles: dict[str, str]
+lineMarkers: dict[str | int, str]
+drawStyles: dict[str, str]
+fillStyles: tuple[FillStyleType, ...]
diff --git a/lib/python3.12/site-packages/matplotlib/markers.pyi b/lib/python3.12/site-packages/matplotlib/markers.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bd2f7dbcaf0ce4a774d743551ce8b3d5e5e1621c
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/markers.pyi
@@ -0,0 +1,51 @@
+from typing import Literal
+
+from .path import Path
+from .transforms import Affine2D, Transform
+
+from numpy.typing import ArrayLike
+from .typing import CapStyleType, FillStyleType, JoinStyleType
+
+TICKLEFT: int
+TICKRIGHT: int
+TICKUP: int
+TICKDOWN: int
+CARETLEFT: int
+CARETRIGHT: int
+CARETUP: int
+CARETDOWN: int
+CARETLEFTBASE: int
+CARETRIGHTBASE: int
+CARETUPBASE: int
+CARETDOWNBASE: int
+
+class MarkerStyle:
+    markers: dict[str | int, str]
+    filled_markers: tuple[str, ...]
+    fillstyles: tuple[FillStyleType, ...]
+
+    def __init__(
+        self,
+        marker: str | ArrayLike | Path | MarkerStyle,
+        fillstyle: FillStyleType | None = ...,
+        transform: Transform | None = ...,
+        capstyle: CapStyleType | None = ...,
+        joinstyle: JoinStyleType | None = ...,
+    ) -> None: ...
+    def __bool__(self) -> bool: ...
+    def is_filled(self) -> bool: ...
+    def get_fillstyle(self) -> FillStyleType: ...
+    def get_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def get_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def get_marker(self) -> str | ArrayLike | Path | None: ...
+    def get_path(self) -> Path: ...
+    def get_transform(self) -> Transform: ...
+    def get_alt_path(self) -> Path | None: ...
+    def get_alt_transform(self) -> Transform: ...
+    def get_snap_threshold(self) -> float | None: ...
+    def get_user_transform(self) -> Transform | None: ...
+    def transformed(self, transform: Affine2D) -> MarkerStyle: ...
+    def rotated(
+        self, *, deg: float | None = ..., rad: float | None = ...
+    ) -> MarkerStyle: ...
+    def scaled(self, sx: float, sy: float | None = ...) -> MarkerStyle: ...
diff --git a/lib/python3.12/site-packages/matplotlib/mathtext.pyi b/lib/python3.12/site-packages/matplotlib/mathtext.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..607501a275c67941e2a67883dc9c99a887ac0581
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/mathtext.pyi
@@ -0,0 +1,33 @@
+import os
+from typing import Generic, IO, Literal, TypeVar, overload
+
+from matplotlib.font_manager import FontProperties
+from matplotlib.typing import ColorType
+
+# Re-exported API from _mathtext.
+from ._mathtext import (
+    RasterParse as RasterParse,
+    VectorParse as VectorParse,
+    get_unicode_index as get_unicode_index,
+)
+
+_ParseType = TypeVar("_ParseType", RasterParse, VectorParse)
+
+class MathTextParser(Generic[_ParseType]):
+    @overload
+    def __init__(self: MathTextParser[VectorParse], output: Literal["path"]) -> None: ...
+    @overload
+    def __init__(self: MathTextParser[RasterParse], output: Literal["agg", "raster", "macosx"]) -> None: ...
+    def parse(
+        self, s: str, dpi: float = ..., prop: FontProperties | None = ..., *, antialiased: bool | None = ...
+    ) -> _ParseType: ...
+
+def math_to_image(
+    s: str,
+    filename_or_obj: str | os.PathLike | IO,
+    prop: FontProperties | None = ...,
+    dpi: float | None = ...,
+    format: str | None = ...,
+    *,
+    color: ColorType | None = ...
+) -> float: ...
diff --git a/lib/python3.12/site-packages/matplotlib/mlab.pyi b/lib/python3.12/site-packages/matplotlib/mlab.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..1f23288dd10b1d8c4be54c0117bc6e34352d33c7
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/mlab.pyi
@@ -0,0 +1,100 @@
+from collections.abc import Callable
+import functools
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+def window_hanning(x: ArrayLike) -> ArrayLike: ...
+def window_none(x: ArrayLike) -> ArrayLike: ...
+def detrend(
+    x: ArrayLike,
+    key: Literal["default", "constant", "mean", "linear", "none"]
+    | Callable[[ArrayLike, int | None], ArrayLike]
+    | None = ...,
+    axis: int | None = ...,
+) -> ArrayLike: ...
+def detrend_mean(x: ArrayLike, axis: int | None = ...) -> ArrayLike: ...
+def detrend_none(x: ArrayLike, axis: int | None = ...) -> ArrayLike: ...
+def detrend_linear(y: ArrayLike) -> ArrayLike: ...
+def psd(
+    x: ArrayLike,
+    NFFT: int | None = ...,
+    Fs: float | None = ...,
+    detrend: Literal["none", "mean", "linear"]
+    | Callable[[ArrayLike, int | None], ArrayLike]
+    | None = ...,
+    window: Callable[[ArrayLike], ArrayLike] | ArrayLike | None = ...,
+    noverlap: int | None = ...,
+    pad_to: int | None = ...,
+    sides: Literal["default", "onesided", "twosided"] | None = ...,
+    scale_by_freq: bool | None = ...,
+) -> tuple[ArrayLike, ArrayLike]: ...
+def csd(
+    x: ArrayLike,
+    y: ArrayLike | None,
+    NFFT: int | None = ...,
+    Fs: float | None = ...,
+    detrend: Literal["none", "mean", "linear"]
+    | Callable[[ArrayLike, int | None], ArrayLike]
+    | None = ...,
+    window: Callable[[ArrayLike], ArrayLike] | ArrayLike | None = ...,
+    noverlap: int | None = ...,
+    pad_to: int | None = ...,
+    sides: Literal["default", "onesided", "twosided"] | None = ...,
+    scale_by_freq: bool | None = ...,
+) -> tuple[ArrayLike, ArrayLike]: ...
+
+complex_spectrum = functools.partial(tuple[ArrayLike, ArrayLike])
+magnitude_spectrum = functools.partial(tuple[ArrayLike, ArrayLike])
+angle_spectrum = functools.partial(tuple[ArrayLike, ArrayLike])
+phase_spectrum = functools.partial(tuple[ArrayLike, ArrayLike])
+
+def specgram(
+    x: ArrayLike,
+    NFFT: int | None = ...,
+    Fs: float | None = ...,
+    detrend: Literal["none", "mean", "linear"] | Callable[[ArrayLike, int | None], ArrayLike] | None = ...,
+    window: Callable[[ArrayLike], ArrayLike] | ArrayLike | None = ...,
+    noverlap: int | None = ...,
+    pad_to: int | None = ...,
+    sides: Literal["default", "onesided", "twosided"] | None = ...,
+    scale_by_freq: bool | None = ...,
+    mode: Literal["psd", "complex", "magnitude", "angle", "phase"] | None = ...,
+) -> tuple[ArrayLike, ArrayLike, ArrayLike]: ...
+def cohere(
+    x: ArrayLike,
+    y: ArrayLike,
+    NFFT: int = ...,
+    Fs: float = ...,
+    detrend: Literal["none", "mean", "linear"] | Callable[[ArrayLike, int | None], ArrayLike] = ...,
+    window: Callable[[ArrayLike], ArrayLike] | ArrayLike = ...,
+    noverlap: int = ...,
+    pad_to: int | None = ...,
+    sides: Literal["default", "onesided", "twosided"] = ...,
+    scale_by_freq: bool | None = ...,
+) -> tuple[ArrayLike, ArrayLike]: ...
+
+class GaussianKDE:
+    dataset: ArrayLike
+    dim: int
+    num_dp: int
+    factor: float
+    data_covariance: ArrayLike
+    data_inv_cov: ArrayLike
+    covariance: ArrayLike
+    inv_cov: ArrayLike
+    norm_factor: float
+    def __init__(
+        self,
+        dataset: ArrayLike,
+        bw_method: Literal["scott", "silverman"]
+        | float
+        | Callable[[GaussianKDE], float]
+        | None = ...,
+    ) -> None: ...
+    def scotts_factor(self) -> float: ...
+    def silverman_factor(self) -> float: ...
+    def covariance_factor(self) -> float: ...
+    def evaluate(self, points: ArrayLike) -> np.ndarray: ...
+    def __call__(self, points: ArrayLike) -> np.ndarray: ...
diff --git a/lib/python3.12/site-packages/matplotlib/patches.py b/lib/python3.12/site-packages/matplotlib/patches.py
new file mode 100644
index 0000000000000000000000000000000000000000..736b1e77e1aca1c925266ab2e9de991f82f2284f
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/patches.py
@@ -0,0 +1,4760 @@
+r"""
+Patches are `.Artist`\s with a face color and an edge color.
+"""
+
+import functools
+import inspect
+import math
+from numbers import Number, Real
+import textwrap
+from types import SimpleNamespace
+from collections import namedtuple
+from matplotlib.transforms import Affine2D
+
+import numpy as np
+
+import matplotlib as mpl
+from . import (_api, artist, cbook, colors, _docstring, hatch as mhatch,
+               lines as mlines, transforms)
+from .bezier import (
+    NonIntersectingPathException, get_cos_sin, get_intersection,
+    get_parallels, inside_circle, make_wedged_bezier2,
+    split_bezier_intersecting_with_closedpath, split_path_inout)
+from .path import Path
+from ._enums import JoinStyle, CapStyle
+
+
+@_docstring.interpd
+@_api.define_aliases({
+    "antialiased": ["aa"],
+    "edgecolor": ["ec"],
+    "facecolor": ["fc"],
+    "linestyle": ["ls"],
+    "linewidth": ["lw"],
+})
+class Patch(artist.Artist):
+    """
+    A patch is a 2D artist with a face color and an edge color.
+
+    If any of *edgecolor*, *facecolor*, *linewidth*, or *antialiased*
+    are *None*, they default to their rc params setting.
+    """
+    zorder = 1
+
+    # Whether to draw an edge by default.  Set on a
+    # subclass-by-subclass basis.
+    _edge_default = False
+
+    def __init__(self, *,
+                 edgecolor=None,
+                 facecolor=None,
+                 color=None,
+                 linewidth=None,
+                 linestyle=None,
+                 antialiased=None,
+                 hatch=None,
+                 fill=True,
+                 capstyle=None,
+                 joinstyle=None,
+                 **kwargs):
+        """
+        The following kwarg properties are supported
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__()
+
+        if linestyle is None:
+            linestyle = "solid"
+        if capstyle is None:
+            capstyle = CapStyle.butt
+        if joinstyle is None:
+            joinstyle = JoinStyle.miter
+
+        self._hatch_color = colors.to_rgba(mpl.rcParams['hatch.color'])
+        self._hatch_linewidth = mpl.rcParams['hatch.linewidth']
+        self._fill = bool(fill)  # needed for set_facecolor call
+        if color is not None:
+            if edgecolor is not None or facecolor is not None:
+                _api.warn_external(
+                    "Setting the 'color' property will override "
+                    "the edgecolor or facecolor properties.")
+            self.set_color(color)
+        else:
+            self.set_edgecolor(edgecolor)
+            self.set_facecolor(facecolor)
+
+        self._linewidth = 0
+        self._unscaled_dash_pattern = (0, None)  # offset, dash
+        self._dash_pattern = (0, None)  # offset, dash (scaled by linewidth)
+
+        self.set_linestyle(linestyle)
+        self.set_linewidth(linewidth)
+        self.set_antialiased(antialiased)
+        self.set_hatch(hatch)
+        self.set_capstyle(capstyle)
+        self.set_joinstyle(joinstyle)
+
+        if len(kwargs):
+            self._internal_update(kwargs)
+
+    def get_verts(self):
+        """
+        Return a copy of the vertices used in this patch.
+
+        If the patch contains Bézier curves, the curves will be interpolated by
+        line segments.  To access the curves as curves, use `get_path`.
+        """
+        trans = self.get_transform()
+        path = self.get_path()
+        polygons = path.to_polygons(trans)
+        if len(polygons):
+            return polygons[0]
+        return []
+
+    def _process_radius(self, radius):
+        if radius is not None:
+            return radius
+        if isinstance(self._picker, Number):
+            _radius = self._picker
+        else:
+            if self.get_edgecolor()[3] == 0:
+                _radius = 0
+            else:
+                _radius = self.get_linewidth()
+        return _radius
+
+    def contains(self, mouseevent, radius=None):
+        """
+        Test whether the mouse event occurred in the patch.
+
+        Parameters
+        ----------
+        mouseevent : `~matplotlib.backend_bases.MouseEvent`
+            Where the user clicked.
+
+        radius : float, optional
+            Additional margin on the patch in target coordinates of
+            `.Patch.get_transform`. See `.Path.contains_point` for further
+            details.
+
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
+
+        Returns
+        -------
+        (bool, empty dict)
+        """
+        if self._different_canvas(mouseevent):
+            return False, {}
+        radius = self._process_radius(radius)
+        codes = self.get_path().codes
+        if codes is not None:
+            vertices = self.get_path().vertices
+            # if the current path is concatenated by multiple sub paths.
+            # get the indexes of the starting code(MOVETO) of all sub paths
+            idxs, = np.where(codes == Path.MOVETO)
+            # Don't split before the first MOVETO.
+            idxs = idxs[1:]
+            subpaths = map(
+                Path, np.split(vertices, idxs), np.split(codes, idxs))
+        else:
+            subpaths = [self.get_path()]
+        inside = any(
+            subpath.contains_point(
+                (mouseevent.x, mouseevent.y), self.get_transform(), radius)
+            for subpath in subpaths)
+        return inside, {}
+
+    def contains_point(self, point, radius=None):
+        """
+        Return whether the given point is inside the patch.
+
+        Parameters
+        ----------
+        point : (float, float)
+            The point (x, y) to check, in target coordinates of
+            ``.Patch.get_transform()``. These are display coordinates for patches
+            that are added to a figure or Axes.
+        radius : float, optional
+            Additional margin on the patch in target coordinates of
+            `.Patch.get_transform`. See `.Path.contains_point` for further
+            details.
+
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
+        Returns
+        -------
+        bool
+
+        Notes
+        -----
+        The proper use of this method depends on the transform of the patch.
+        Isolated patches do not have a transform. In this case, the patch
+        creation coordinates and the point coordinates match. The following
+        example checks that the center of a circle is within the circle
+
+        >>> center = 0, 0
+        >>> c = Circle(center, radius=1)
+        >>> c.contains_point(center)
+        True
+
+        The convention of checking against the transformed patch stems from
+        the fact that this method is predominantly used to check if display
+        coordinates (e.g. from mouse events) are within the patch. If you want
+        to do the above check with data coordinates, you have to properly
+        transform them first:
+
+        >>> center = 0, 0
+        >>> c = Circle(center, radius=3)
+        >>> plt.gca().add_patch(c)
+        >>> transformed_interior_point = c.get_data_transform().transform((0, 2))
+        >>> c.contains_point(transformed_interior_point)
+        True
+
+        """
+        radius = self._process_radius(radius)
+        return self.get_path().contains_point(point,
+                                              self.get_transform(),
+                                              radius)
+
+    def contains_points(self, points, radius=None):
+        """
+        Return whether the given points are inside the patch.
+
+        Parameters
+        ----------
+        points : (N, 2) array
+            The points to check, in target coordinates of
+            ``self.get_transform()``. These are display coordinates for patches
+            that are added to a figure or Axes. Columns contain x and y values.
+        radius : float, optional
+            Additional margin on the patch in target coordinates of
+            `.Patch.get_transform`. See `.Path.contains_point` for further
+            details.
+
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
+        Returns
+        -------
+        length-N bool array
+
+        Notes
+        -----
+        The proper use of this method depends on the transform of the patch.
+        See the notes on `.Patch.contains_point`.
+        """
+        radius = self._process_radius(radius)
+        return self.get_path().contains_points(points,
+                                               self.get_transform(),
+                                               radius)
+
+    def update_from(self, other):
+        # docstring inherited.
+        super().update_from(other)
+        # For some properties we don't need or don't want to go through the
+        # getters/setters, so we just copy them directly.
+        self._edgecolor = other._edgecolor
+        self._facecolor = other._facecolor
+        self._original_edgecolor = other._original_edgecolor
+        self._original_facecolor = other._original_facecolor
+        self._fill = other._fill
+        self._hatch = other._hatch
+        self._hatch_color = other._hatch_color
+        self._unscaled_dash_pattern = other._unscaled_dash_pattern
+        self.set_linewidth(other._linewidth)  # also sets scaled dashes
+        self.set_transform(other.get_data_transform())
+        # If the transform of other needs further initialization, then it will
+        # be the case for this artist too.
+        self._transformSet = other.is_transform_set()
+
+    def get_extents(self):
+        """
+        Return the `Patch`'s axis-aligned extents as a `~.transforms.Bbox`.
+        """
+        return self.get_path().get_extents(self.get_transform())
+
+    def get_transform(self):
+        """Return the `~.transforms.Transform` applied to the `Patch`."""
+        return self.get_patch_transform() + artist.Artist.get_transform(self)
+
+    def get_data_transform(self):
+        """
+        Return the `~.transforms.Transform` mapping data coordinates to
+        physical coordinates.
+        """
+        return artist.Artist.get_transform(self)
+
+    def get_patch_transform(self):
+        """
+        Return the `~.transforms.Transform` instance mapping patch coordinates
+        to data coordinates.
+
+        For example, one may define a patch of a circle which represents a
+        radius of 5 by providing coordinates for a unit circle, and a
+        transform which scales the coordinates (the patch coordinate) by 5.
+        """
+        return transforms.IdentityTransform()
+
+    def get_antialiased(self):
+        """Return whether antialiasing is used for drawing."""
+        return self._antialiased
+
+    def get_edgecolor(self):
+        """Return the edge color."""
+        return self._edgecolor
+
+    def get_facecolor(self):
+        """Return the face color."""
+        return self._facecolor
+
+    def get_linewidth(self):
+        """Return the line width in points."""
+        return self._linewidth
+
+    def get_linestyle(self):
+        """Return the linestyle."""
+        return self._linestyle
+
+    def set_antialiased(self, aa):
+        """
+        Set whether to use antialiased rendering.
+
+        Parameters
+        ----------
+        aa : bool or None
+        """
+        if aa is None:
+            aa = mpl.rcParams['patch.antialiased']
+        self._antialiased = aa
+        self.stale = True
+
+    def _set_edgecolor(self, color):
+        set_hatch_color = True
+        if color is None:
+            if (mpl.rcParams['patch.force_edgecolor'] or
+                    not self._fill or self._edge_default):
+                color = mpl.rcParams['patch.edgecolor']
+            else:
+                color = 'none'
+                set_hatch_color = False
+
+        self._edgecolor = colors.to_rgba(color, self._alpha)
+        if set_hatch_color:
+            self._hatch_color = self._edgecolor
+        self.stale = True
+
+    def set_edgecolor(self, color):
+        """
+        Set the patch edge color.
+
+        Parameters
+        ----------
+        color : :mpltype:`color` or None
+        """
+        self._original_edgecolor = color
+        self._set_edgecolor(color)
+
+    def _set_facecolor(self, color):
+        if color is None:
+            color = mpl.rcParams['patch.facecolor']
+        alpha = self._alpha if self._fill else 0
+        self._facecolor = colors.to_rgba(color, alpha)
+        self.stale = True
+
+    def set_facecolor(self, color):
+        """
+        Set the patch face color.
+
+        Parameters
+        ----------
+        color : :mpltype:`color` or None
+        """
+        self._original_facecolor = color
+        self._set_facecolor(color)
+
+    def set_color(self, c):
+        """
+        Set both the edgecolor and the facecolor.
+
+        Parameters
+        ----------
+        c : :mpltype:`color`
+
+        See Also
+        --------
+        Patch.set_facecolor, Patch.set_edgecolor
+            For setting the edge or face color individually.
+        """
+        self.set_facecolor(c)
+        self.set_edgecolor(c)
+
+    def set_alpha(self, alpha):
+        # docstring inherited
+        super().set_alpha(alpha)
+        self._set_facecolor(self._original_facecolor)
+        self._set_edgecolor(self._original_edgecolor)
+        # stale is already True
+
+    def set_linewidth(self, w):
+        """
+        Set the patch linewidth in points.
+
+        Parameters
+        ----------
+        w : float or None
+        """
+        if w is None:
+            w = mpl.rcParams['patch.linewidth']
+        self._linewidth = float(w)
+        self._dash_pattern = mlines._scale_dashes(
+            *self._unscaled_dash_pattern, w)
+        self.stale = True
+
+    def set_linestyle(self, ls):
+        """
+        Set the patch linestyle.
+
+        ==========================================  =================
+        linestyle                                   description
+        ==========================================  =================
+        ``'-'`` or ``'solid'``                      solid line
+        ``'--'`` or  ``'dashed'``                   dashed line
+        ``'-.'`` or  ``'dashdot'``                  dash-dotted line
+        ``':'`` or ``'dotted'``                     dotted line
+        ``'none'``, ``'None'``, ``' '``, or ``''``  draw nothing
+        ==========================================  =================
+
+        Alternatively a dash tuple of the following form can be provided::
+
+            (offset, onoffseq)
+
+        where ``onoffseq`` is an even length tuple of on and off ink in points.
+
+        Parameters
+        ----------
+        ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
+            The line style.
+        """
+        if ls is None:
+            ls = "solid"
+        if ls in [' ', '', 'none']:
+            ls = 'None'
+        self._linestyle = ls
+        self._unscaled_dash_pattern = mlines._get_dash_pattern(ls)
+        self._dash_pattern = mlines._scale_dashes(
+            *self._unscaled_dash_pattern, self._linewidth)
+        self.stale = True
+
+    def set_fill(self, b):
+        """
+        Set whether to fill the patch.
+
+        Parameters
+        ----------
+        b : bool
+        """
+        self._fill = bool(b)
+        self._set_facecolor(self._original_facecolor)
+        self._set_edgecolor(self._original_edgecolor)
+        self.stale = True
+
+    def get_fill(self):
+        """Return whether the patch is filled."""
+        return self._fill
+
+    # Make fill a property so as to preserve the long-standing
+    # but somewhat inconsistent behavior in which fill was an
+    # attribute.
+    fill = property(get_fill, set_fill)
+
+    @_docstring.interpd
+    def set_capstyle(self, s):
+        """
+        Set the `.CapStyle`.
+
+        The default capstyle is 'round' for `.FancyArrowPatch` and 'butt' for
+        all other patches.
+
+        Parameters
+        ----------
+        s : `.CapStyle` or %(CapStyle)s
+        """
+        cs = CapStyle(s)
+        self._capstyle = cs
+        self.stale = True
+
+    def get_capstyle(self):
+        """Return the capstyle."""
+        return self._capstyle.name
+
+    @_docstring.interpd
+    def set_joinstyle(self, s):
+        """
+        Set the `.JoinStyle`.
+
+        The default joinstyle is 'round' for `.FancyArrowPatch` and 'miter' for
+        all other patches.
+
+        Parameters
+        ----------
+        s : `.JoinStyle` or %(JoinStyle)s
+        """
+        js = JoinStyle(s)
+        self._joinstyle = js
+        self.stale = True
+
+    def get_joinstyle(self):
+        """Return the joinstyle."""
+        return self._joinstyle.name
+
+    def set_hatch(self, hatch):
+        r"""
+        Set the hatching pattern.
+
+        *hatch* can be one of::
+
+          /   - diagonal hatching
+          \   - back diagonal
+          |   - vertical
+          -   - horizontal
+          +   - crossed
+          x   - crossed diagonal
+          o   - small circle
+          O   - large circle
+          .   - dots
+          *   - stars
+
+        Letters can be combined, in which case all the specified
+        hatchings are done.  If same letter repeats, it increases the
+        density of hatching of that pattern.
+
+        Parameters
+        ----------
+        hatch : {'/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
+        """
+        # Use validate_hatch(list) after deprecation.
+        mhatch._validate_hatch_pattern(hatch)
+        self._hatch = hatch
+        self.stale = True
+
+    def get_hatch(self):
+        """Return the hatching pattern."""
+        return self._hatch
+
+    def set_hatch_linewidth(self, lw):
+        """Set the hatch linewidth."""
+        self._hatch_linewidth = lw
+
+    def get_hatch_linewidth(self):
+        """Return the hatch linewidth."""
+        return self._hatch_linewidth
+
+    def _draw_paths_with_artist_properties(
+            self, renderer, draw_path_args_list):
+        """
+        ``draw()`` helper factored out for sharing with `FancyArrowPatch`.
+
+        Configure *renderer* and the associated graphics context *gc*
+        from the artist properties, then repeatedly call
+        ``renderer.draw_path(gc, *draw_path_args)`` for each tuple
+        *draw_path_args* in *draw_path_args_list*.
+        """
+
+        renderer.open_group('patch', self.get_gid())
+        gc = renderer.new_gc()
+
+        gc.set_foreground(self._edgecolor, isRGBA=True)
+
+        lw = self._linewidth
+        if self._edgecolor[3] == 0 or self._linestyle == 'None':
+            lw = 0
+        gc.set_linewidth(lw)
+        gc.set_dashes(*self._dash_pattern)
+        gc.set_capstyle(self._capstyle)
+        gc.set_joinstyle(self._joinstyle)
+
+        gc.set_antialiased(self._antialiased)
+        self._set_gc_clip(gc)
+        gc.set_url(self._url)
+        gc.set_snap(self.get_snap())
+
+        gc.set_alpha(self._alpha)
+
+        if self._hatch:
+            gc.set_hatch(self._hatch)
+            gc.set_hatch_color(self._hatch_color)
+            gc.set_hatch_linewidth(self._hatch_linewidth)
+
+        if self.get_sketch_params() is not None:
+            gc.set_sketch_params(*self.get_sketch_params())
+
+        if self.get_path_effects():
+            from matplotlib.patheffects import PathEffectRenderer
+            renderer = PathEffectRenderer(self.get_path_effects(), renderer)
+
+        for draw_path_args in draw_path_args_list:
+            renderer.draw_path(gc, *draw_path_args)
+
+        gc.restore()
+        renderer.close_group('patch')
+        self.stale = False
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        # docstring inherited
+        if not self.get_visible():
+            return
+        path = self.get_path()
+        transform = self.get_transform()
+        tpath = transform.transform_path_non_affine(path)
+        affine = transform.get_affine()
+        self._draw_paths_with_artist_properties(
+            renderer,
+            [(tpath, affine,
+              # Work around a bug in the PDF and SVG renderers, which
+              # do not draw the hatches if the facecolor is fully
+              # transparent, but do if it is None.
+              self._facecolor if self._facecolor[3] else None)])
+
+    def get_path(self):
+        """Return the path of this patch."""
+        raise NotImplementedError('Derived must override')
+
+    def get_window_extent(self, renderer=None):
+        return self.get_path().get_extents(self.get_transform())
+
+    def _convert_xy_units(self, xy):
+        """Convert x and y units for a tuple (x, y)."""
+        x = self.convert_xunits(xy[0])
+        y = self.convert_yunits(xy[1])
+        return x, y
+
+
+class Shadow(Patch):
+    def __str__(self):
+        return f"Shadow({self.patch})"
+
+    @_docstring.interpd
+    def __init__(self, patch, ox, oy, *, shade=0.7, **kwargs):
+        """
+        Create a shadow of the given *patch*.
+
+        By default, the shadow will have the same face color as the *patch*,
+        but darkened. The darkness can be controlled by *shade*.
+
+        Parameters
+        ----------
+        patch : `~matplotlib.patches.Patch`
+            The patch to create the shadow for.
+        ox, oy : float
+            The shift of the shadow in data coordinates, scaled by a factor
+            of dpi/72.
+        shade : float, default: 0.7
+            How the darkness of the shadow relates to the original color. If 1, the
+            shadow is black, if 0, the shadow has the same color as the *patch*.
+
+            .. versionadded:: 3.8
+
+        **kwargs
+            Properties of the shadow patch. Supported keys are:
+
+            %(Patch:kwdoc)s
+        """
+        super().__init__()
+        self.patch = patch
+        self._ox, self._oy = ox, oy
+        self._shadow_transform = transforms.Affine2D()
+
+        self.update_from(self.patch)
+        if not 0 <= shade <= 1:
+            raise ValueError("shade must be between 0 and 1.")
+        color = (1 - shade) * np.asarray(colors.to_rgb(self.patch.get_facecolor()))
+        self.update({'facecolor': color, 'edgecolor': color, 'alpha': 0.5,
+                     # Place shadow patch directly behind the inherited patch.
+                     'zorder': np.nextafter(self.patch.zorder, -np.inf),
+                     **kwargs})
+
+    def _update_transform(self, renderer):
+        ox = renderer.points_to_pixels(self._ox)
+        oy = renderer.points_to_pixels(self._oy)
+        self._shadow_transform.clear().translate(ox, oy)
+
+    def get_path(self):
+        return self.patch.get_path()
+
+    def get_patch_transform(self):
+        return self.patch.get_patch_transform() + self._shadow_transform
+
+    def draw(self, renderer):
+        self._update_transform(renderer)
+        super().draw(renderer)
+
+
+class Rectangle(Patch):
+    """
+    A rectangle defined via an anchor point *xy* and its *width* and *height*.
+
+    The rectangle extends from ``xy[0]`` to ``xy[0] + width`` in x-direction
+    and from ``xy[1]`` to ``xy[1] + height`` in y-direction. ::
+
+      :                +------------------+
+      :                |                  |
+      :              height               |
+      :                |                  |
+      :               (xy)---- width -----+
+
+    One may picture *xy* as the bottom left corner, but which corner *xy* is
+    actually depends on the direction of the axis and the sign of *width*
+    and *height*; e.g. *xy* would be the bottom right corner if the x-axis
+    was inverted or if *width* was negative.
+    """
+
+    def __str__(self):
+        pars = self._x0, self._y0, self._width, self._height, self.angle
+        fmt = "Rectangle(xy=(%g, %g), width=%g, height=%g, angle=%g)"
+        return fmt % pars
+
+    @_docstring.interpd
+    def __init__(self, xy, width, height, *,
+                 angle=0.0, rotation_point='xy', **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+            The anchor point.
+        width : float
+            Rectangle width.
+        height : float
+            Rectangle height.
+        angle : float, default: 0
+            Rotation in degrees anti-clockwise about the rotation point.
+        rotation_point : {'xy', 'center', (number, number)}, default: 'xy'
+            If ``'xy'``, rotate around the anchor point. If ``'center'`` rotate
+            around the center. If 2-tuple of number, rotate around this
+            coordinate.
+
+        Other Parameters
+        ----------------
+        **kwargs : `~matplotlib.patches.Patch` properties
+            %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+        self._x0 = xy[0]
+        self._y0 = xy[1]
+        self._width = width
+        self._height = height
+        self.angle = float(angle)
+        self.rotation_point = rotation_point
+        # Required for RectangleSelector with axes aspect ratio != 1
+        # The patch is defined in data coordinates and when changing the
+        # selector with square modifier and not in data coordinates, we need
+        # to correct for the aspect ratio difference between the data and
+        # display coordinate systems. Its value is typically provide by
+        # Axes._get_aspect_ratio()
+        self._aspect_ratio_correction = 1.0
+        self._convert_units()  # Validate the inputs.
+
+    def get_path(self):
+        """Return the vertices of the rectangle."""
+        return Path.unit_rectangle()
+
+    def _convert_units(self):
+        """Convert bounds of the rectangle."""
+        x0 = self.convert_xunits(self._x0)
+        y0 = self.convert_yunits(self._y0)
+        x1 = self.convert_xunits(self._x0 + self._width)
+        y1 = self.convert_yunits(self._y0 + self._height)
+        return x0, y0, x1, y1
+
+    def get_patch_transform(self):
+        # Note: This cannot be called until after this has been added to
+        # an Axes, otherwise unit conversion will fail. This makes it very
+        # important to call the accessor method and not directly access the
+        # transformation member variable.
+        bbox = self.get_bbox()
+        if self.rotation_point == 'center':
+            width, height = bbox.x1 - bbox.x0, bbox.y1 - bbox.y0
+            rotation_point = bbox.x0 + width / 2., bbox.y0 + height / 2.
+        elif self.rotation_point == 'xy':
+            rotation_point = bbox.x0, bbox.y0
+        else:
+            rotation_point = self.rotation_point
+        return transforms.BboxTransformTo(bbox) \
+                + transforms.Affine2D() \
+                .translate(-rotation_point[0], -rotation_point[1]) \
+                .scale(1, self._aspect_ratio_correction) \
+                .rotate_deg(self.angle) \
+                .scale(1, 1 / self._aspect_ratio_correction) \
+                .translate(*rotation_point)
+
+    @property
+    def rotation_point(self):
+        """The rotation point of the patch."""
+        return self._rotation_point
+
+    @rotation_point.setter
+    def rotation_point(self, value):
+        if value in ['center', 'xy'] or (
+                isinstance(value, tuple) and len(value) == 2 and
+                isinstance(value[0], Real) and isinstance(value[1], Real)
+                ):
+            self._rotation_point = value
+        else:
+            raise ValueError("`rotation_point` must be one of "
+                             "{'xy', 'center', (number, number)}.")
+
+    def get_x(self):
+        """Return the left coordinate of the rectangle."""
+        return self._x0
+
+    def get_y(self):
+        """Return the bottom coordinate of the rectangle."""
+        return self._y0
+
+    def get_xy(self):
+        """Return the left and bottom coords of the rectangle as a tuple."""
+        return self._x0, self._y0
+
+    def get_corners(self):
+        """
+        Return the corners of the rectangle, moving anti-clockwise from
+        (x0, y0).
+        """
+        return self.get_patch_transform().transform(
+            [(0, 0), (1, 0), (1, 1), (0, 1)])
+
+    def get_center(self):
+        """Return the centre of the rectangle."""
+        return self.get_patch_transform().transform((0.5, 0.5))
+
+    def get_width(self):
+        """Return the width of the rectangle."""
+        return self._width
+
+    def get_height(self):
+        """Return the height of the rectangle."""
+        return self._height
+
+    def get_angle(self):
+        """Get the rotation angle in degrees."""
+        return self.angle
+
+    def set_x(self, x):
+        """Set the left coordinate of the rectangle."""
+        self._x0 = x
+        self.stale = True
+
+    def set_y(self, y):
+        """Set the bottom coordinate of the rectangle."""
+        self._y0 = y
+        self.stale = True
+
+    def set_angle(self, angle):
+        """
+        Set the rotation angle in degrees.
+
+        The rotation is performed anti-clockwise around *xy*.
+        """
+        self.angle = angle
+        self.stale = True
+
+    def set_xy(self, xy):
+        """
+        Set the left and bottom coordinates of the rectangle.
+
+        Parameters
+        ----------
+        xy : (float, float)
+        """
+        self._x0, self._y0 = xy
+        self.stale = True
+
+    def set_width(self, w):
+        """Set the width of the rectangle."""
+        self._width = w
+        self.stale = True
+
+    def set_height(self, h):
+        """Set the height of the rectangle."""
+        self._height = h
+        self.stale = True
+
+    def set_bounds(self, *args):
+        """
+        Set the bounds of the rectangle as *left*, *bottom*, *width*, *height*.
+
+        The values may be passed as separate parameters or as a tuple::
+
+            set_bounds(left, bottom, width, height)
+            set_bounds((left, bottom, width, height))
+
+        .. ACCEPTS: (left, bottom, width, height)
+        """
+        if len(args) == 1:
+            l, b, w, h = args[0]
+        else:
+            l, b, w, h = args
+        self._x0 = l
+        self._y0 = b
+        self._width = w
+        self._height = h
+        self.stale = True
+
+    def get_bbox(self):
+        """Return the `.Bbox`."""
+        return transforms.Bbox.from_extents(*self._convert_units())
+
+    xy = property(get_xy, set_xy)
+
+
+class RegularPolygon(Patch):
+    """A regular polygon patch."""
+
+    def __str__(self):
+        s = "RegularPolygon((%g, %g), %d, radius=%g, orientation=%g)"
+        return s % (self.xy[0], self.xy[1], self.numvertices, self.radius,
+                    self.orientation)
+
+    @_docstring.interpd
+    def __init__(self, xy, numVertices, *,
+                 radius=5, orientation=0, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+            The center position.
+
+        numVertices : int
+            The number of vertices.
+
+        radius : float
+            The distance from the center to each of the vertices.
+
+        orientation : float
+            The polygon rotation angle (in radians).
+
+        **kwargs
+            `Patch` properties:
+
+            %(Patch:kwdoc)s
+        """
+        self.xy = xy
+        self.numvertices = numVertices
+        self.orientation = orientation
+        self.radius = radius
+        self._path = Path.unit_regular_polygon(numVertices)
+        self._patch_transform = transforms.Affine2D()
+        super().__init__(**kwargs)
+
+    def get_path(self):
+        return self._path
+
+    def get_patch_transform(self):
+        return self._patch_transform.clear() \
+            .scale(self.radius) \
+            .rotate(self.orientation) \
+            .translate(*self.xy)
+
+
+class PathPatch(Patch):
+    """A general polycurve path patch."""
+
+    _edge_default = True
+
+    def __str__(self):
+        s = "PathPatch%d((%g, %g) ...)"
+        return s % (len(self._path.vertices), *tuple(self._path.vertices[0]))
+
+    @_docstring.interpd
+    def __init__(self, path, **kwargs):
+        """
+        *path* is a `.Path` object.
+
+        Valid keyword arguments are:
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+        self._path = path
+
+    def get_path(self):
+        return self._path
+
+    def set_path(self, path):
+        self._path = path
+
+
+class StepPatch(PathPatch):
+    """
+    A path patch describing a stepwise constant function.
+
+    By default, the path is not closed and starts and stops at
+    baseline value.
+    """
+
+    _edge_default = False
+
+    @_docstring.interpd
+    def __init__(self, values, edges, *,
+                 orientation='vertical', baseline=0, **kwargs):
+        """
+        Parameters
+        ----------
+        values : array-like
+            The step heights.
+
+        edges : array-like
+            The edge positions, with ``len(edges) == len(vals) + 1``,
+            between which the curve takes on vals values.
+
+        orientation : {'vertical', 'horizontal'}, default: 'vertical'
+            The direction of the steps. Vertical means that *values* are
+            along the y-axis, and edges are along the x-axis.
+
+        baseline : float, array-like or None, default: 0
+            The bottom value of the bounding edges or when
+            ``fill=True``, position of lower edge. If *fill* is
+            True or an array is passed to *baseline*, a closed
+            path is drawn.
+
+        **kwargs
+            `Patch` properties:
+
+            %(Patch:kwdoc)s
+        """
+        self.orientation = orientation
+        self._edges = np.asarray(edges)
+        self._values = np.asarray(values)
+        self._baseline = np.asarray(baseline) if baseline is not None else None
+        self._update_path()
+        super().__init__(self._path, **kwargs)
+
+    def _update_path(self):
+        if np.isnan(np.sum(self._edges)):
+            raise ValueError('Nan values in "edges" are disallowed')
+        if self._edges.size - 1 != self._values.size:
+            raise ValueError('Size mismatch between "values" and "edges". '
+                             "Expected `len(values) + 1 == len(edges)`, but "
+                             f"`len(values) = {self._values.size}` and "
+                             f"`len(edges) = {self._edges.size}`.")
+        # Initializing with empty arrays allows supporting empty stairs.
+        verts, codes = [np.empty((0, 2))], [np.empty(0, dtype=Path.code_type)]
+
+        _nan_mask = np.isnan(self._values)
+        if self._baseline is not None:
+            _nan_mask |= np.isnan(self._baseline)
+        for idx0, idx1 in cbook.contiguous_regions(~_nan_mask):
+            x = np.repeat(self._edges[idx0:idx1+1], 2)
+            y = np.repeat(self._values[idx0:idx1], 2)
+            if self._baseline is None:
+                y = np.concatenate([y[:1], y, y[-1:]])
+            elif self._baseline.ndim == 0:  # single baseline value
+                y = np.concatenate([[self._baseline], y, [self._baseline]])
+            elif self._baseline.ndim == 1:  # baseline array
+                base = np.repeat(self._baseline[idx0:idx1], 2)[::-1]
+                x = np.concatenate([x, x[::-1]])
+                y = np.concatenate([base[-1:], y, base[:1],
+                                    base[:1], base, base[-1:]])
+            else:  # no baseline
+                raise ValueError('Invalid `baseline` specified')
+            if self.orientation == 'vertical':
+                xy = np.column_stack([x, y])
+            else:
+                xy = np.column_stack([y, x])
+            verts.append(xy)
+            codes.append([Path.MOVETO] + [Path.LINETO]*(len(xy)-1))
+        self._path = Path(np.concatenate(verts), np.concatenate(codes))
+
+    def get_data(self):
+        """Get `.StepPatch` values, edges and baseline as namedtuple."""
+        StairData = namedtuple('StairData', 'values edges baseline')
+        return StairData(self._values, self._edges, self._baseline)
+
+    def set_data(self, values=None, edges=None, baseline=None):
+        """
+        Set `.StepPatch` values, edges and baseline.
+
+        Parameters
+        ----------
+        values : 1D array-like or None
+            Will not update values, if passing None
+        edges : 1D array-like, optional
+        baseline : float, 1D array-like or None
+        """
+        if values is None and edges is None and baseline is None:
+            raise ValueError("Must set *values*, *edges* or *baseline*.")
+        if values is not None:
+            self._values = np.asarray(values)
+        if edges is not None:
+            self._edges = np.asarray(edges)
+        if baseline is not None:
+            self._baseline = np.asarray(baseline)
+        self._update_path()
+        self.stale = True
+
+
+class Polygon(Patch):
+    """A general polygon patch."""
+
+    def __str__(self):
+        if len(self._path.vertices):
+            s = "Polygon%d((%g, %g) ...)"
+            return s % (len(self._path.vertices), *self._path.vertices[0])
+        else:
+            return "Polygon0()"
+
+    @_docstring.interpd
+    def __init__(self, xy, *, closed=True, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (N, 2) array
+
+        closed : bool, default: True
+            Whether the polygon is closed (i.e., has identical start and end
+            points).
+
+        **kwargs
+            %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+        self._closed = closed
+        self.set_xy(xy)
+
+    def get_path(self):
+        """Get the `.Path` of the polygon."""
+        return self._path
+
+    def get_closed(self):
+        """Return whether the polygon is closed."""
+        return self._closed
+
+    def set_closed(self, closed):
+        """
+        Set whether the polygon is closed.
+
+        Parameters
+        ----------
+        closed : bool
+            True if the polygon is closed
+        """
+        if self._closed == bool(closed):
+            return
+        self._closed = bool(closed)
+        self.set_xy(self.get_xy())
+        self.stale = True
+
+    def get_xy(self):
+        """
+        Get the vertices of the path.
+
+        Returns
+        -------
+        (N, 2) array
+            The coordinates of the vertices.
+        """
+        return self._path.vertices
+
+    def set_xy(self, xy):
+        """
+        Set the vertices of the polygon.
+
+        Parameters
+        ----------
+        xy : (N, 2) array-like
+            The coordinates of the vertices.
+
+        Notes
+        -----
+        Unlike `.Path`, we do not ignore the last input vertex. If the
+        polygon is meant to be closed, and the last point of the polygon is not
+        equal to the first, we assume that the user has not explicitly passed a
+        ``CLOSEPOLY`` vertex, and add it ourselves.
+        """
+        xy = np.asarray(xy)
+        nverts, _ = xy.shape
+        if self._closed:
+            # if the first and last vertex are the "same", then we assume that
+            # the user explicitly passed the CLOSEPOLY vertex. Otherwise, we
+            # have to append one since the last vertex will be "ignored" by
+            # Path
+            if nverts == 1 or nverts > 1 and (xy[0] != xy[-1]).any():
+                xy = np.concatenate([xy, [xy[0]]])
+        else:
+            # if we aren't closed, and the last vertex matches the first, then
+            # we assume we have an unnecessary CLOSEPOLY vertex and remove it
+            if nverts > 2 and (xy[0] == xy[-1]).all():
+                xy = xy[:-1]
+        self._path = Path(xy, closed=self._closed)
+        self.stale = True
+
+    xy = property(get_xy, set_xy,
+                  doc='The vertices of the path as a (N, 2) array.')
+
+
+class Wedge(Patch):
+    """Wedge shaped patch."""
+
+    def __str__(self):
+        pars = (self.center[0], self.center[1], self.r,
+                self.theta1, self.theta2, self.width)
+        fmt = "Wedge(center=(%g, %g), r=%g, theta1=%g, theta2=%g, width=%s)"
+        return fmt % pars
+
+    @_docstring.interpd
+    def __init__(self, center, r, theta1, theta2, *, width=None, **kwargs):
+        """
+        A wedge centered at *x*, *y* center with radius *r* that
+        sweeps *theta1* to *theta2* (in degrees).  If *width* is given,
+        then a partial wedge is drawn from inner radius *r* - *width*
+        to outer radius *r*.
+
+        Valid keyword arguments are:
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+        self.center = center
+        self.r, self.width = r, width
+        self.theta1, self.theta2 = theta1, theta2
+        self._patch_transform = transforms.IdentityTransform()
+        self._recompute_path()
+
+    def _recompute_path(self):
+        # Inner and outer rings are connected unless the annulus is complete
+        if abs((self.theta2 - self.theta1) - 360) <= 1e-12:
+            theta1, theta2 = 0, 360
+            connector = Path.MOVETO
+        else:
+            theta1, theta2 = self.theta1, self.theta2
+            connector = Path.LINETO
+
+        # Form the outer ring
+        arc = Path.arc(theta1, theta2)
+
+        if self.width is not None:
+            # Partial annulus needs to draw the outer ring
+            # followed by a reversed and scaled inner ring
+            v1 = arc.vertices
+            v2 = arc.vertices[::-1] * (self.r - self.width) / self.r
+            v = np.concatenate([v1, v2, [(0, 0)]])
+            c = [*arc.codes, connector, *arc.codes[1:], Path.CLOSEPOLY]
+        else:
+            # Wedge doesn't need an inner ring
+            v = np.concatenate([arc.vertices, [(0, 0), (0, 0)]])
+            c = [*arc.codes, connector, Path.CLOSEPOLY]
+
+        # Shift and scale the wedge to the final location.
+        self._path = Path(v * self.r + self.center, c)
+
+    def set_center(self, center):
+        self._path = None
+        self.center = center
+        self.stale = True
+
+    def set_radius(self, radius):
+        self._path = None
+        self.r = radius
+        self.stale = True
+
+    def set_theta1(self, theta1):
+        self._path = None
+        self.theta1 = theta1
+        self.stale = True
+
+    def set_theta2(self, theta2):
+        self._path = None
+        self.theta2 = theta2
+        self.stale = True
+
+    def set_width(self, width):
+        self._path = None
+        self.width = width
+        self.stale = True
+
+    def get_path(self):
+        if self._path is None:
+            self._recompute_path()
+        return self._path
+
+
+# COVERAGE NOTE: Not used internally or from examples
+class Arrow(Patch):
+    """An arrow patch."""
+
+    def __str__(self):
+        return "Arrow()"
+
+    _path = Path._create_closed([
+        [0.0, 0.1], [0.0, -0.1], [0.8, -0.1], [0.8, -0.3], [1.0, 0.0],
+        [0.8, 0.3], [0.8, 0.1]])
+
+    @_docstring.interpd
+    def __init__(self, x, y, dx, dy, *, width=1.0, **kwargs):
+        """
+        Draws an arrow from (*x*, *y*) to (*x* + *dx*, *y* + *dy*).
+        The width of the arrow is scaled by *width*.
+
+        Parameters
+        ----------
+        x : float
+            x coordinate of the arrow tail.
+        y : float
+            y coordinate of the arrow tail.
+        dx : float
+            Arrow length in the x direction.
+        dy : float
+            Arrow length in the y direction.
+        width : float, default: 1
+            Scale factor for the width of the arrow. With a default value of 1,
+            the tail width is 0.2 and head width is 0.6.
+        **kwargs
+            Keyword arguments control the `Patch` properties:
+
+            %(Patch:kwdoc)s
+
+        See Also
+        --------
+        FancyArrow
+            Patch that allows independent control of the head and tail
+            properties.
+        """
+        super().__init__(**kwargs)
+        self.set_data(x, y, dx, dy, width)
+
+    def get_path(self):
+        return self._path
+
+    def get_patch_transform(self):
+        return self._patch_transform
+
+    def set_data(self, x=None, y=None, dx=None, dy=None, width=None):
+        """
+        Set `.Arrow` x, y, dx, dy and width.
+        Values left as None will not be updated.
+
+        Parameters
+        ----------
+        x, y : float or None, default: None
+            The x and y coordinates of the arrow base.
+
+        dx, dy : float or None, default: None
+            The length of the arrow along x and y direction.
+
+        width : float or None, default: None
+            Width of full arrow tail.
+        """
+        if x is not None:
+            self._x = x
+        if y is not None:
+            self._y = y
+        if dx is not None:
+            self._dx = dx
+        if dy is not None:
+            self._dy = dy
+        if width is not None:
+            self._width = width
+        self._patch_transform = (
+            transforms.Affine2D()
+            .scale(np.hypot(self._dx, self._dy), self._width)
+            .rotate(np.arctan2(self._dy, self._dx))
+            .translate(self._x, self._y)
+            .frozen())
+
+
+class FancyArrow(Polygon):
+    """
+    Like Arrow, but lets you set head width and head height independently.
+    """
+
+    _edge_default = True
+
+    def __str__(self):
+        return "FancyArrow()"
+
+    @_docstring.interpd
+    def __init__(self, x, y, dx, dy, *,
+                 width=0.001, length_includes_head=False, head_width=None,
+                 head_length=None, shape='full', overhang=0,
+                 head_starts_at_zero=False, **kwargs):
+        """
+        Parameters
+        ----------
+        x, y : float
+            The x and y coordinates of the arrow base.
+
+        dx, dy : float
+            The length of the arrow along x and y direction.
+
+        width : float, default: 0.001
+            Width of full arrow tail.
+
+        length_includes_head : bool, default: False
+            True if head is to be counted in calculating the length.
+
+        head_width : float or None, default: 3*width
+            Total width of the full arrow head.
+
+        head_length : float or None, default: 1.5*head_width
+            Length of arrow head.
+
+        shape : {'full', 'left', 'right'}, default: 'full'
+            Draw the left-half, right-half, or full arrow.
+
+        overhang : float, default: 0
+            Fraction that the arrow is swept back (0 overhang means
+            triangular shape). Can be negative or greater than one.
+
+        head_starts_at_zero : bool, default: False
+            If True, the head starts being drawn at coordinate 0
+            instead of ending at coordinate 0.
+
+        **kwargs
+            `.Patch` properties:
+
+            %(Patch:kwdoc)s
+        """
+        self._x = x
+        self._y = y
+        self._dx = dx
+        self._dy = dy
+        self._width = width
+        self._length_includes_head = length_includes_head
+        self._head_width = head_width
+        self._head_length = head_length
+        self._shape = shape
+        self._overhang = overhang
+        self._head_starts_at_zero = head_starts_at_zero
+        self._make_verts()
+        super().__init__(self.verts, closed=True, **kwargs)
+
+    def set_data(self, *, x=None, y=None, dx=None, dy=None, width=None,
+                 head_width=None, head_length=None):
+        """
+        Set `.FancyArrow` x, y, dx, dy, width, head_with, and head_length.
+        Values left as None will not be updated.
+
+        Parameters
+        ----------
+        x, y : float or None, default: None
+            The x and y coordinates of the arrow base.
+
+        dx, dy : float or None, default: None
+            The length of the arrow along x and y direction.
+
+        width : float or None, default: None
+            Width of full arrow tail.
+
+        head_width : float or None, default: None
+            Total width of the full arrow head.
+
+        head_length : float or None, default: None
+            Length of arrow head.
+        """
+        if x is not None:
+            self._x = x
+        if y is not None:
+            self._y = y
+        if dx is not None:
+            self._dx = dx
+        if dy is not None:
+            self._dy = dy
+        if width is not None:
+            self._width = width
+        if head_width is not None:
+            self._head_width = head_width
+        if head_length is not None:
+            self._head_length = head_length
+        self._make_verts()
+        self.set_xy(self.verts)
+
+    def _make_verts(self):
+        if self._head_width is None:
+            head_width = 3 * self._width
+        else:
+            head_width = self._head_width
+        if self._head_length is None:
+            head_length = 1.5 * head_width
+        else:
+            head_length = self._head_length
+
+        distance = np.hypot(self._dx, self._dy)
+
+        if self._length_includes_head:
+            length = distance
+        else:
+            length = distance + head_length
+        if not length:
+            self.verts = np.empty([0, 2])  # display nothing if empty
+        else:
+            # start by drawing horizontal arrow, point at (0, 0)
+            hw, hl = head_width, head_length
+            hs, lw = self._overhang, self._width
+            left_half_arrow = np.array([
+                [0.0, 0.0],                 # tip
+                [-hl, -hw / 2],             # leftmost
+                [-hl * (1 - hs), -lw / 2],  # meets stem
+                [-length, -lw / 2],         # bottom left
+                [-length, 0],
+            ])
+            # if we're not including the head, shift up by head length
+            if not self._length_includes_head:
+                left_half_arrow += [head_length, 0]
+            # if the head starts at 0, shift up by another head length
+            if self._head_starts_at_zero:
+                left_half_arrow += [head_length / 2, 0]
+            # figure out the shape, and complete accordingly
+            if self._shape == 'left':
+                coords = left_half_arrow
+            else:
+                right_half_arrow = left_half_arrow * [1, -1]
+                if self._shape == 'right':
+                    coords = right_half_arrow
+                elif self._shape == 'full':
+                    # The half-arrows contain the midpoint of the stem,
+                    # which we can omit from the full arrow. Including it
+                    # twice caused a problem with xpdf.
+                    coords = np.concatenate([left_half_arrow[:-1],
+                                             right_half_arrow[-2::-1]])
+                else:
+                    raise ValueError(f"Got unknown shape: {self._shape!r}")
+            if distance != 0:
+                cx = self._dx / distance
+                sx = self._dy / distance
+            else:
+                # Account for division by zero
+                cx, sx = 0, 1
+            M = [[cx, sx], [-sx, cx]]
+            self.verts = np.dot(coords, M) + [
+                self._x + self._dx,
+                self._y + self._dy,
+            ]
+
+
+_docstring.interpd.register(
+    FancyArrow="\n".join(
+        (inspect.getdoc(FancyArrow.__init__) or "").splitlines()[2:]))
+
+
+class CirclePolygon(RegularPolygon):
+    """A polygon-approximation of a circle patch."""
+
+    def __str__(self):
+        s = "CirclePolygon((%g, %g), radius=%g, resolution=%d)"
+        return s % (self.xy[0], self.xy[1], self.radius, self.numvertices)
+
+    @_docstring.interpd
+    def __init__(self, xy, radius=5, *,
+                 resolution=20,  # the number of vertices
+                 ** kwargs):
+        """
+        Create a circle at *xy* = (*x*, *y*) with given *radius*.
+
+        This circle is approximated by a regular polygon with *resolution*
+        sides.  For a smoother circle drawn with splines, see `Circle`.
+
+        Valid keyword arguments are:
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__(
+            xy, resolution, radius=radius, orientation=0, **kwargs)
+
+
+class Ellipse(Patch):
+    """A scale-free ellipse."""
+
+    def __str__(self):
+        pars = (self._center[0], self._center[1],
+                self.width, self.height, self.angle)
+        fmt = "Ellipse(xy=(%s, %s), width=%s, height=%s, angle=%s)"
+        return fmt % pars
+
+    @_docstring.interpd
+    def __init__(self, xy, width, height, *, angle=0, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+            xy coordinates of ellipse centre.
+        width : float
+            Total length (diameter) of horizontal axis.
+        height : float
+            Total length (diameter) of vertical axis.
+        angle : float, default: 0
+            Rotation in degrees anti-clockwise.
+
+        Notes
+        -----
+        Valid keyword arguments are:
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+
+        self._center = xy
+        self._width, self._height = width, height
+        self._angle = angle
+        self._path = Path.unit_circle()
+        # Required for EllipseSelector with axes aspect ratio != 1
+        # The patch is defined in data coordinates and when changing the
+        # selector with square modifier and not in data coordinates, we need
+        # to correct for the aspect ratio difference between the data and
+        # display coordinate systems.
+        self._aspect_ratio_correction = 1.0
+        # Note: This cannot be calculated until this is added to an Axes
+        self._patch_transform = transforms.IdentityTransform()
+
+    def _recompute_transform(self):
+        """
+        Notes
+        -----
+        This cannot be called until after this has been added to an Axes,
+        otherwise unit conversion will fail. This makes it very important to
+        call the accessor method and not directly access the transformation
+        member variable.
+        """
+        center = (self.convert_xunits(self._center[0]),
+                  self.convert_yunits(self._center[1]))
+        width = self.convert_xunits(self._width)
+        height = self.convert_yunits(self._height)
+        self._patch_transform = transforms.Affine2D() \
+            .scale(width * 0.5, height * 0.5 * self._aspect_ratio_correction) \
+            .rotate_deg(self.angle) \
+            .scale(1, 1 / self._aspect_ratio_correction) \
+            .translate(*center)
+
+    def get_path(self):
+        """Return the path of the ellipse."""
+        return self._path
+
+    def get_patch_transform(self):
+        self._recompute_transform()
+        return self._patch_transform
+
+    def set_center(self, xy):
+        """
+        Set the center of the ellipse.
+
+        Parameters
+        ----------
+        xy : (float, float)
+        """
+        self._center = xy
+        self.stale = True
+
+    def get_center(self):
+        """Return the center of the ellipse."""
+        return self._center
+
+    center = property(get_center, set_center)
+
+    def set_width(self, width):
+        """
+        Set the width of the ellipse.
+
+        Parameters
+        ----------
+        width : float
+        """
+        self._width = width
+        self.stale = True
+
+    def get_width(self):
+        """
+        Return the width of the ellipse.
+        """
+        return self._width
+
+    width = property(get_width, set_width)
+
+    def set_height(self, height):
+        """
+        Set the height of the ellipse.
+
+        Parameters
+        ----------
+        height : float
+        """
+        self._height = height
+        self.stale = True
+
+    def get_height(self):
+        """Return the height of the ellipse."""
+        return self._height
+
+    height = property(get_height, set_height)
+
+    def set_angle(self, angle):
+        """
+        Set the angle of the ellipse.
+
+        Parameters
+        ----------
+        angle : float
+        """
+        self._angle = angle
+        self.stale = True
+
+    def get_angle(self):
+        """Return the angle of the ellipse."""
+        return self._angle
+
+    angle = property(get_angle, set_angle)
+
+    def get_corners(self):
+        """
+        Return the corners of the ellipse bounding box.
+
+        The bounding box orientation is moving anti-clockwise from the
+        lower left corner defined before rotation.
+        """
+        return self.get_patch_transform().transform(
+            [(-1, -1), (1, -1), (1, 1), (-1, 1)])
+
+    def get_vertices(self):
+        """
+        Return the vertices coordinates of the ellipse.
+
+        The definition can be found `here <https://en.wikipedia.org/wiki/Ellipse>`_
+
+        .. versionadded:: 3.8
+        """
+        if self.width < self.height:
+            ret = self.get_patch_transform().transform([(0, 1), (0, -1)])
+        else:
+            ret = self.get_patch_transform().transform([(1, 0), (-1, 0)])
+        return [tuple(x) for x in ret]
+
+    def get_co_vertices(self):
+        """
+        Return the co-vertices coordinates of the ellipse.
+
+        The definition can be found `here <https://en.wikipedia.org/wiki/Ellipse>`_
+
+        .. versionadded:: 3.8
+        """
+        if self.width < self.height:
+            ret = self.get_patch_transform().transform([(1, 0), (-1, 0)])
+        else:
+            ret = self.get_patch_transform().transform([(0, 1), (0, -1)])
+        return [tuple(x) for x in ret]
+
+
+class Annulus(Patch):
+    """
+    An elliptical annulus.
+    """
+
+    @_docstring.interpd
+    def __init__(self, xy, r, width, angle=0.0, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+            xy coordinates of annulus centre.
+        r : float or (float, float)
+            The radius, or semi-axes:
+
+            - If float: radius of the outer circle.
+            - If two floats: semi-major and -minor axes of outer ellipse.
+        width : float
+            Width (thickness) of the annular ring. The width is measured inward
+            from the outer ellipse so that for the inner ellipse the semi-axes
+            are given by ``r - width``. *width* must be less than or equal to
+            the semi-minor axis.
+        angle : float, default: 0
+            Rotation angle in degrees (anti-clockwise from the positive
+            x-axis). Ignored for circular annuli (i.e., if *r* is a scalar).
+        **kwargs
+            Keyword arguments control the `Patch` properties:
+
+            %(Patch:kwdoc)s
+        """
+        super().__init__(**kwargs)
+
+        self.set_radii(r)
+        self.center = xy
+        self.width = width
+        self.angle = angle
+        self._path = None
+
+    def __str__(self):
+        if self.a == self.b:
+            r = self.a
+        else:
+            r = (self.a, self.b)
+
+        return "Annulus(xy=(%s, %s), r=%s, width=%s, angle=%s)" % \
+                (*self.center, r, self.width, self.angle)
+
+    def set_center(self, xy):
+        """
+        Set the center of the annulus.
+
+        Parameters
+        ----------
+        xy : (float, float)
+        """
+        self._center = xy
+        self._path = None
+        self.stale = True
+
+    def get_center(self):
+        """Return the center of the annulus."""
+        return self._center
+
+    center = property(get_center, set_center)
+
+    def set_width(self, width):
+        """
+        Set the width (thickness) of the annulus ring.
+
+        The width is measured inwards from the outer ellipse.
+
+        Parameters
+        ----------
+        width : float
+        """
+        if width > min(self.a, self.b):
+            raise ValueError(
+                'Width of annulus must be less than or equal to semi-minor axis')
+
+        self._width = width
+        self._path = None
+        self.stale = True
+
+    def get_width(self):
+        """Return the width (thickness) of the annulus ring."""
+        return self._width
+
+    width = property(get_width, set_width)
+
+    def set_angle(self, angle):
+        """
+        Set the tilt angle of the annulus.
+
+        Parameters
+        ----------
+        angle : float
+        """
+        self._angle = angle
+        self._path = None
+        self.stale = True
+
+    def get_angle(self):
+        """Return the angle of the annulus."""
+        return self._angle
+
+    angle = property(get_angle, set_angle)
+
+    def set_semimajor(self, a):
+        """
+        Set the semi-major axis *a* of the annulus.
+
+        Parameters
+        ----------
+        a : float
+        """
+        self.a = float(a)
+        self._path = None
+        self.stale = True
+
+    def set_semiminor(self, b):
+        """
+        Set the semi-minor axis *b* of the annulus.
+
+        Parameters
+        ----------
+        b : float
+        """
+        self.b = float(b)
+        self._path = None
+        self.stale = True
+
+    def set_radii(self, r):
+        """
+        Set the semi-major (*a*) and semi-minor radii (*b*) of the annulus.
+
+        Parameters
+        ----------
+        r : float or (float, float)
+            The radius, or semi-axes:
+
+            - If float: radius of the outer circle.
+            - If two floats: semi-major and -minor axes of outer ellipse.
+        """
+        if np.shape(r) == (2,):
+            self.a, self.b = r
+        elif np.shape(r) == ():
+            self.a = self.b = float(r)
+        else:
+            raise ValueError("Parameter 'r' must be one or two floats.")
+
+        self._path = None
+        self.stale = True
+
+    def get_radii(self):
+        """Return the semi-major and semi-minor radii of the annulus."""
+        return self.a, self.b
+
+    radii = property(get_radii, set_radii)
+
+    def _transform_verts(self, verts, a, b):
+        return transforms.Affine2D() \
+            .scale(*self._convert_xy_units((a, b))) \
+            .rotate_deg(self.angle) \
+            .translate(*self._convert_xy_units(self.center)) \
+            .transform(verts)
+
+    def _recompute_path(self):
+        # circular arc
+        arc = Path.arc(0, 360)
+
+        # annulus needs to draw an outer ring
+        # followed by a reversed and scaled inner ring
+        a, b, w = self.a, self.b, self.width
+        v1 = self._transform_verts(arc.vertices, a, b)
+        v2 = self._transform_verts(arc.vertices[::-1], a - w, b - w)
+        v = np.vstack([v1, v2, v1[0, :], (0, 0)])
+        c = np.hstack([arc.codes, Path.MOVETO,
+                       arc.codes[1:], Path.MOVETO,
+                       Path.CLOSEPOLY])
+        self._path = Path(v, c)
+
+    def get_path(self):
+        if self._path is None:
+            self._recompute_path()
+        return self._path
+
+
+class Circle(Ellipse):
+    """
+    A circle patch.
+    """
+    def __str__(self):
+        pars = self.center[0], self.center[1], self.radius
+        fmt = "Circle(xy=(%g, %g), radius=%g)"
+        return fmt % pars
+
+    @_docstring.interpd
+    def __init__(self, xy, radius=5, **kwargs):
+        """
+        Create a true circle at center *xy* = (*x*, *y*) with given *radius*.
+
+        Unlike `CirclePolygon` which is a polygonal approximation, this uses
+        Bezier splines and is much closer to a scale-free circle.
+
+        Valid keyword arguments are:
+
+        %(Patch:kwdoc)s
+        """
+        super().__init__(xy, radius * 2, radius * 2, **kwargs)
+        self.radius = radius
+
+    def set_radius(self, radius):
+        """
+        Set the radius of the circle.
+
+        Parameters
+        ----------
+        radius : float
+        """
+        self.width = self.height = 2 * radius
+        self.stale = True
+
+    def get_radius(self):
+        """Return the radius of the circle."""
+        return self.width / 2.
+
+    radius = property(get_radius, set_radius)
+
+
+class Arc(Ellipse):
+    """
+    An elliptical arc, i.e. a segment of an ellipse.
+
+    Due to internal optimizations, the arc cannot be filled.
+    """
+
+    def __str__(self):
+        pars = (self.center[0], self.center[1], self.width,
+                self.height, self.angle, self.theta1, self.theta2)
+        fmt = ("Arc(xy=(%g, %g), width=%g, "
+               "height=%g, angle=%g, theta1=%g, theta2=%g)")
+        return fmt % pars
+
+    @_docstring.interpd
+    def __init__(self, xy, width, height, *,
+                 angle=0.0, theta1=0.0, theta2=360.0, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+            The center of the ellipse.
+
+        width : float
+            The length of the horizontal axis.
+
+        height : float
+            The length of the vertical axis.
+
+        angle : float
+            Rotation of the ellipse in degrees (counterclockwise).
+
+        theta1, theta2 : float, default: 0, 360
+            Starting and ending angles of the arc in degrees. These values
+            are relative to *angle*, e.g. if *angle* = 45 and *theta1* = 90
+            the absolute starting angle is 135.
+            Default *theta1* = 0, *theta2* = 360, i.e. a complete ellipse.
+            The arc is drawn in the counterclockwise direction.
+            Angles greater than or equal to 360, or smaller than 0, are
+            represented by an equivalent angle in the range [0, 360), by
+            taking the input value mod 360.
+
+        Other Parameters
+        ----------------
+        **kwargs : `~matplotlib.patches.Patch` properties
+            Most `.Patch` properties are supported as keyword arguments,
+            except *fill* and *facecolor* because filling is not supported.
+
+        %(Patch:kwdoc)s
+        """
+        fill = kwargs.setdefault('fill', False)
+        if fill:
+            raise ValueError("Arc objects cannot be filled")
+
+        super().__init__(xy, width, height, angle=angle, **kwargs)
+
+        self.theta1 = theta1
+        self.theta2 = theta2
+        (self._theta1, self._theta2, self._stretched_width,
+         self._stretched_height) = self._theta_stretch()
+        self._path = Path.arc(self._theta1, self._theta2)
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        """
+        Draw the arc to the given *renderer*.
+
+        Notes
+        -----
+        Ellipses are normally drawn using an approximation that uses
+        eight cubic Bezier splines.  The error of this approximation
+        is 1.89818e-6, according to this unverified source:
+
+          Lancaster, Don.  *Approximating a Circle or an Ellipse Using
+          Four Bezier Cubic Splines.*
+
+          https://www.tinaja.com/glib/ellipse4.pdf
+
+        There is a use case where very large ellipses must be drawn
+        with very high accuracy, and it is too expensive to render the
+        entire ellipse with enough segments (either splines or line
+        segments).  Therefore, in the case where either radius of the
+        ellipse is large enough that the error of the spline
+        approximation will be visible (greater than one pixel offset
+        from the ideal), a different technique is used.
+
+        In that case, only the visible parts of the ellipse are drawn,
+        with each visible arc using a fixed number of spline segments
+        (8).  The algorithm proceeds as follows:
+
+        1. The points where the ellipse intersects the axes (or figure)
+           bounding box are located.  (This is done by performing an inverse
+           transformation on the bbox such that it is relative to the unit
+           circle -- this makes the intersection calculation much easier than
+           doing rotated ellipse intersection directly.)
+
+           This uses the "line intersecting a circle" algorithm from:
+
+               Vince, John.  *Geometry for Computer Graphics: Formulae,
+               Examples & Proofs.*  London: Springer-Verlag, 2005.
+
+        2. The angles of each of the intersection points are calculated.
+
+        3. Proceeding counterclockwise starting in the positive
+           x-direction, each of the visible arc-segments between the
+           pairs of vertices are drawn using the Bezier arc
+           approximation technique implemented in `.Path.arc`.
+        """
+        if not self.get_visible():
+            return
+
+        self._recompute_transform()
+
+        self._update_path()
+        # Get width and height in pixels we need to use
+        # `self.get_data_transform` rather than `self.get_transform`
+        # because we want the transform from dataspace to the
+        # screen space to estimate how big the arc will be in physical
+        # units when rendered (the transform that we get via
+        # `self.get_transform()` goes from an idealized unit-radius
+        # space to screen space).
+        data_to_screen_trans = self.get_data_transform()
+        pwidth, pheight = (
+            data_to_screen_trans.transform((self._stretched_width,
+                                            self._stretched_height)) -
+            data_to_screen_trans.transform((0, 0)))
+        inv_error = (1.0 / 1.89818e-6) * 0.5
+
+        if pwidth < inv_error and pheight < inv_error:
+            return Patch.draw(self, renderer)
+
+        def line_circle_intersect(x0, y0, x1, y1):
+            dx = x1 - x0
+            dy = y1 - y0
+            dr2 = dx * dx + dy * dy
+            D = x0 * y1 - x1 * y0
+            D2 = D * D
+            discrim = dr2 - D2
+            if discrim >= 0.0:
+                sign_dy = np.copysign(1, dy)  # +/-1, never 0.
+                sqrt_discrim = np.sqrt(discrim)
+                return np.array(
+                    [[(D * dy + sign_dy * dx * sqrt_discrim) / dr2,
+                      (-D * dx + abs(dy) * sqrt_discrim) / dr2],
+                     [(D * dy - sign_dy * dx * sqrt_discrim) / dr2,
+                      (-D * dx - abs(dy) * sqrt_discrim) / dr2]])
+            else:
+                return np.empty((0, 2))
+
+        def segment_circle_intersect(x0, y0, x1, y1):
+            epsilon = 1e-9
+            if x1 < x0:
+                x0e, x1e = x1, x0
+            else:
+                x0e, x1e = x0, x1
+            if y1 < y0:
+                y0e, y1e = y1, y0
+            else:
+                y0e, y1e = y0, y1
+            xys = line_circle_intersect(x0, y0, x1, y1)
+            xs, ys = xys.T
+            return xys[
+                (x0e - epsilon < xs) & (xs < x1e + epsilon)
+                & (y0e - epsilon < ys) & (ys < y1e + epsilon)
+            ]
+
+        # Transform the Axes (or figure) box_path so that it is relative to
+        # the unit circle in the same way that it is relative to the desired
+        # ellipse.
+        box_path_transform = (
+            transforms.BboxTransformTo((self.axes or self.get_figure(root=False)).bbox)
+            - self.get_transform())
+        box_path = Path.unit_rectangle().transformed(box_path_transform)
+
+        thetas = set()
+        # For each of the point pairs, there is a line segment
+        for p0, p1 in zip(box_path.vertices[:-1], box_path.vertices[1:]):
+            xy = segment_circle_intersect(*p0, *p1)
+            x, y = xy.T
+            # arctan2 return [-pi, pi), the rest of our angles are in
+            # [0, 360], adjust as needed.
+            theta = (np.rad2deg(np.arctan2(y, x)) + 360) % 360
+            thetas.update(
+                theta[(self._theta1 < theta) & (theta < self._theta2)])
+        thetas = sorted(thetas) + [self._theta2]
+        last_theta = self._theta1
+        theta1_rad = np.deg2rad(self._theta1)
+        inside = box_path.contains_point(
+            (np.cos(theta1_rad), np.sin(theta1_rad))
+        )
+
+        # save original path
+        path_original = self._path
+        for theta in thetas:
+            if inside:
+                self._path = Path.arc(last_theta, theta, 8)
+                Patch.draw(self, renderer)
+                inside = False
+            else:
+                inside = True
+            last_theta = theta
+
+        # restore original path
+        self._path = path_original
+
+    def _update_path(self):
+        # Compute new values and update and set new _path if any value changed
+        stretched = self._theta_stretch()
+        if any(a != b for a, b in zip(
+                stretched, (self._theta1, self._theta2, self._stretched_width,
+                            self._stretched_height))):
+            (self._theta1, self._theta2, self._stretched_width,
+             self._stretched_height) = stretched
+            self._path = Path.arc(self._theta1, self._theta2)
+
+    def _theta_stretch(self):
+        # If the width and height of ellipse are not equal, take into account
+        # stretching when calculating angles to draw between
+        def theta_stretch(theta, scale):
+            theta = np.deg2rad(theta)
+            x = np.cos(theta)
+            y = np.sin(theta)
+            stheta = np.rad2deg(np.arctan2(scale * y, x))
+            # arctan2 has the range [-pi, pi], we expect [0, 2*pi]
+            return (stheta + 360) % 360
+
+        width = self.convert_xunits(self.width)
+        height = self.convert_yunits(self.height)
+        if (
+            # if we need to stretch the angles because we are distorted
+            width != height
+            # and we are not doing a full circle.
+            #
+            # 0 and 360 do not exactly round-trip through the angle
+            # stretching (due to both float precision limitations and
+            # the difference between the range of arctan2 [-pi, pi] and
+            # this method [0, 360]) so avoid doing it if we don't have to.
+            and not (self.theta1 != self.theta2 and
+                     self.theta1 % 360 == self.theta2 % 360)
+        ):
+            theta1 = theta_stretch(self.theta1, width / height)
+            theta2 = theta_stretch(self.theta2, width / height)
+            return theta1, theta2, width, height
+        return self.theta1, self.theta2, width, height
+
+
+def bbox_artist(artist, renderer, props=None, fill=True):
+    """
+    A debug function to draw a rectangle around the bounding
+    box returned by an artist's `.Artist.get_window_extent`
+    to test whether the artist is returning the correct bbox.
+
+    *props* is a dict of rectangle props with the additional property
+    'pad' that sets the padding around the bbox in points.
+    """
+    if props is None:
+        props = {}
+    props = props.copy()  # don't want to alter the pad externally
+    pad = props.pop('pad', 4)
+    pad = renderer.points_to_pixels(pad)
+    bbox = artist.get_window_extent(renderer)
+    r = Rectangle(
+        xy=(bbox.x0 - pad / 2, bbox.y0 - pad / 2),
+        width=bbox.width + pad, height=bbox.height + pad,
+        fill=fill, transform=transforms.IdentityTransform(), clip_on=False)
+    r.update(props)
+    r.draw(renderer)
+
+
+def draw_bbox(bbox, renderer, color='k', trans=None):
+    """
+    A debug function to draw a rectangle around the bounding
+    box returned by an artist's `.Artist.get_window_extent`
+    to test whether the artist is returning the correct bbox.
+    """
+    r = Rectangle(xy=bbox.p0, width=bbox.width, height=bbox.height,
+                  edgecolor=color, fill=False, clip_on=False)
+    if trans is not None:
+        r.set_transform(trans)
+    r.draw(renderer)
+
+
+class _Style:
+    """
+    A base class for the Styles. It is meant to be a container class,
+    where actual styles are declared as subclass of it, and it
+    provides some helper functions.
+    """
+
+    def __init_subclass__(cls):
+        # Automatically perform docstring interpolation on the subclasses:
+        # This allows listing the supported styles via
+        # - %(BoxStyle:table)s
+        # - %(ConnectionStyle:table)s
+        # - %(ArrowStyle:table)s
+        # and additionally adding .. ACCEPTS: blocks via
+        # - %(BoxStyle:table_and_accepts)s
+        # - %(ConnectionStyle:table_and_accepts)s
+        # - %(ArrowStyle:table_and_accepts)s
+        _docstring.interpd.register(**{
+            f"{cls.__name__}:table": cls.pprint_styles(),
+            f"{cls.__name__}:table_and_accepts": (
+                cls.pprint_styles()
+                + "\n\n    .. ACCEPTS: ["
+                + "|".join(map(" '{}' ".format, cls._style_list))
+                + "]")
+        })
+
+    def __new__(cls, stylename, **kwargs):
+        """Return the instance of the subclass with the given style name."""
+        # The "class" should have the _style_list attribute, which is a mapping
+        # of style names to style classes.
+        _list = stylename.replace(" ", "").split(",")
+        _name = _list[0].lower()
+        try:
+            _cls = cls._style_list[_name]
+        except KeyError as err:
+            raise ValueError(f"Unknown style: {stylename!r}") from err
+        try:
+            _args_pair = [cs.split("=") for cs in _list[1:]]
+            _args = {k: float(v) for k, v in _args_pair}
+        except ValueError as err:
+            raise ValueError(
+                f"Incorrect style argument: {stylename!r}") from err
+        return _cls(**{**_args, **kwargs})
+
+    @classmethod
+    def get_styles(cls):
+        """Return a dictionary of available styles."""
+        return cls._style_list
+
+    @classmethod
+    def pprint_styles(cls):
+        """Return the available styles as pretty-printed string."""
+        table = [('Class', 'Name', 'Parameters'),
+                 *[(cls.__name__,
+                    # Add backquotes, as - and | have special meaning in reST.
+                    f'``{name}``',
+                    # [1:-1] drops the surrounding parentheses.
+                    str(inspect.signature(cls))[1:-1] or 'None')
+                   for name, cls in cls._style_list.items()]]
+        # Convert to rst table.
+        col_len = [max(len(cell) for cell in column) for column in zip(*table)]
+        table_formatstr = '  '.join('=' * cl for cl in col_len)
+        rst_table = '\n'.join([
+            '',
+            table_formatstr,
+            '  '.join(cell.ljust(cl) for cell, cl in zip(table[0], col_len)),
+            table_formatstr,
+            *['  '.join(cell.ljust(cl) for cell, cl in zip(row, col_len))
+              for row in table[1:]],
+            table_formatstr,
+        ])
+        return textwrap.indent(rst_table, prefix=' ' * 4)
+
+    @classmethod
+    @_api.deprecated(
+        '3.10.0',
+        message="This method is never used internally.",
+        alternative="No replacement.  Please open an issue if you use this."
+    )
+    def register(cls, name, style):
+        """Register a new style."""
+        if not issubclass(style, cls._Base):
+            raise ValueError(f"{style} must be a subclass of {cls._Base}")
+        cls._style_list[name] = style
+
+
+def _register_style(style_list, cls=None, *, name=None):
+    """Class decorator that stashes a class in a (style) dictionary."""
+    if cls is None:
+        return functools.partial(_register_style, style_list, name=name)
+    style_list[name or cls.__name__.lower()] = cls
+    return cls
+
+
+@_docstring.interpd
+class BoxStyle(_Style):
+    """
+    `BoxStyle` is a container class which defines several
+    boxstyle classes, which are used for `FancyBboxPatch`.
+
+    A style object can be created as::
+
+           BoxStyle.Round(pad=0.2)
+
+    or::
+
+           BoxStyle("Round", pad=0.2)
+
+    or::
+
+           BoxStyle("Round, pad=0.2")
+
+    The following boxstyle classes are defined.
+
+    %(BoxStyle:table)s
+
+    An instance of a boxstyle class is a callable object, with the signature ::
+
+       __call__(self, x0, y0, width, height, mutation_size) -> Path
+
+    *x0*, *y0*, *width* and *height* specify the location and size of the box
+    to be drawn; *mutation_size* scales the outline properties such as padding.
+    """
+
+    _style_list = {}
+
+    @_register_style(_style_list)
+    class Square:
+        """A square box."""
+
+        def __init__(self, pad=0.3):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            """
+            self.pad = pad
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            pad = mutation_size * self.pad
+            # width and height with padding added.
+            width, height = width + 2 * pad, height + 2 * pad
+            # boundary of the padded box
+            x0, y0 = x0 - pad, y0 - pad
+            x1, y1 = x0 + width, y0 + height
+            return Path._create_closed(
+                [(x0, y0), (x1, y0), (x1, y1), (x0, y1)])
+
+    @_register_style(_style_list)
+    class Circle:
+        """A circular box."""
+
+        def __init__(self, pad=0.3):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            """
+            self.pad = pad
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            pad = mutation_size * self.pad
+            width, height = width + 2 * pad, height + 2 * pad
+            # boundary of the padded box
+            x0, y0 = x0 - pad, y0 - pad
+            return Path.circle((x0 + width / 2, y0 + height / 2),
+                                max(width, height) / 2)
+
+    @_register_style(_style_list)
+    class Ellipse:
+        """
+        An elliptical box.
+
+        .. versionadded:: 3.7
+        """
+
+        def __init__(self, pad=0.3):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            """
+            self.pad = pad
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            pad = mutation_size * self.pad
+            width, height = width + 2 * pad, height + 2 * pad
+            # boundary of the padded box
+            x0, y0 = x0 - pad, y0 - pad
+            a = width / math.sqrt(2)
+            b = height / math.sqrt(2)
+            trans = Affine2D().scale(a, b).translate(x0 + width / 2,
+                                                     y0 + height / 2)
+            return trans.transform_path(Path.unit_circle())
+
+    @_register_style(_style_list)
+    class LArrow:
+        """A box in the shape of a left-pointing arrow."""
+
+        def __init__(self, pad=0.3):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            """
+            self.pad = pad
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            # padding
+            pad = mutation_size * self.pad
+            # width and height with padding added.
+            width, height = width + 2 * pad, height + 2 * pad
+            # boundary of the padded box
+            x0, y0 = x0 - pad, y0 - pad,
+            x1, y1 = x0 + width, y0 + height
+
+            dx = (y1 - y0) / 2
+            dxx = dx / 2
+            x0 = x0 + pad / 1.4  # adjust by ~sqrt(2)
+
+            return Path._create_closed(
+                [(x0 + dxx, y0), (x1, y0), (x1, y1), (x0 + dxx, y1),
+                 (x0 + dxx, y1 + dxx), (x0 - dx, y0 + dx),
+                 (x0 + dxx, y0 - dxx),  # arrow
+                 (x0 + dxx, y0)])
+
+    @_register_style(_style_list)
+    class RArrow(LArrow):
+        """A box in the shape of a right-pointing arrow."""
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            p = BoxStyle.LArrow.__call__(
+                self, x0, y0, width, height, mutation_size)
+            p.vertices[:, 0] = 2 * x0 + width - p.vertices[:, 0]
+            return p
+
+    @_register_style(_style_list)
+    class DArrow:
+        """A box in the shape of a two-way arrow."""
+        # Modified from LArrow to add a right arrow to the bbox.
+
+        def __init__(self, pad=0.3):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            """
+            self.pad = pad
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            # padding
+            pad = mutation_size * self.pad
+            # width and height with padding added.
+            # The width is padded by the arrows, so we don't need to pad it.
+            height = height + 2 * pad
+            # boundary of the padded box
+            x0, y0 = x0 - pad, y0 - pad
+            x1, y1 = x0 + width, y0 + height
+
+            dx = (y1 - y0) / 2
+            dxx = dx / 2
+            x0 = x0 + pad / 1.4  # adjust by ~sqrt(2)
+
+            return Path._create_closed([
+                (x0 + dxx, y0), (x1, y0),  # bot-segment
+                (x1, y0 - dxx), (x1 + dx + dxx, y0 + dx),
+                (x1, y1 + dxx),  # right-arrow
+                (x1, y1), (x0 + dxx, y1),  # top-segment
+                (x0 + dxx, y1 + dxx), (x0 - dx, y0 + dx),
+                (x0 + dxx, y0 - dxx),  # left-arrow
+                (x0 + dxx, y0)])
+
+    @_register_style(_style_list)
+    class Round:
+        """A box with round corners."""
+
+        def __init__(self, pad=0.3, rounding_size=None):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            rounding_size : float, default: *pad*
+                Radius of the corners.
+            """
+            self.pad = pad
+            self.rounding_size = rounding_size
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+
+            # padding
+            pad = mutation_size * self.pad
+
+            # size of the rounding corner
+            if self.rounding_size:
+                dr = mutation_size * self.rounding_size
+            else:
+                dr = pad
+
+            width, height = width + 2 * pad, height + 2 * pad
+
+            x0, y0 = x0 - pad, y0 - pad,
+            x1, y1 = x0 + width, y0 + height
+
+            # Round corners are implemented as quadratic Bezier, e.g.,
+            # [(x0, y0-dr), (x0, y0), (x0+dr, y0)] for lower left corner.
+            cp = [(x0 + dr, y0),
+                  (x1 - dr, y0),
+                  (x1, y0), (x1, y0 + dr),
+                  (x1, y1 - dr),
+                  (x1, y1), (x1 - dr, y1),
+                  (x0 + dr, y1),
+                  (x0, y1), (x0, y1 - dr),
+                  (x0, y0 + dr),
+                  (x0, y0), (x0 + dr, y0),
+                  (x0 + dr, y0)]
+
+            com = [Path.MOVETO,
+                   Path.LINETO,
+                   Path.CURVE3, Path.CURVE3,
+                   Path.LINETO,
+                   Path.CURVE3, Path.CURVE3,
+                   Path.LINETO,
+                   Path.CURVE3, Path.CURVE3,
+                   Path.LINETO,
+                   Path.CURVE3, Path.CURVE3,
+                   Path.CLOSEPOLY]
+
+            return Path(cp, com)
+
+    @_register_style(_style_list)
+    class Round4:
+        """A box with rounded edges."""
+
+        def __init__(self, pad=0.3, rounding_size=None):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            rounding_size : float, default: *pad*/2
+                Rounding of edges.
+            """
+            self.pad = pad
+            self.rounding_size = rounding_size
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+
+            # padding
+            pad = mutation_size * self.pad
+
+            # Rounding size; defaults to half of the padding.
+            if self.rounding_size:
+                dr = mutation_size * self.rounding_size
+            else:
+                dr = pad / 2.
+
+            width = width + 2 * pad - 2 * dr
+            height = height + 2 * pad - 2 * dr
+
+            x0, y0 = x0 - pad + dr, y0 - pad + dr,
+            x1, y1 = x0 + width, y0 + height
+
+            cp = [(x0, y0),
+                  (x0 + dr, y0 - dr), (x1 - dr, y0 - dr), (x1, y0),
+                  (x1 + dr, y0 + dr), (x1 + dr, y1 - dr), (x1, y1),
+                  (x1 - dr, y1 + dr), (x0 + dr, y1 + dr), (x0, y1),
+                  (x0 - dr, y1 - dr), (x0 - dr, y0 + dr), (x0, y0),
+                  (x0, y0)]
+
+            com = [Path.MOVETO,
+                   Path.CURVE4, Path.CURVE4, Path.CURVE4,
+                   Path.CURVE4, Path.CURVE4, Path.CURVE4,
+                   Path.CURVE4, Path.CURVE4, Path.CURVE4,
+                   Path.CURVE4, Path.CURVE4, Path.CURVE4,
+                   Path.CLOSEPOLY]
+
+            return Path(cp, com)
+
+    @_register_style(_style_list)
+    class Sawtooth:
+        """A box with a sawtooth outline."""
+
+        def __init__(self, pad=0.3, tooth_size=None):
+            """
+            Parameters
+            ----------
+            pad : float, default: 0.3
+                The amount of padding around the original box.
+            tooth_size : float, default: *pad*/2
+                Size of the sawtooth.
+            """
+            self.pad = pad
+            self.tooth_size = tooth_size
+
+        def _get_sawtooth_vertices(self, x0, y0, width, height, mutation_size):
+
+            # padding
+            pad = mutation_size * self.pad
+
+            # size of sawtooth
+            if self.tooth_size is None:
+                tooth_size = self.pad * .5 * mutation_size
+            else:
+                tooth_size = self.tooth_size * mutation_size
+
+            hsz = tooth_size / 2
+            width = width + 2 * pad - tooth_size
+            height = height + 2 * pad - tooth_size
+
+            # the sizes of the vertical and horizontal sawtooth are
+            # separately adjusted to fit the given box size.
+            dsx_n = round((width - tooth_size) / (tooth_size * 2)) * 2
+            dsy_n = round((height - tooth_size) / (tooth_size * 2)) * 2
+
+            x0, y0 = x0 - pad + hsz, y0 - pad + hsz
+            x1, y1 = x0 + width, y0 + height
+
+            xs = [
+                x0, *np.linspace(x0 + hsz, x1 - hsz, 2 * dsx_n + 1),  # bottom
+                *([x1, x1 + hsz, x1, x1 - hsz] * dsy_n)[:2*dsy_n+2],  # right
+                x1, *np.linspace(x1 - hsz, x0 + hsz, 2 * dsx_n + 1),  # top
+                *([x0, x0 - hsz, x0, x0 + hsz] * dsy_n)[:2*dsy_n+2],  # left
+            ]
+            ys = [
+                *([y0, y0 - hsz, y0, y0 + hsz] * dsx_n)[:2*dsx_n+2],  # bottom
+                y0, *np.linspace(y0 + hsz, y1 - hsz, 2 * dsy_n + 1),  # right
+                *([y1, y1 + hsz, y1, y1 - hsz] * dsx_n)[:2*dsx_n+2],  # top
+                y1, *np.linspace(y1 - hsz, y0 + hsz, 2 * dsy_n + 1),  # left
+            ]
+
+            return [*zip(xs, ys), (xs[0], ys[0])]
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            saw_vertices = self._get_sawtooth_vertices(x0, y0, width,
+                                                       height, mutation_size)
+            return Path(saw_vertices, closed=True)
+
+    @_register_style(_style_list)
+    class Roundtooth(Sawtooth):
+        """A box with a rounded sawtooth outline."""
+
+        def __call__(self, x0, y0, width, height, mutation_size):
+            saw_vertices = self._get_sawtooth_vertices(x0, y0,
+                                                       width, height,
+                                                       mutation_size)
+            # Add a trailing vertex to allow us to close the polygon correctly
+            saw_vertices = np.concatenate([saw_vertices, [saw_vertices[0]]])
+            codes = ([Path.MOVETO] +
+                     [Path.CURVE3, Path.CURVE3] * ((len(saw_vertices)-1)//2) +
+                     [Path.CLOSEPOLY])
+            return Path(saw_vertices, codes)
+
+
+@_docstring.interpd
+class ConnectionStyle(_Style):
+    """
+    `ConnectionStyle` is a container class which defines
+    several connectionstyle classes, which is used to create a path
+    between two points.  These are mainly used with `FancyArrowPatch`.
+
+    A connectionstyle object can be either created as::
+
+           ConnectionStyle.Arc3(rad=0.2)
+
+    or::
+
+           ConnectionStyle("Arc3", rad=0.2)
+
+    or::
+
+           ConnectionStyle("Arc3, rad=0.2")
+
+    The following classes are defined
+
+    %(ConnectionStyle:table)s
+
+    An instance of any connection style class is a callable object,
+    whose call signature is::
+
+        __call__(self, posA, posB,
+                 patchA=None, patchB=None,
+                 shrinkA=2., shrinkB=2.)
+
+    and it returns a `.Path` instance. *posA* and *posB* are
+    tuples of (x, y) coordinates of the two points to be
+    connected. *patchA* (or *patchB*) is given, the returned path is
+    clipped so that it start (or end) from the boundary of the
+    patch. The path is further shrunk by *shrinkA* (or *shrinkB*)
+    which is given in points.
+    """
+
+    _style_list = {}
+
+    class _Base:
+        """
+        A base class for connectionstyle classes. The subclass needs
+        to implement a *connect* method whose call signature is::
+
+          connect(posA, posB)
+
+        where posA and posB are tuples of x, y coordinates to be
+        connected.  The method needs to return a path connecting two
+        points. This base class defines a __call__ method, and a few
+        helper methods.
+        """
+        def _in_patch(self, patch):
+            """
+            Return a predicate function testing whether a point *xy* is
+            contained in *patch*.
+            """
+            return lambda xy: patch.contains(
+                SimpleNamespace(x=xy[0], y=xy[1]))[0]
+
+        def _clip(self, path, in_start, in_stop):
+            """
+            Clip *path* at its start by the region where *in_start* returns
+            True, and at its stop by the region where *in_stop* returns True.
+
+            The original path is assumed to start in the *in_start* region and
+            to stop in the *in_stop* region.
+            """
+            if in_start:
+                try:
+                    _, path = split_path_inout(path, in_start)
+                except ValueError:
+                    pass
+            if in_stop:
+                try:
+                    path, _ = split_path_inout(path, in_stop)
+                except ValueError:
+                    pass
+            return path
+
+        def __call__(self, posA, posB,
+                     shrinkA=2., shrinkB=2., patchA=None, patchB=None):
+            """
+            Call the *connect* method to create a path between *posA* and
+            *posB*; then clip and shrink the path.
+            """
+            path = self.connect(posA, posB)
+            path = self._clip(
+                path,
+                self._in_patch(patchA) if patchA else None,
+                self._in_patch(patchB) if patchB else None,
+            )
+            path = self._clip(
+                path,
+                inside_circle(*path.vertices[0], shrinkA) if shrinkA else None,
+                inside_circle(*path.vertices[-1], shrinkB) if shrinkB else None
+            )
+            return path
+
+    @_register_style(_style_list)
+    class Arc3(_Base):
+        """
+        Creates a simple quadratic Bézier curve between two
+        points. The curve is created so that the middle control point
+        (C1) is located at the same distance from the start (C0) and
+        end points(C2) and the distance of the C1 to the line
+        connecting C0-C2 is *rad* times the distance of C0-C2.
+        """
+
+        def __init__(self, rad=0.):
+            """
+            Parameters
+            ----------
+            rad : float
+              Curvature of the curve.
+            """
+            self.rad = rad
+
+        def connect(self, posA, posB):
+            x1, y1 = posA
+            x2, y2 = posB
+            x12, y12 = (x1 + x2) / 2., (y1 + y2) / 2.
+            dx, dy = x2 - x1, y2 - y1
+
+            f = self.rad
+
+            cx, cy = x12 + f * dy, y12 - f * dx
+
+            vertices = [(x1, y1),
+                        (cx, cy),
+                        (x2, y2)]
+            codes = [Path.MOVETO,
+                     Path.CURVE3,
+                     Path.CURVE3]
+
+            return Path(vertices, codes)
+
+    @_register_style(_style_list)
+    class Angle3(_Base):
+        """
+        Creates a simple quadratic Bézier curve between two points. The middle
+        control point is placed at the intersecting point of two lines which
+        cross the start and end point, and have a slope of *angleA* and
+        *angleB*, respectively.
+        """
+
+        def __init__(self, angleA=90, angleB=0):
+            """
+            Parameters
+            ----------
+            angleA : float
+              Starting angle of the path.
+
+            angleB : float
+              Ending angle of the path.
+            """
+
+            self.angleA = angleA
+            self.angleB = angleB
+
+        def connect(self, posA, posB):
+            x1, y1 = posA
+            x2, y2 = posB
+
+            cosA = math.cos(math.radians(self.angleA))
+            sinA = math.sin(math.radians(self.angleA))
+            cosB = math.cos(math.radians(self.angleB))
+            sinB = math.sin(math.radians(self.angleB))
+
+            cx, cy = get_intersection(x1, y1, cosA, sinA,
+                                      x2, y2, cosB, sinB)
+
+            vertices = [(x1, y1), (cx, cy), (x2, y2)]
+            codes = [Path.MOVETO, Path.CURVE3, Path.CURVE3]
+
+            return Path(vertices, codes)
+
+    @_register_style(_style_list)
+    class Angle(_Base):
+        """
+        Creates a piecewise continuous quadratic Bézier path between two
+        points. The path has a one passing-through point placed at the
+        intersecting point of two lines which cross the start and end point,
+        and have a slope of *angleA* and *angleB*, respectively.
+        The connecting edges are rounded with *rad*.
+        """
+
+        def __init__(self, angleA=90, angleB=0, rad=0.):
+            """
+            Parameters
+            ----------
+            angleA : float
+              Starting angle of the path.
+
+            angleB : float
+              Ending angle of the path.
+
+            rad : float
+              Rounding radius of the edge.
+            """
+
+            self.angleA = angleA
+            self.angleB = angleB
+
+            self.rad = rad
+
+        def connect(self, posA, posB):
+            x1, y1 = posA
+            x2, y2 = posB
+
+            cosA = math.cos(math.radians(self.angleA))
+            sinA = math.sin(math.radians(self.angleA))
+            cosB = math.cos(math.radians(self.angleB))
+            sinB = math.sin(math.radians(self.angleB))
+
+            cx, cy = get_intersection(x1, y1, cosA, sinA,
+                                      x2, y2, cosB, sinB)
+
+            vertices = [(x1, y1)]
+            codes = [Path.MOVETO]
+
+            if self.rad == 0.:
+                vertices.append((cx, cy))
+                codes.append(Path.LINETO)
+            else:
+                dx1, dy1 = x1 - cx, y1 - cy
+                d1 = np.hypot(dx1, dy1)
+                f1 = self.rad / d1
+                dx2, dy2 = x2 - cx, y2 - cy
+                d2 = np.hypot(dx2, dy2)
+                f2 = self.rad / d2
+                vertices.extend([(cx + dx1 * f1, cy + dy1 * f1),
+                                 (cx, cy),
+                                 (cx + dx2 * f2, cy + dy2 * f2)])
+                codes.extend([Path.LINETO, Path.CURVE3, Path.CURVE3])
+
+            vertices.append((x2, y2))
+            codes.append(Path.LINETO)
+
+            return Path(vertices, codes)
+
+    @_register_style(_style_list)
+    class Arc(_Base):
+        """
+        Creates a piecewise continuous quadratic Bézier path between two
+        points. The path can have two passing-through points, a
+        point placed at the distance of *armA* and angle of *angleA* from
+        point A, another point with respect to point B. The edges are
+        rounded with *rad*.
+        """
+
+        def __init__(self, angleA=0, angleB=0, armA=None, armB=None, rad=0.):
+            """
+            Parameters
+            ----------
+            angleA : float
+              Starting angle of the path.
+
+            angleB : float
+              Ending angle of the path.
+
+            armA : float or None
+              Length of the starting arm.
+
+            armB : float or None
+              Length of the ending arm.
+
+            rad : float
+              Rounding radius of the edges.
+            """
+
+            self.angleA = angleA
+            self.angleB = angleB
+            self.armA = armA
+            self.armB = armB
+
+            self.rad = rad
+
+        def connect(self, posA, posB):
+            x1, y1 = posA
+            x2, y2 = posB
+
+            vertices = [(x1, y1)]
+            rounded = []
+            codes = [Path.MOVETO]
+
+            if self.armA:
+                cosA = math.cos(math.radians(self.angleA))
+                sinA = math.sin(math.radians(self.angleA))
+                # x_armA, y_armB
+                d = self.armA - self.rad
+                rounded.append((x1 + d * cosA, y1 + d * sinA))
+                d = self.armA
+                rounded.append((x1 + d * cosA, y1 + d * sinA))
+
+            if self.armB:
+                cosB = math.cos(math.radians(self.angleB))
+                sinB = math.sin(math.radians(self.angleB))
+                x_armB, y_armB = x2 + self.armB * cosB, y2 + self.armB * sinB
+
+                if rounded:
+                    xp, yp = rounded[-1]
+                    dx, dy = x_armB - xp, y_armB - yp
+                    dd = (dx * dx + dy * dy) ** .5
+
+                    rounded.append((xp + self.rad * dx / dd,
+                                    yp + self.rad * dy / dd))
+                    vertices.extend(rounded)
+                    codes.extend([Path.LINETO,
+                                  Path.CURVE3,
+                                  Path.CURVE3])
+                else:
+                    xp, yp = vertices[-1]
+                    dx, dy = x_armB - xp, y_armB - yp
+                    dd = (dx * dx + dy * dy) ** .5
+
+                d = dd - self.rad
+                rounded = [(xp + d * dx / dd, yp + d * dy / dd),
+                           (x_armB, y_armB)]
+
+            if rounded:
+                xp, yp = rounded[-1]
+                dx, dy = x2 - xp, y2 - yp
+                dd = (dx * dx + dy * dy) ** .5
+
+                rounded.append((xp + self.rad * dx / dd,
+                                yp + self.rad * dy / dd))
+                vertices.extend(rounded)
+                codes.extend([Path.LINETO,
+                              Path.CURVE3,
+                              Path.CURVE3])
+
+            vertices.append((x2, y2))
+            codes.append(Path.LINETO)
+
+            return Path(vertices, codes)
+
+    @_register_style(_style_list)
+    class Bar(_Base):
+        """
+        A line with *angle* between A and B with *armA* and *armB*. One of the
+        arms is extended so that they are connected in a right angle. The
+        length of *armA* is determined by (*armA* + *fraction* x AB distance).
+        Same for *armB*.
+        """
+
+        def __init__(self, armA=0., armB=0., fraction=0.3, angle=None):
+            """
+            Parameters
+            ----------
+            armA : float
+                Minimum length of armA.
+
+            armB : float
+                Minimum length of armB.
+
+            fraction : float
+                A fraction of the distance between two points that will be
+                added to armA and armB.
+
+            angle : float or None
+                Angle of the connecting line (if None, parallel to A and B).
+            """
+            self.armA = armA
+            self.armB = armB
+            self.fraction = fraction
+            self.angle = angle
+
+        def connect(self, posA, posB):
+            x1, y1 = posA
+            x20, y20 = x2, y2 = posB
+
+            theta1 = math.atan2(y2 - y1, x2 - x1)
+            dx, dy = x2 - x1, y2 - y1
+            dd = (dx * dx + dy * dy) ** .5
+            ddx, ddy = dx / dd, dy / dd
+
+            armA, armB = self.armA, self.armB
+
+            if self.angle is not None:
+                theta0 = np.deg2rad(self.angle)
+                dtheta = theta1 - theta0
+                dl = dd * math.sin(dtheta)
+                dL = dd * math.cos(dtheta)
+                x2, y2 = x1 + dL * math.cos(theta0), y1 + dL * math.sin(theta0)
+                armB = armB - dl
+
+                # update
+                dx, dy = x2 - x1, y2 - y1
+                dd2 = (dx * dx + dy * dy) ** .5
+                ddx, ddy = dx / dd2, dy / dd2
+
+            arm = max(armA, armB)
+            f = self.fraction * dd + arm
+
+            cx1, cy1 = x1 + f * ddy, y1 - f * ddx
+            cx2, cy2 = x2 + f * ddy, y2 - f * ddx
+
+            vertices = [(x1, y1),
+                        (cx1, cy1),
+                        (cx2, cy2),
+                        (x20, y20)]
+            codes = [Path.MOVETO,
+                     Path.LINETO,
+                     Path.LINETO,
+                     Path.LINETO]
+
+            return Path(vertices, codes)
+
+
+def _point_along_a_line(x0, y0, x1, y1, d):
+    """
+    Return the point on the line connecting (*x0*, *y0*) -- (*x1*, *y1*) whose
+    distance from (*x0*, *y0*) is *d*.
+    """
+    dx, dy = x0 - x1, y0 - y1
+    ff = d / (dx * dx + dy * dy) ** .5
+    x2, y2 = x0 - ff * dx, y0 - ff * dy
+
+    return x2, y2
+
+
+@_docstring.interpd
+class ArrowStyle(_Style):
+    """
+    `ArrowStyle` is a container class which defines several
+    arrowstyle classes, which is used to create an arrow path along a
+    given path.  These are mainly used with `FancyArrowPatch`.
+
+    An arrowstyle object can be either created as::
+
+           ArrowStyle.Fancy(head_length=.4, head_width=.4, tail_width=.4)
+
+    or::
+
+           ArrowStyle("Fancy", head_length=.4, head_width=.4, tail_width=.4)
+
+    or::
+
+           ArrowStyle("Fancy, head_length=.4, head_width=.4, tail_width=.4")
+
+    The following classes are defined
+
+    %(ArrowStyle:table)s
+
+    For an overview of the visual appearance, see
+    :doc:`/gallery/text_labels_and_annotations/fancyarrow_demo`.
+
+    An instance of any arrow style class is a callable object,
+    whose call signature is::
+
+        __call__(self, path, mutation_size, linewidth, aspect_ratio=1.)
+
+    and it returns a tuple of a `.Path` instance and a boolean
+    value. *path* is a `.Path` instance along which the arrow
+    will be drawn. *mutation_size* and *aspect_ratio* have the same
+    meaning as in `BoxStyle`. *linewidth* is a line width to be
+    stroked. This is meant to be used to correct the location of the
+    head so that it does not overshoot the destination point, but not all
+    classes support it.
+
+    Notes
+    -----
+    *angleA* and *angleB* specify the orientation of the bracket, as either a
+    clockwise or counterclockwise angle depending on the arrow type. 0 degrees
+    means perpendicular to the line connecting the arrow's head and tail.
+
+    .. plot:: gallery/text_labels_and_annotations/angles_on_bracket_arrows.py
+    """
+
+    _style_list = {}
+
+    class _Base:
+        """
+        Arrow Transmuter Base class
+
+        ArrowTransmuterBase and its derivatives are used to make a fancy
+        arrow around a given path. The __call__ method returns a path
+        (which will be used to create a PathPatch instance) and a boolean
+        value indicating the path is open therefore is not fillable.  This
+        class is not an artist and actual drawing of the fancy arrow is
+        done by the FancyArrowPatch class.
+        """
+
+        # The derived classes are required to be able to be initialized
+        # w/o arguments, i.e., all its argument (except self) must have
+        # the default values.
+
+        @staticmethod
+        def ensure_quadratic_bezier(path):
+            """
+            Some ArrowStyle classes only works with a simple quadratic
+            Bézier curve (created with `.ConnectionStyle.Arc3` or
+            `.ConnectionStyle.Angle3`). This static method checks if the
+            provided path is a simple quadratic Bézier curve and returns its
+            control points if true.
+            """
+            segments = list(path.iter_segments())
+            if (len(segments) != 2 or segments[0][1] != Path.MOVETO or
+                    segments[1][1] != Path.CURVE3):
+                raise ValueError(
+                    "'path' is not a valid quadratic Bezier curve")
+            return [*segments[0][0], *segments[1][0]]
+
+        def transmute(self, path, mutation_size, linewidth):
+            """
+            The transmute method is the very core of the ArrowStyle class and
+            must be overridden in the subclasses. It receives the *path*
+            object along which the arrow will be drawn, and the
+            *mutation_size*, with which the arrow head etc. will be scaled.
+            The *linewidth* may be used to adjust the path so that it does not
+            pass beyond the given points. It returns a tuple of a `.Path`
+            instance and a boolean. The boolean value indicate whether the
+            path can be filled or not. The return value can also be a list of
+            paths and list of booleans of the same length.
+            """
+            raise NotImplementedError('Derived must override')
+
+        def __call__(self, path, mutation_size, linewidth,
+                     aspect_ratio=1.):
+            """
+            The __call__ method is a thin wrapper around the transmute method
+            and takes care of the aspect ratio.
+            """
+
+            if aspect_ratio is not None:
+                # Squeeze the given height by the aspect_ratio
+                vertices = path.vertices / [1, aspect_ratio]
+                path_shrunk = Path(vertices, path.codes)
+                # call transmute method with squeezed height.
+                path_mutated, fillable = self.transmute(path_shrunk,
+                                                        mutation_size,
+                                                        linewidth)
+                if np.iterable(fillable):
+                    # Restore the height
+                    path_list = [Path(p.vertices * [1, aspect_ratio], p.codes)
+                                 for p in path_mutated]
+                    return path_list, fillable
+                else:
+                    return path_mutated, fillable
+            else:
+                return self.transmute(path, mutation_size, linewidth)
+
+    class _Curve(_Base):
+        """
+        A simple arrow which will work with any path instance. The
+        returned path is the concatenation of the original path, and at
+        most two paths representing the arrow head or bracket at the start
+        point and at the end point. The arrow heads can be either open
+        or closed.
+        """
+
+        arrow = "-"
+        fillbegin = fillend = False  # Whether arrows are filled.
+
+        def __init__(self, head_length=.4, head_width=.2, widthA=1., widthB=1.,
+                     lengthA=0.2, lengthB=0.2, angleA=0, angleB=0, scaleA=None,
+                     scaleB=None):
+            """
+            Parameters
+            ----------
+            head_length : float, default: 0.4
+                Length of the arrow head, relative to *mutation_size*.
+            head_width : float, default: 0.2
+                Width of the arrow head, relative to *mutation_size*.
+            widthA, widthB : float, default: 1.0
+                Width of the bracket.
+            lengthA, lengthB : float, default: 0.2
+                Length of the bracket.
+            angleA, angleB : float, default: 0
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            scaleA, scaleB : float, default: *mutation_size*
+                The scale of the brackets.
+            """
+
+            self.head_length, self.head_width = head_length, head_width
+            self.widthA, self.widthB = widthA, widthB
+            self.lengthA, self.lengthB = lengthA, lengthB
+            self.angleA, self.angleB = angleA, angleB
+            self.scaleA, self.scaleB = scaleA, scaleB
+
+            self._beginarrow_head = False
+            self._beginarrow_bracket = False
+            self._endarrow_head = False
+            self._endarrow_bracket = False
+
+            if "-" not in self.arrow:
+                raise ValueError("arrow must have the '-' between "
+                                 "the two heads")
+
+            beginarrow, endarrow = self.arrow.split("-", 1)
+
+            if beginarrow == "<":
+                self._beginarrow_head = True
+                self._beginarrow_bracket = False
+            elif beginarrow == "<|":
+                self._beginarrow_head = True
+                self._beginarrow_bracket = False
+                self.fillbegin = True
+            elif beginarrow in ("]", "|"):
+                self._beginarrow_head = False
+                self._beginarrow_bracket = True
+
+            if endarrow == ">":
+                self._endarrow_head = True
+                self._endarrow_bracket = False
+            elif endarrow == "|>":
+                self._endarrow_head = True
+                self._endarrow_bracket = False
+                self.fillend = True
+            elif endarrow in ("[", "|"):
+                self._endarrow_head = False
+                self._endarrow_bracket = True
+
+            super().__init__()
+
+        def _get_arrow_wedge(self, x0, y0, x1, y1,
+                             head_dist, cos_t, sin_t, linewidth):
+            """
+            Return the paths for arrow heads. Since arrow lines are
+            drawn with capstyle=projected, The arrow goes beyond the
+            desired point. This method also returns the amount of the path
+            to be shrunken so that it does not overshoot.
+            """
+
+            # arrow from x0, y0 to x1, y1
+            dx, dy = x0 - x1, y0 - y1
+
+            cp_distance = np.hypot(dx, dy)
+
+            # pad_projected : amount of pad to account the
+            # overshooting of the projection of the wedge
+            pad_projected = (.5 * linewidth / sin_t)
+
+            # Account for division by zero
+            if cp_distance == 0:
+                cp_distance = 1
+
+            # apply pad for projected edge
+            ddx = pad_projected * dx / cp_distance
+            ddy = pad_projected * dy / cp_distance
+
+            # offset for arrow wedge
+            dx = dx / cp_distance * head_dist
+            dy = dy / cp_distance * head_dist
+
+            dx1, dy1 = cos_t * dx + sin_t * dy, -sin_t * dx + cos_t * dy
+            dx2, dy2 = cos_t * dx - sin_t * dy, sin_t * dx + cos_t * dy
+
+            vertices_arrow = [(x1 + ddx + dx1, y1 + ddy + dy1),
+                              (x1 + ddx, y1 + ddy),
+                              (x1 + ddx + dx2, y1 + ddy + dy2)]
+            codes_arrow = [Path.MOVETO,
+                           Path.LINETO,
+                           Path.LINETO]
+
+            return vertices_arrow, codes_arrow, ddx, ddy
+
+        def _get_bracket(self, x0, y0,
+                         x1, y1, width, length, angle):
+
+            cos_t, sin_t = get_cos_sin(x1, y1, x0, y0)
+
+            # arrow from x0, y0 to x1, y1
+            from matplotlib.bezier import get_normal_points
+            x1, y1, x2, y2 = get_normal_points(x0, y0, cos_t, sin_t, width)
+
+            dx, dy = length * cos_t, length * sin_t
+
+            vertices_arrow = [(x1 + dx, y1 + dy),
+                              (x1, y1),
+                              (x2, y2),
+                              (x2 + dx, y2 + dy)]
+            codes_arrow = [Path.MOVETO,
+                           Path.LINETO,
+                           Path.LINETO,
+                           Path.LINETO]
+
+            if angle:
+                trans = transforms.Affine2D().rotate_deg_around(x0, y0, angle)
+                vertices_arrow = trans.transform(vertices_arrow)
+
+            return vertices_arrow, codes_arrow
+
+        def transmute(self, path, mutation_size, linewidth):
+            # docstring inherited
+            if self._beginarrow_head or self._endarrow_head:
+                head_length = self.head_length * mutation_size
+                head_width = self.head_width * mutation_size
+                head_dist = np.hypot(head_length, head_width)
+                cos_t, sin_t = head_length / head_dist, head_width / head_dist
+
+            scaleA = mutation_size if self.scaleA is None else self.scaleA
+            scaleB = mutation_size if self.scaleB is None else self.scaleB
+
+            # begin arrow
+            x0, y0 = path.vertices[0]
+            x1, y1 = path.vertices[1]
+
+            # If there is no room for an arrow and a line, then skip the arrow
+            has_begin_arrow = self._beginarrow_head and (x0, y0) != (x1, y1)
+            verticesA, codesA, ddxA, ddyA = (
+                self._get_arrow_wedge(x1, y1, x0, y0,
+                                      head_dist, cos_t, sin_t, linewidth)
+                if has_begin_arrow
+                else ([], [], 0, 0)
+            )
+
+            # end arrow
+            x2, y2 = path.vertices[-2]
+            x3, y3 = path.vertices[-1]
+
+            # If there is no room for an arrow and a line, then skip the arrow
+            has_end_arrow = self._endarrow_head and (x2, y2) != (x3, y3)
+            verticesB, codesB, ddxB, ddyB = (
+                self._get_arrow_wedge(x2, y2, x3, y3,
+                                      head_dist, cos_t, sin_t, linewidth)
+                if has_end_arrow
+                else ([], [], 0, 0)
+            )
+
+            # This simple code will not work if ddx, ddy is greater than the
+            # separation between vertices.
+            paths = [Path(np.concatenate([[(x0 + ddxA, y0 + ddyA)],
+                                          path.vertices[1:-1],
+                                          [(x3 + ddxB, y3 + ddyB)]]),
+                          path.codes)]
+            fills = [False]
+
+            if has_begin_arrow:
+                if self.fillbegin:
+                    paths.append(
+                        Path([*verticesA, (0, 0)], [*codesA, Path.CLOSEPOLY]))
+                    fills.append(True)
+                else:
+                    paths.append(Path(verticesA, codesA))
+                    fills.append(False)
+            elif self._beginarrow_bracket:
+                x0, y0 = path.vertices[0]
+                x1, y1 = path.vertices[1]
+                verticesA, codesA = self._get_bracket(x0, y0, x1, y1,
+                                                      self.widthA * scaleA,
+                                                      self.lengthA * scaleA,
+                                                      self.angleA)
+
+                paths.append(Path(verticesA, codesA))
+                fills.append(False)
+
+            if has_end_arrow:
+                if self.fillend:
+                    fills.append(True)
+                    paths.append(
+                        Path([*verticesB, (0, 0)], [*codesB, Path.CLOSEPOLY]))
+                else:
+                    fills.append(False)
+                    paths.append(Path(verticesB, codesB))
+            elif self._endarrow_bracket:
+                x0, y0 = path.vertices[-1]
+                x1, y1 = path.vertices[-2]
+                verticesB, codesB = self._get_bracket(x0, y0, x1, y1,
+                                                      self.widthB * scaleB,
+                                                      self.lengthB * scaleB,
+                                                      self.angleB)
+
+                paths.append(Path(verticesB, codesB))
+                fills.append(False)
+
+            return paths, fills
+
+    @_register_style(_style_list, name="-")
+    class Curve(_Curve):
+        """A simple curve without any arrow head."""
+
+        def __init__(self):  # hide head_length, head_width
+            # These attributes (whose values come from backcompat) only matter
+            # if someone modifies beginarrow/etc. on an ArrowStyle instance.
+            super().__init__(head_length=.2, head_width=.1)
+
+    @_register_style(_style_list, name="<-")
+    class CurveA(_Curve):
+        """An arrow with a head at its start point."""
+        arrow = "<-"
+
+    @_register_style(_style_list, name="->")
+    class CurveB(_Curve):
+        """An arrow with a head at its end point."""
+        arrow = "->"
+
+    @_register_style(_style_list, name="<->")
+    class CurveAB(_Curve):
+        """An arrow with heads both at the start and the end point."""
+        arrow = "<->"
+
+    @_register_style(_style_list, name="<|-")
+    class CurveFilledA(_Curve):
+        """An arrow with filled triangle head at the start."""
+        arrow = "<|-"
+
+    @_register_style(_style_list, name="-|>")
+    class CurveFilledB(_Curve):
+        """An arrow with filled triangle head at the end."""
+        arrow = "-|>"
+
+    @_register_style(_style_list, name="<|-|>")
+    class CurveFilledAB(_Curve):
+        """An arrow with filled triangle heads at both ends."""
+        arrow = "<|-|>"
+
+    @_register_style(_style_list, name="]-")
+    class BracketA(_Curve):
+        """An arrow with an outward square bracket at its start."""
+        arrow = "]-"
+
+        def __init__(self, widthA=1., lengthA=0.2, angleA=0):
+            """
+            Parameters
+            ----------
+            widthA : float, default: 1.0
+                Width of the bracket.
+            lengthA : float, default: 0.2
+                Length of the bracket.
+            angleA : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthA=widthA, lengthA=lengthA, angleA=angleA)
+
+    @_register_style(_style_list, name="-[")
+    class BracketB(_Curve):
+        """An arrow with an outward square bracket at its end."""
+        arrow = "-["
+
+        def __init__(self, widthB=1., lengthB=0.2, angleB=0):
+            """
+            Parameters
+            ----------
+            widthB : float, default: 1.0
+                Width of the bracket.
+            lengthB : float, default: 0.2
+                Length of the bracket.
+            angleB : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthB=widthB, lengthB=lengthB, angleB=angleB)
+
+    @_register_style(_style_list, name="]-[")
+    class BracketAB(_Curve):
+        """An arrow with outward square brackets at both ends."""
+        arrow = "]-["
+
+        def __init__(self,
+                     widthA=1., lengthA=0.2, angleA=0,
+                     widthB=1., lengthB=0.2, angleB=0):
+            """
+            Parameters
+            ----------
+            widthA, widthB : float, default: 1.0
+                Width of the bracket.
+            lengthA, lengthB : float, default: 0.2
+                Length of the bracket.
+            angleA, angleB : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthA=widthA, lengthA=lengthA, angleA=angleA,
+                             widthB=widthB, lengthB=lengthB, angleB=angleB)
+
+    @_register_style(_style_list, name="|-|")
+    class BarAB(_Curve):
+        """An arrow with vertical bars ``|`` at both ends."""
+        arrow = "|-|"
+
+        def __init__(self, widthA=1., angleA=0, widthB=1., angleB=0):
+            """
+            Parameters
+            ----------
+            widthA, widthB : float, default: 1.0
+                Width of the bracket.
+            angleA, angleB : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthA=widthA, lengthA=0, angleA=angleA,
+                             widthB=widthB, lengthB=0, angleB=angleB)
+
+    @_register_style(_style_list, name=']->')
+    class BracketCurve(_Curve):
+        """
+        An arrow with an outward square bracket at its start and a head at
+        the end.
+        """
+        arrow = "]->"
+
+        def __init__(self, widthA=1., lengthA=0.2, angleA=None):
+            """
+            Parameters
+            ----------
+            widthA : float, default: 1.0
+                Width of the bracket.
+            lengthA : float, default: 0.2
+                Length of the bracket.
+            angleA : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthA=widthA, lengthA=lengthA, angleA=angleA)
+
+    @_register_style(_style_list, name='<-[')
+    class CurveBracket(_Curve):
+        """
+        An arrow with an outward square bracket at its end and a head at
+        the start.
+        """
+        arrow = "<-["
+
+        def __init__(self, widthB=1., lengthB=0.2, angleB=None):
+            """
+            Parameters
+            ----------
+            widthB : float, default: 1.0
+                Width of the bracket.
+            lengthB : float, default: 0.2
+                Length of the bracket.
+            angleB : float, default: 0 degrees
+                Orientation of the bracket, as a counterclockwise angle.
+                0 degrees means perpendicular to the line.
+            """
+            super().__init__(widthB=widthB, lengthB=lengthB, angleB=angleB)
+
+    @_register_style(_style_list)
+    class Simple(_Base):
+        """A simple arrow. Only works with a quadratic Bézier curve."""
+
+        def __init__(self, head_length=.5, head_width=.5, tail_width=.2):
+            """
+            Parameters
+            ----------
+            head_length : float, default: 0.5
+                Length of the arrow head.
+
+            head_width : float, default: 0.5
+                Width of the arrow head.
+
+            tail_width : float, default: 0.2
+                Width of the arrow tail.
+            """
+            self.head_length, self.head_width, self.tail_width = \
+                head_length, head_width, tail_width
+            super().__init__()
+
+        def transmute(self, path, mutation_size, linewidth):
+            # docstring inherited
+            x0, y0, x1, y1, x2, y2 = self.ensure_quadratic_bezier(path)
+
+            # divide the path into a head and a tail
+            head_length = self.head_length * mutation_size
+            in_f = inside_circle(x2, y2, head_length)
+            arrow_path = [(x0, y0), (x1, y1), (x2, y2)]
+
+            try:
+                arrow_out, arrow_in = \
+                    split_bezier_intersecting_with_closedpath(arrow_path, in_f)
+            except NonIntersectingPathException:
+                # if this happens, make a straight line of the head_length
+                # long.
+                x0, y0 = _point_along_a_line(x2, y2, x1, y1, head_length)
+                x1n, y1n = 0.5 * (x0 + x2), 0.5 * (y0 + y2)
+                arrow_in = [(x0, y0), (x1n, y1n), (x2, y2)]
+                arrow_out = None
+
+            # head
+            head_width = self.head_width * mutation_size
+            head_left, head_right = make_wedged_bezier2(arrow_in,
+                                                        head_width / 2., wm=.5)
+
+            # tail
+            if arrow_out is not None:
+                tail_width = self.tail_width * mutation_size
+                tail_left, tail_right = get_parallels(arrow_out,
+                                                      tail_width / 2.)
+
+                patch_path = [(Path.MOVETO, tail_right[0]),
+                              (Path.CURVE3, tail_right[1]),
+                              (Path.CURVE3, tail_right[2]),
+                              (Path.LINETO, head_right[0]),
+                              (Path.CURVE3, head_right[1]),
+                              (Path.CURVE3, head_right[2]),
+                              (Path.CURVE3, head_left[1]),
+                              (Path.CURVE3, head_left[0]),
+                              (Path.LINETO, tail_left[2]),
+                              (Path.CURVE3, tail_left[1]),
+                              (Path.CURVE3, tail_left[0]),
+                              (Path.LINETO, tail_right[0]),
+                              (Path.CLOSEPOLY, tail_right[0]),
+                              ]
+            else:
+                patch_path = [(Path.MOVETO, head_right[0]),
+                              (Path.CURVE3, head_right[1]),
+                              (Path.CURVE3, head_right[2]),
+                              (Path.CURVE3, head_left[1]),
+                              (Path.CURVE3, head_left[0]),
+                              (Path.CLOSEPOLY, head_left[0]),
+                              ]
+
+            path = Path([p for c, p in patch_path], [c for c, p in patch_path])
+
+            return path, True
+
+    @_register_style(_style_list)
+    class Fancy(_Base):
+        """A fancy arrow. Only works with a quadratic Bézier curve."""
+
+        def __init__(self, head_length=.4, head_width=.4, tail_width=.4):
+            """
+            Parameters
+            ----------
+            head_length : float, default: 0.4
+                Length of the arrow head.
+
+            head_width : float, default: 0.4
+                Width of the arrow head.
+
+            tail_width : float, default: 0.4
+                Width of the arrow tail.
+            """
+            self.head_length, self.head_width, self.tail_width = \
+                head_length, head_width, tail_width
+            super().__init__()
+
+        def transmute(self, path, mutation_size, linewidth):
+            # docstring inherited
+            x0, y0, x1, y1, x2, y2 = self.ensure_quadratic_bezier(path)
+
+            # divide the path into a head and a tail
+            head_length = self.head_length * mutation_size
+            arrow_path = [(x0, y0), (x1, y1), (x2, y2)]
+
+            # path for head
+            in_f = inside_circle(x2, y2, head_length)
+            try:
+                path_out, path_in = split_bezier_intersecting_with_closedpath(
+                    arrow_path, in_f)
+            except NonIntersectingPathException:
+                # if this happens, make a straight line of the head_length
+                # long.
+                x0, y0 = _point_along_a_line(x2, y2, x1, y1, head_length)
+                x1n, y1n = 0.5 * (x0 + x2), 0.5 * (y0 + y2)
+                arrow_path = [(x0, y0), (x1n, y1n), (x2, y2)]
+                path_head = arrow_path
+            else:
+                path_head = path_in
+
+            # path for head
+            in_f = inside_circle(x2, y2, head_length * .8)
+            path_out, path_in = split_bezier_intersecting_with_closedpath(
+                arrow_path, in_f)
+            path_tail = path_out
+
+            # head
+            head_width = self.head_width * mutation_size
+            head_l, head_r = make_wedged_bezier2(path_head,
+                                                 head_width / 2.,
+                                                 wm=.6)
+
+            # tail
+            tail_width = self.tail_width * mutation_size
+            tail_left, tail_right = make_wedged_bezier2(path_tail,
+                                                        tail_width * .5,
+                                                        w1=1., wm=0.6, w2=0.3)
+
+            # path for head
+            in_f = inside_circle(x0, y0, tail_width * .3)
+            path_in, path_out = split_bezier_intersecting_with_closedpath(
+                arrow_path, in_f)
+            tail_start = path_in[-1]
+
+            head_right, head_left = head_r, head_l
+            patch_path = [(Path.MOVETO, tail_start),
+                          (Path.LINETO, tail_right[0]),
+                          (Path.CURVE3, tail_right[1]),
+                          (Path.CURVE3, tail_right[2]),
+                          (Path.LINETO, head_right[0]),
+                          (Path.CURVE3, head_right[1]),
+                          (Path.CURVE3, head_right[2]),
+                          (Path.CURVE3, head_left[1]),
+                          (Path.CURVE3, head_left[0]),
+                          (Path.LINETO, tail_left[2]),
+                          (Path.CURVE3, tail_left[1]),
+                          (Path.CURVE3, tail_left[0]),
+                          (Path.LINETO, tail_start),
+                          (Path.CLOSEPOLY, tail_start),
+                          ]
+            path = Path([p for c, p in patch_path], [c for c, p in patch_path])
+
+            return path, True
+
+    @_register_style(_style_list)
+    class Wedge(_Base):
+        """
+        Wedge(?) shape. Only works with a quadratic Bézier curve.  The
+        start point has a width of the *tail_width* and the end point has a
+        width of 0. At the middle, the width is *shrink_factor*x*tail_width*.
+        """
+
+        def __init__(self, tail_width=.3, shrink_factor=0.5):
+            """
+            Parameters
+            ----------
+            tail_width : float, default: 0.3
+                Width of the tail.
+
+            shrink_factor : float, default: 0.5
+                Fraction of the arrow width at the middle point.
+            """
+            self.tail_width = tail_width
+            self.shrink_factor = shrink_factor
+            super().__init__()
+
+        def transmute(self, path, mutation_size, linewidth):
+            # docstring inherited
+            x0, y0, x1, y1, x2, y2 = self.ensure_quadratic_bezier(path)
+
+            arrow_path = [(x0, y0), (x1, y1), (x2, y2)]
+            b_plus, b_minus = make_wedged_bezier2(
+                                    arrow_path,
+                                    self.tail_width * mutation_size / 2.,
+                                    wm=self.shrink_factor)
+
+            patch_path = [(Path.MOVETO, b_plus[0]),
+                          (Path.CURVE3, b_plus[1]),
+                          (Path.CURVE3, b_plus[2]),
+                          (Path.LINETO, b_minus[2]),
+                          (Path.CURVE3, b_minus[1]),
+                          (Path.CURVE3, b_minus[0]),
+                          (Path.CLOSEPOLY, b_minus[0]),
+                          ]
+            path = Path([p for c, p in patch_path], [c for c, p in patch_path])
+
+            return path, True
+
+
+class FancyBboxPatch(Patch):
+    """
+    A fancy box around a rectangle with lower left at *xy* = (*x*, *y*)
+    with specified width and height.
+
+    `.FancyBboxPatch` is similar to `.Rectangle`, but it draws a fancy box
+    around the rectangle. The transformation of the rectangle box to the
+    fancy box is delegated to the style classes defined in `.BoxStyle`.
+    """
+
+    _edge_default = True
+
+    def __str__(self):
+        s = self.__class__.__name__ + "((%g, %g), width=%g, height=%g)"
+        return s % (self._x, self._y, self._width, self._height)
+
+    @_docstring.interpd
+    def __init__(self, xy, width, height, boxstyle="round", *,
+                 mutation_scale=1, mutation_aspect=1, **kwargs):
+        """
+        Parameters
+        ----------
+        xy : (float, float)
+          The lower left corner of the box.
+
+        width : float
+            The width of the box.
+
+        height : float
+            The height of the box.
+
+        boxstyle : str or `~matplotlib.patches.BoxStyle`
+            The style of the fancy box. This can either be a `.BoxStyle`
+            instance or a string of the style name and optionally comma
+            separated attributes (e.g. "Round, pad=0.2"). This string is
+            passed to `.BoxStyle` to construct a `.BoxStyle` object. See
+            there for a full documentation.
+
+            The following box styles are available:
+
+            %(BoxStyle:table)s
+
+        mutation_scale : float, default: 1
+            Scaling factor applied to the attributes of the box style
+            (e.g. pad or rounding_size).
+
+        mutation_aspect : float, default: 1
+            The height of the rectangle will be squeezed by this value before
+            the mutation and the mutated box will be stretched by the inverse
+            of it. For example, this allows different horizontal and vertical
+            padding.
+
+        Other Parameters
+        ----------------
+        **kwargs : `~matplotlib.patches.Patch` properties
+
+        %(Patch:kwdoc)s
+        """
+
+        super().__init__(**kwargs)
+        self._x, self._y = xy
+        self._width = width
+        self._height = height
+        self.set_boxstyle(boxstyle)
+        self._mutation_scale = mutation_scale
+        self._mutation_aspect = mutation_aspect
+        self.stale = True
+
+    @_docstring.interpd
+    def set_boxstyle(self, boxstyle=None, **kwargs):
+        """
+        Set the box style, possibly with further attributes.
+
+        Attributes from the previous box style are not reused.
+
+        Without argument (or with ``boxstyle=None``), the available box styles
+        are returned as a human-readable string.
+
+        Parameters
+        ----------
+        boxstyle : str or `~matplotlib.patches.BoxStyle`
+            The style of the box: either a `.BoxStyle` instance, or a string,
+            which is the style name and optionally comma separated attributes
+            (e.g. "Round,pad=0.2"). Such a string is used to construct a
+            `.BoxStyle` object, as documented in that class.
+
+            The following box styles are available:
+
+            %(BoxStyle:table_and_accepts)s
+
+        **kwargs
+            Additional attributes for the box style. See the table above for
+            supported parameters.
+
+        Examples
+        --------
+        ::
+
+            set_boxstyle("Round,pad=0.2")
+            set_boxstyle("round", pad=0.2)
+        """
+        if boxstyle is None:
+            return BoxStyle.pprint_styles()
+        self._bbox_transmuter = (
+            BoxStyle(boxstyle, **kwargs)
+            if isinstance(boxstyle, str) else boxstyle)
+        self.stale = True
+
+    def get_boxstyle(self):
+        """Return the boxstyle object."""
+        return self._bbox_transmuter
+
+    def set_mutation_scale(self, scale):
+        """
+        Set the mutation scale.
+
+        Parameters
+        ----------
+        scale : float
+        """
+        self._mutation_scale = scale
+        self.stale = True
+
+    def get_mutation_scale(self):
+        """Return the mutation scale."""
+        return self._mutation_scale
+
+    def set_mutation_aspect(self, aspect):
+        """
+        Set the aspect ratio of the bbox mutation.
+
+        Parameters
+        ----------
+        aspect : float
+        """
+        self._mutation_aspect = aspect
+        self.stale = True
+
+    def get_mutation_aspect(self):
+        """Return the aspect ratio of the bbox mutation."""
+        return (self._mutation_aspect if self._mutation_aspect is not None
+                else 1)  # backcompat.
+
+    def get_path(self):
+        """Return the mutated path of the rectangle."""
+        boxstyle = self.get_boxstyle()
+        m_aspect = self.get_mutation_aspect()
+        # Call boxstyle with y, height squeezed by aspect_ratio.
+        path = boxstyle(self._x, self._y / m_aspect,
+                        self._width, self._height / m_aspect,
+                        self.get_mutation_scale())
+        return Path(path.vertices * [1, m_aspect], path.codes)  # Unsqueeze y.
+
+    # Following methods are borrowed from the Rectangle class.
+
+    def get_x(self):
+        """Return the left coord of the rectangle."""
+        return self._x
+
+    def get_y(self):
+        """Return the bottom coord of the rectangle."""
+        return self._y
+
+    def get_width(self):
+        """Return the width of the rectangle."""
+        return self._width
+
+    def get_height(self):
+        """Return the height of the rectangle."""
+        return self._height
+
+    def set_x(self, x):
+        """
+        Set the left coord of the rectangle.
+
+        Parameters
+        ----------
+        x : float
+        """
+        self._x = x
+        self.stale = True
+
+    def set_y(self, y):
+        """
+        Set the bottom coord of the rectangle.
+
+        Parameters
+        ----------
+        y : float
+        """
+        self._y = y
+        self.stale = True
+
+    def set_width(self, w):
+        """
+        Set the rectangle width.
+
+        Parameters
+        ----------
+        w : float
+        """
+        self._width = w
+        self.stale = True
+
+    def set_height(self, h):
+        """
+        Set the rectangle height.
+
+        Parameters
+        ----------
+        h : float
+        """
+        self._height = h
+        self.stale = True
+
+    def set_bounds(self, *args):
+        """
+        Set the bounds of the rectangle.
+
+        Call signatures::
+
+            set_bounds(left, bottom, width, height)
+            set_bounds((left, bottom, width, height))
+
+        Parameters
+        ----------
+        left, bottom : float
+            The coordinates of the bottom left corner of the rectangle.
+        width, height : float
+            The width/height of the rectangle.
+        """
+        if len(args) == 1:
+            l, b, w, h = args[0]
+        else:
+            l, b, w, h = args
+        self._x = l
+        self._y = b
+        self._width = w
+        self._height = h
+        self.stale = True
+
+    def get_bbox(self):
+        """Return the `.Bbox`."""
+        return transforms.Bbox.from_bounds(self._x, self._y,
+                                           self._width, self._height)
+
+
+class FancyArrowPatch(Patch):
+    """
+    A fancy arrow patch.
+
+    It draws an arrow using the `ArrowStyle`. It is primarily used by the
+    `~.axes.Axes.annotate` method.  For most purposes, use the annotate method for
+    drawing arrows.
+
+    The head and tail positions are fixed at the specified start and end points
+    of the arrow, but the size and shape (in display coordinates) of the arrow
+    does not change when the axis is moved or zoomed.
+    """
+    _edge_default = True
+
+    def __str__(self):
+        if self._posA_posB is not None:
+            (x1, y1), (x2, y2) = self._posA_posB
+            return f"{type(self).__name__}(({x1:g}, {y1:g})->({x2:g}, {y2:g}))"
+        else:
+            return f"{type(self).__name__}({self._path_original})"
+
+    @_docstring.interpd
+    def __init__(self, posA=None, posB=None, *,
+                 path=None, arrowstyle="simple", connectionstyle="arc3",
+                 patchA=None, patchB=None, shrinkA=2, shrinkB=2,
+                 mutation_scale=1, mutation_aspect=1, **kwargs):
+        """
+        **Defining the arrow position and path**
+
+        There are two ways to define the arrow position and path:
+
+        - **Start, end and connection**:
+          The typical approach is to define the start and end points of the
+          arrow using *posA* and *posB*. The curve between these two can
+          further be configured using *connectionstyle*.
+
+          If given, the arrow curve is clipped by *patchA* and *patchB*,
+          allowing it to start/end at the border of these patches.
+          Additionally, the arrow curve can be shortened by *shrinkA* and *shrinkB*
+          to create a margin between start/end (after possible clipping) and the
+          drawn arrow.
+
+        - **path**: Alternatively if *path* is provided, an arrow is drawn along
+          this Path. In this case, *connectionstyle*, *patchA*, *patchB*,
+          *shrinkA*, and *shrinkB* are ignored.
+
+        **Styling**
+
+        The *arrowstyle* defines the styling of the arrow head, tail and shaft.
+        The resulting arrows can be styled further by setting the `.Patch`
+        properties such as *linewidth*, *color*, *facecolor*, *edgecolor*
+        etc. via keyword arguments.
+
+        Parameters
+        ----------
+        posA, posB : (float, float), optional
+            (x, y) coordinates of start and end point of the arrow.
+            The actually drawn start and end positions may be modified
+            through *patchA*, *patchB*, *shrinkA*, and *shrinkB*.
+
+            *posA*, *posB* are exclusive of *path*.
+
+        path : `~matplotlib.path.Path`, optional
+            If provided, an arrow is drawn along this path and *patchA*,
+            *patchB*, *shrinkA*, and *shrinkB* are ignored.
+
+            *path* is exclusive of *posA*, *posB*.
+
+        arrowstyle : str or `.ArrowStyle`, default: 'simple'
+            The styling of arrow head, tail and shaft. This can be
+
+            - `.ArrowStyle` or one of its subclasses
+            - The shorthand string name (e.g. "->") as given in the table below,
+              optionally containing a comma-separated list of style parameters,
+              e.g. "->, head_length=10, head_width=5".
+
+            The style parameters are scaled by *mutation_scale*.
+
+            The following arrow styles are available. See also
+            :doc:`/gallery/text_labels_and_annotations/fancyarrow_demo`.
+
+            %(ArrowStyle:table)s
+
+            Only the styles ``<|-``, ``-|>``, ``<|-|>`` ``simple``, ``fancy``
+            and ``wedge`` contain closed paths and can be filled.
+
+        connectionstyle : str or `.ConnectionStyle` or None, optional, \
+default: 'arc3'
+            `.ConnectionStyle` with which *posA* and *posB* are connected.
+            This can be
+
+            - `.ConnectionStyle` or one of its subclasses
+            - The shorthand string name as given in the table below, e.g. "arc3".
+
+            %(ConnectionStyle:table)s
+
+            Ignored if *path* is provided.
+
+        patchA, patchB : `~matplotlib.patches.Patch`, default: None
+            Optional Patches at *posA* and *posB*, respectively. If given,
+            the arrow path is clipped by these patches such that head and tail
+            are at the border of the patches.
+
+            Ignored if *path* is provided.
+
+        shrinkA, shrinkB : float, default: 2
+            Shorten the arrow path at *posA* and *posB* by this amount in points.
+            This allows to add a margin between the intended start/end points and
+            the arrow.
+
+            Ignored if *path* is provided.
+
+        mutation_scale : float, default: 1
+            Value with which attributes of *arrowstyle* (e.g., *head_length*)
+            will be scaled.
+
+        mutation_aspect : None or float, default: None
+            The height of the rectangle will be squeezed by this value before
+            the mutation and the mutated box will be stretched by the inverse
+            of it.
+
+        Other Parameters
+        ----------------
+        **kwargs : `~matplotlib.patches.Patch` properties, optional
+            Here is a list of available `.Patch` properties:
+
+        %(Patch:kwdoc)s
+
+            In contrast to other patches, the default ``capstyle`` and
+            ``joinstyle`` for `FancyArrowPatch` are set to ``"round"``.
+        """
+        # Traditionally, the cap- and joinstyle for FancyArrowPatch are round
+        kwargs.setdefault("joinstyle", JoinStyle.round)
+        kwargs.setdefault("capstyle", CapStyle.round)
+
+        super().__init__(**kwargs)
+
+        if posA is not None and posB is not None and path is None:
+            self._posA_posB = [posA, posB]
+
+            if connectionstyle is None:
+                connectionstyle = "arc3"
+            self.set_connectionstyle(connectionstyle)
+
+        elif posA is None and posB is None and path is not None:
+            self._posA_posB = None
+        else:
+            raise ValueError("Either posA and posB, or path need to provided")
+
+        self.patchA = patchA
+        self.patchB = patchB
+        self.shrinkA = shrinkA
+        self.shrinkB = shrinkB
+
+        self._path_original = path
+
+        self.set_arrowstyle(arrowstyle)
+
+        self._mutation_scale = mutation_scale
+        self._mutation_aspect = mutation_aspect
+
+        self._dpi_cor = 1.0
+
+    def set_positions(self, posA, posB):
+        """
+        Set the start and end positions of the connecting path.
+
+        Parameters
+        ----------
+        posA, posB : None, tuple
+            (x, y) coordinates of arrow tail and arrow head respectively. If
+            `None` use current value.
+        """
+        if posA is not None:
+            self._posA_posB[0] = posA
+        if posB is not None:
+            self._posA_posB[1] = posB
+        self.stale = True
+
+    def set_patchA(self, patchA):
+        """
+        Set the tail patch.
+
+        Parameters
+        ----------
+        patchA : `.patches.Patch`
+        """
+        self.patchA = patchA
+        self.stale = True
+
+    def set_patchB(self, patchB):
+        """
+        Set the head patch.
+
+        Parameters
+        ----------
+        patchB : `.patches.Patch`
+        """
+        self.patchB = patchB
+        self.stale = True
+
+    @_docstring.interpd
+    def set_connectionstyle(self, connectionstyle=None, **kwargs):
+        """
+        Set the connection style, possibly with further attributes.
+
+        Attributes from the previous connection style are not reused.
+
+        Without argument (or with ``connectionstyle=None``), the available box
+        styles are returned as a human-readable string.
+
+        Parameters
+        ----------
+        connectionstyle : str or `~matplotlib.patches.ConnectionStyle`
+            The style of the connection: either a `.ConnectionStyle` instance,
+            or a string, which is the style name and optionally comma separated
+            attributes (e.g. "Arc,armA=30,rad=10"). Such a string is used to
+            construct a `.ConnectionStyle` object, as documented in that class.
+
+            The following connection styles are available:
+
+            %(ConnectionStyle:table_and_accepts)s
+
+        **kwargs
+            Additional attributes for the connection style. See the table above
+            for supported parameters.
+
+        Examples
+        --------
+        ::
+
+            set_connectionstyle("Arc,armA=30,rad=10")
+            set_connectionstyle("arc", armA=30, rad=10)
+        """
+        if connectionstyle is None:
+            return ConnectionStyle.pprint_styles()
+        self._connector = (
+            ConnectionStyle(connectionstyle, **kwargs)
+            if isinstance(connectionstyle, str) else connectionstyle)
+        self.stale = True
+
+    def get_connectionstyle(self):
+        """Return the `ConnectionStyle` used."""
+        return self._connector
+
+    @_docstring.interpd
+    def set_arrowstyle(self, arrowstyle=None, **kwargs):
+        """
+        Set the arrow style, possibly with further attributes.
+
+        Attributes from the previous arrow style are not reused.
+
+        Without argument (or with ``arrowstyle=None``), the available box
+        styles are returned as a human-readable string.
+
+        Parameters
+        ----------
+        arrowstyle : str or `~matplotlib.patches.ArrowStyle`
+            The style of the arrow: either a `.ArrowStyle` instance, or a
+            string, which is the style name and optionally comma separated
+            attributes (e.g. "Fancy,head_length=0.2"). Such a string is used to
+            construct a `.ArrowStyle` object, as documented in that class.
+
+            The following arrow styles are available:
+
+            %(ArrowStyle:table_and_accepts)s
+
+        **kwargs
+            Additional attributes for the arrow style. See the table above for
+            supported parameters.
+
+        Examples
+        --------
+        ::
+
+            set_arrowstyle("Fancy,head_length=0.2")
+            set_arrowstyle("fancy", head_length=0.2)
+        """
+        if arrowstyle is None:
+            return ArrowStyle.pprint_styles()
+        self._arrow_transmuter = (
+            ArrowStyle(arrowstyle, **kwargs)
+            if isinstance(arrowstyle, str) else arrowstyle)
+        self.stale = True
+
+    def get_arrowstyle(self):
+        """Return the arrowstyle object."""
+        return self._arrow_transmuter
+
+    def set_mutation_scale(self, scale):
+        """
+        Set the mutation scale.
+
+        Parameters
+        ----------
+        scale : float
+        """
+        self._mutation_scale = scale
+        self.stale = True
+
+    def get_mutation_scale(self):
+        """
+        Return the mutation scale.
+
+        Returns
+        -------
+        scalar
+        """
+        return self._mutation_scale
+
+    def set_mutation_aspect(self, aspect):
+        """
+        Set the aspect ratio of the bbox mutation.
+
+        Parameters
+        ----------
+        aspect : float
+        """
+        self._mutation_aspect = aspect
+        self.stale = True
+
+    def get_mutation_aspect(self):
+        """Return the aspect ratio of the bbox mutation."""
+        return (self._mutation_aspect if self._mutation_aspect is not None
+                else 1)  # backcompat.
+
+    def get_path(self):
+        """Return the path of the arrow in the data coordinates."""
+        # The path is generated in display coordinates, then converted back to
+        # data coordinates.
+        _path, fillable = self._get_path_in_displaycoord()
+        if np.iterable(fillable):
+            _path = Path.make_compound_path(*_path)
+        return self.get_transform().inverted().transform_path(_path)
+
+    def _get_path_in_displaycoord(self):
+        """Return the mutated path of the arrow in display coordinates."""
+        dpi_cor = self._dpi_cor
+
+        if self._posA_posB is not None:
+            posA = self._convert_xy_units(self._posA_posB[0])
+            posB = self._convert_xy_units(self._posA_posB[1])
+            (posA, posB) = self.get_transform().transform((posA, posB))
+            _path = self.get_connectionstyle()(posA, posB,
+                                               patchA=self.patchA,
+                                               patchB=self.patchB,
+                                               shrinkA=self.shrinkA * dpi_cor,
+                                               shrinkB=self.shrinkB * dpi_cor
+                                               )
+        else:
+            _path = self.get_transform().transform_path(self._path_original)
+
+        _path, fillable = self.get_arrowstyle()(
+            _path,
+            self.get_mutation_scale() * dpi_cor,
+            self.get_linewidth() * dpi_cor,
+            self.get_mutation_aspect())
+
+        return _path, fillable
+
+    def draw(self, renderer):
+        if not self.get_visible():
+            return
+
+        # FIXME: dpi_cor is for the dpi-dependency of the linewidth.  There
+        # could be room for improvement.  Maybe _get_path_in_displaycoord could
+        # take a renderer argument, but get_path should be adapted too.
+        self._dpi_cor = renderer.points_to_pixels(1.)
+        path, fillable = self._get_path_in_displaycoord()
+
+        if not np.iterable(fillable):
+            path = [path]
+            fillable = [fillable]
+
+        affine = transforms.IdentityTransform()
+
+        self._draw_paths_with_artist_properties(
+            renderer,
+            [(p, affine, self._facecolor if f and self._facecolor[3] else None)
+             for p, f in zip(path, fillable)])
+
+
+class ConnectionPatch(FancyArrowPatch):
+    """A patch that connects two points (possibly in different Axes)."""
+
+    def __str__(self):
+        return "ConnectionPatch((%g, %g), (%g, %g))" % \
+               (self.xy1[0], self.xy1[1], self.xy2[0], self.xy2[1])
+
+    @_docstring.interpd
+    def __init__(self, xyA, xyB, coordsA, coordsB=None, *,
+                 axesA=None, axesB=None,
+                 arrowstyle="-",
+                 connectionstyle="arc3",
+                 patchA=None,
+                 patchB=None,
+                 shrinkA=0.,
+                 shrinkB=0.,
+                 mutation_scale=10.,
+                 mutation_aspect=None,
+                 clip_on=False,
+                 **kwargs):
+        """
+        Connect point *xyA* in *coordsA* with point *xyB* in *coordsB*.
+
+        Valid keys are
+
+        ===============  ======================================================
+        Key              Description
+        ===============  ======================================================
+        arrowstyle       the arrow style
+        connectionstyle  the connection style
+        relpos           default is (0.5, 0.5)
+        patchA           default is bounding box of the text
+        patchB           default is None
+        shrinkA          default is 2 points
+        shrinkB          default is 2 points
+        mutation_scale   default is text size (in points)
+        mutation_aspect  default is 1.
+        ?                any key for `matplotlib.patches.PathPatch`
+        ===============  ======================================================
+
+        *coordsA* and *coordsB* are strings that indicate the
+        coordinates of *xyA* and *xyB*.
+
+        ==================== ==================================================
+        Property             Description
+        ==================== ==================================================
+        'figure points'      points from the lower left corner of the figure
+        'figure pixels'      pixels from the lower left corner of the figure
+        'figure fraction'    0, 0 is lower left of figure and 1, 1 is upper
+                             right
+        'subfigure points'   points from the lower left corner of the subfigure
+        'subfigure pixels'   pixels from the lower left corner of the subfigure
+        'subfigure fraction' fraction of the subfigure, 0, 0 is lower left.
+        'axes points'        points from lower left corner of the Axes
+        'axes pixels'        pixels from lower left corner of the Axes
+        'axes fraction'      0, 0 is lower left of Axes and 1, 1 is upper right
+        'data'               use the coordinate system of the object being
+                             annotated (default)
+        'offset points'      offset (in points) from the *xy* value
+        'polar'              you can specify *theta*, *r* for the annotation,
+                             even in cartesian plots.  Note that if you are
+                             using a polar Axes, you do not need to specify
+                             polar for the coordinate system since that is the
+                             native "data" coordinate system.
+        ==================== ==================================================
+
+        Alternatively they can be set to any valid
+        `~matplotlib.transforms.Transform`.
+
+        Note that 'subfigure pixels' and 'figure pixels' are the same
+        for the parent figure, so users who want code that is usable in
+        a subfigure can use 'subfigure pixels'.
+
+        .. note::
+
+           Using `ConnectionPatch` across two `~.axes.Axes` instances
+           is not directly compatible with :ref:`constrained layout
+           <constrainedlayout_guide>`. Add the artist
+           directly to the `.Figure` instead of adding it to a specific Axes,
+           or exclude it from the layout using ``con.set_in_layout(False)``.
+
+           .. code-block:: default
+
+              fig, ax = plt.subplots(1, 2, constrained_layout=True)
+              con = ConnectionPatch(..., axesA=ax[0], axesB=ax[1])
+              fig.add_artist(con)
+
+        """
+        if coordsB is None:
+            coordsB = coordsA
+        # we'll draw ourself after the artist we annotate by default
+        self.xy1 = xyA
+        self.xy2 = xyB
+        self.coords1 = coordsA
+        self.coords2 = coordsB
+
+        self.axesA = axesA
+        self.axesB = axesB
+
+        super().__init__(posA=(0, 0), posB=(1, 1),
+                         arrowstyle=arrowstyle,
+                         connectionstyle=connectionstyle,
+                         patchA=patchA, patchB=patchB,
+                         shrinkA=shrinkA, shrinkB=shrinkB,
+                         mutation_scale=mutation_scale,
+                         mutation_aspect=mutation_aspect,
+                         clip_on=clip_on,
+                         **kwargs)
+        # if True, draw annotation only if self.xy is inside the Axes
+        self._annotation_clip = None
+
+    def _get_xy(self, xy, s, axes=None):
+        """Calculate the pixel position of given point."""
+        s0 = s  # For the error message, if needed.
+        if axes is None:
+            axes = self.axes
+
+        # preserve mixed type input (such as str, int)
+        x = np.array(xy[0])
+        y = np.array(xy[1])
+
+        fig = self.get_figure(root=False)
+        if s in ["figure points", "axes points"]:
+            x = x * fig.dpi / 72
+            y = y * fig.dpi / 72
+            s = s.replace("points", "pixels")
+        elif s == "figure fraction":
+            s = fig.transFigure
+        elif s == "subfigure fraction":
+            s = fig.transSubfigure
+        elif s == "axes fraction":
+            s = axes.transAxes
+
+        if s == 'data':
+            trans = axes.transData
+            x = cbook._to_unmasked_float_array(axes.xaxis.convert_units(x))
+            y = cbook._to_unmasked_float_array(axes.yaxis.convert_units(y))
+            return trans.transform((x, y))
+        elif s == 'offset points':
+            if self.xycoords == 'offset points':  # prevent recursion
+                return self._get_xy(self.xy, 'data')
+            return (
+                self._get_xy(self.xy, self.xycoords)  # converted data point
+                + xy * self.get_figure(root=True).dpi / 72)  # converted offset
+        elif s == 'polar':
+            theta, r = x, y
+            x = r * np.cos(theta)
+            y = r * np.sin(theta)
+            trans = axes.transData
+            return trans.transform((x, y))
+        elif s == 'figure pixels':
+            # pixels from the lower left corner of the figure
+            bb = self.get_figure(root=False).figbbox
+            x = bb.x0 + x if x >= 0 else bb.x1 + x
+            y = bb.y0 + y if y >= 0 else bb.y1 + y
+            return x, y
+        elif s == 'subfigure pixels':
+            # pixels from the lower left corner of the figure
+            bb = self.get_figure(root=False).bbox
+            x = bb.x0 + x if x >= 0 else bb.x1 + x
+            y = bb.y0 + y if y >= 0 else bb.y1 + y
+            return x, y
+        elif s == 'axes pixels':
+            # pixels from the lower left corner of the Axes
+            bb = axes.bbox
+            x = bb.x0 + x if x >= 0 else bb.x1 + x
+            y = bb.y0 + y if y >= 0 else bb.y1 + y
+            return x, y
+        elif isinstance(s, transforms.Transform):
+            return s.transform(xy)
+        else:
+            raise ValueError(f"{s0} is not a valid coordinate transformation")
+
+    def set_annotation_clip(self, b):
+        """
+        Set the annotation's clipping behavior.
+
+        Parameters
+        ----------
+        b : bool or None
+            - True: The annotation will be clipped when ``self.xy`` is
+              outside the Axes.
+            - False: The annotation will always be drawn.
+            - None: The annotation will be clipped when ``self.xy`` is
+              outside the Axes and ``self.xycoords == "data"``.
+        """
+        self._annotation_clip = b
+        self.stale = True
+
+    def get_annotation_clip(self):
+        """
+        Return the clipping behavior.
+
+        See `.set_annotation_clip` for the meaning of the return value.
+        """
+        return self._annotation_clip
+
+    def _get_path_in_displaycoord(self):
+        """Return the mutated path of the arrow in display coordinates."""
+        dpi_cor = self._dpi_cor
+        posA = self._get_xy(self.xy1, self.coords1, self.axesA)
+        posB = self._get_xy(self.xy2, self.coords2, self.axesB)
+        path = self.get_connectionstyle()(
+            posA, posB,
+            patchA=self.patchA, patchB=self.patchB,
+            shrinkA=self.shrinkA * dpi_cor, shrinkB=self.shrinkB * dpi_cor,
+        )
+        path, fillable = self.get_arrowstyle()(
+            path,
+            self.get_mutation_scale() * dpi_cor,
+            self.get_linewidth() * dpi_cor,
+            self.get_mutation_aspect()
+        )
+        return path, fillable
+
+    def _check_xy(self, renderer):
+        """Check whether the annotation needs to be drawn."""
+
+        b = self.get_annotation_clip()
+
+        if b or (b is None and self.coords1 == "data"):
+            xy_pixel = self._get_xy(self.xy1, self.coords1, self.axesA)
+            if self.axesA is None:
+                axes = self.axes
+            else:
+                axes = self.axesA
+            if not axes.contains_point(xy_pixel):
+                return False
+
+        if b or (b is None and self.coords2 == "data"):
+            xy_pixel = self._get_xy(self.xy2, self.coords2, self.axesB)
+            if self.axesB is None:
+                axes = self.axes
+            else:
+                axes = self.axesB
+            if not axes.contains_point(xy_pixel):
+                return False
+
+        return True
+
+    def draw(self, renderer):
+        if not self.get_visible() or not self._check_xy(renderer):
+            return
+        super().draw(renderer)
diff --git a/lib/python3.12/site-packages/matplotlib/patches.pyi b/lib/python3.12/site-packages/matplotlib/patches.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..0645479ee5e75de2279a0d619b8860d7abe4bd32
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/patches.pyi
@@ -0,0 +1,757 @@
+from . import artist
+from .axes import Axes
+from .backend_bases import RendererBase, MouseEvent
+from .path import Path
+from .transforms import Transform, Bbox
+
+from typing import Any, Literal, overload
+
+import numpy as np
+from numpy.typing import ArrayLike
+from .typing import ColorType, LineStyleType, CapStyleType, JoinStyleType
+
+class Patch(artist.Artist):
+    zorder: float
+    def __init__(
+        self,
+        *,
+        edgecolor: ColorType | None = ...,
+        facecolor: ColorType | None = ...,
+        color: ColorType | None = ...,
+        linewidth: float | None = ...,
+        linestyle: LineStyleType | None = ...,
+        antialiased: bool | None = ...,
+        hatch: str | None = ...,
+        fill: bool = ...,
+        capstyle: CapStyleType | None = ...,
+        joinstyle: JoinStyleType | None = ...,
+        **kwargs,
+    ) -> None: ...
+    def get_verts(self) -> ArrayLike: ...
+    def contains(self, mouseevent: MouseEvent, radius: float | None = None) -> tuple[bool, dict[Any, Any]]: ...
+    def contains_point(
+        self, point: tuple[float, float], radius: float | None = ...
+    ) -> bool: ...
+    def contains_points(
+        self, points: ArrayLike, radius: float | None = ...
+    ) -> np.ndarray: ...
+    def get_extents(self) -> Bbox: ...
+    def get_transform(self) -> Transform: ...
+    def get_data_transform(self) -> Transform: ...
+    def get_patch_transform(self) -> Transform: ...
+    def get_antialiased(self) -> bool: ...
+    def get_edgecolor(self) -> ColorType: ...
+    def get_facecolor(self) -> ColorType: ...
+    def get_linewidth(self) -> float: ...
+    def get_linestyle(self) -> LineStyleType: ...
+    def set_antialiased(self, aa: bool | None) -> None: ...
+    def set_edgecolor(self, color: ColorType | None) -> None: ...
+    def set_facecolor(self, color: ColorType | None) -> None: ...
+    def set_color(self, c: ColorType | None) -> None: ...
+    def set_alpha(self, alpha: float | None) -> None: ...
+    def set_linewidth(self, w: float | None) -> None: ...
+    def set_linestyle(self, ls: LineStyleType | None) -> None: ...
+    def set_fill(self, b: bool) -> None: ...
+    def get_fill(self) -> bool: ...
+    fill = property(get_fill, set_fill)
+    def set_capstyle(self, s: CapStyleType) -> None: ...
+    def get_capstyle(self) -> Literal["butt", "projecting", "round"]: ...
+    def set_joinstyle(self, s: JoinStyleType) -> None: ...
+    def get_joinstyle(self) -> Literal["miter", "round", "bevel"]: ...
+    def set_hatch(self, hatch: str) -> None: ...
+    def set_hatch_linewidth(self, lw: float) -> None: ...
+    def get_hatch_linewidth(self) -> float: ...
+    def get_hatch(self) -> str: ...
+    def get_path(self) -> Path: ...
+
+class Shadow(Patch):
+    patch: Patch
+    def __init__(self, patch: Patch, ox: float, oy: float, *, shade: float = ..., **kwargs) -> None: ...
+
+class Rectangle(Patch):
+    angle: float
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        width: float,
+        height: float,
+        *,
+        angle: float = ...,
+        rotation_point: Literal["xy", "center"] | tuple[float, float] = ...,
+        **kwargs,
+    ) -> None: ...
+    @property
+    def rotation_point(self) -> Literal["xy", "center"] | tuple[float, float]: ...
+    @rotation_point.setter
+    def rotation_point(
+        self, value: Literal["xy", "center"] | tuple[float, float]
+    ) -> None: ...
+    def get_x(self) -> float: ...
+    def get_y(self) -> float: ...
+    def get_xy(self) -> tuple[float, float]: ...
+    def get_corners(self) -> np.ndarray: ...
+    def get_center(self) -> np.ndarray: ...
+    def get_width(self) -> float: ...
+    def get_height(self) -> float: ...
+    def get_angle(self) -> float: ...
+    def set_x(self, x: float) -> None: ...
+    def set_y(self, y: float) -> None: ...
+    def set_angle(self, angle: float) -> None: ...
+    def set_xy(self, xy: tuple[float, float]) -> None: ...
+    def set_width(self, w: float) -> None: ...
+    def set_height(self, h: float) -> None: ...
+    @overload
+    def set_bounds(self, args: tuple[float, float, float, float], /) -> None: ...
+    @overload
+    def set_bounds(
+        self, left: float, bottom: float, width: float, height: float, /
+    ) -> None: ...
+    def get_bbox(self) -> Bbox: ...
+    xy = property(get_xy, set_xy)
+
+class RegularPolygon(Patch):
+    xy: tuple[float, float]
+    numvertices: int
+    orientation: float
+    radius: float
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        numVertices: int,
+        *,
+        radius: float = ...,
+        orientation: float = ...,
+        **kwargs,
+    ) -> None: ...
+
+class PathPatch(Patch):
+    def __init__(self, path: Path, **kwargs) -> None: ...
+    def set_path(self, path: Path) -> None: ...
+
+class StepPatch(PathPatch):
+    orientation: Literal["vertical", "horizontal"]
+    def __init__(
+        self,
+        values: ArrayLike,
+        edges: ArrayLike,
+        *,
+        orientation: Literal["vertical", "horizontal"] = ...,
+        baseline: float = ...,
+        **kwargs,
+    ) -> None: ...
+
+    # NamedTuple StairData, defined in body of method
+    def get_data(self) -> tuple[np.ndarray, np.ndarray, float]: ...
+    def set_data(
+        self,
+        values: ArrayLike | None = ...,
+        edges: ArrayLike | None = ...,
+        baseline: float | None = ...,
+    ) -> None: ...
+
+class Polygon(Patch):
+    def __init__(self, xy: ArrayLike, *, closed: bool = ..., **kwargs) -> None: ...
+    def get_closed(self) -> bool: ...
+    def set_closed(self, closed: bool) -> None: ...
+    def get_xy(self) -> np.ndarray: ...
+    def set_xy(self, xy: ArrayLike) -> None: ...
+    xy = property(get_xy, set_xy)
+
+class Wedge(Patch):
+    center: tuple[float, float]
+    r: float
+    theta1: float
+    theta2: float
+    width: float | None
+    def __init__(
+        self,
+        center: tuple[float, float],
+        r: float,
+        theta1: float,
+        theta2: float,
+        *,
+        width: float | None = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_center(self, center: tuple[float, float]) -> None: ...
+    def set_radius(self, radius: float) -> None: ...
+    def set_theta1(self, theta1: float) -> None: ...
+    def set_theta2(self, theta2: float) -> None: ...
+    def set_width(self, width: float | None) -> None: ...
+
+class Arrow(Patch):
+    def __init__(
+        self, x: float, y: float, dx: float, dy: float, *, width: float = ..., **kwargs
+    ) -> None: ...
+    def set_data(
+        self,
+        x: float | None = ...,
+        y: float | None = ...,
+        dx: float | None = ...,
+        dy: float | None = ...,
+        width: float | None = ...,
+    ) -> None: ...
+class FancyArrow(Polygon):
+    def __init__(
+        self,
+        x: float,
+        y: float,
+        dx: float,
+        dy: float,
+        *,
+        width: float = ...,
+        length_includes_head: bool = ...,
+        head_width: float | None = ...,
+        head_length: float | None = ...,
+        shape: Literal["full", "left", "right"] = ...,
+        overhang: float = ...,
+        head_starts_at_zero: bool = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_data(
+        self,
+        *,
+        x: float | None = ...,
+        y: float | None = ...,
+        dx: float | None = ...,
+        dy: float | None = ...,
+        width: float | None = ...,
+        head_width: float | None = ...,
+        head_length: float | None = ...,
+    ) -> None: ...
+
+class CirclePolygon(RegularPolygon):
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        radius: float = ...,
+        *,
+        resolution: int = ...,
+        **kwargs,
+    ) -> None: ...
+
+class Ellipse(Patch):
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        width: float,
+        height: float,
+        *,
+        angle: float = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_center(self, xy: tuple[float, float]) -> None: ...
+    def get_center(self) -> float: ...
+    center = property(get_center, set_center)
+
+    def set_width(self, width: float) -> None: ...
+    def get_width(self) -> float: ...
+    width = property(get_width, set_width)
+
+    def set_height(self, height: float) -> None: ...
+    def get_height(self) -> float: ...
+    height = property(get_height, set_height)
+
+    def set_angle(self, angle: float) -> None: ...
+    def get_angle(self) -> float: ...
+    angle = property(get_angle, set_angle)
+
+    def get_corners(self) -> np.ndarray: ...
+
+    def get_vertices(self) -> list[tuple[float, float]]: ...
+    def get_co_vertices(self) -> list[tuple[float, float]]: ...
+
+
+class Annulus(Patch):
+    a: float
+    b: float
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        r: float | tuple[float, float],
+        width: float,
+        angle: float = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_center(self, xy: tuple[float, float]) -> None: ...
+    def get_center(self) -> tuple[float, float]: ...
+    center = property(get_center, set_center)
+
+    def set_width(self, width: float) -> None: ...
+    def get_width(self) -> float: ...
+    width = property(get_width, set_width)
+
+    def set_angle(self, angle: float) -> None: ...
+    def get_angle(self) -> float: ...
+    angle = property(get_angle, set_angle)
+
+    def set_semimajor(self, a: float) -> None: ...
+    def set_semiminor(self, b: float) -> None: ...
+    def set_radii(self, r: float | tuple[float, float]) -> None: ...
+    def get_radii(self) -> tuple[float, float]: ...
+    radii = property(get_radii, set_radii)
+
+class Circle(Ellipse):
+    def __init__(
+        self, xy: tuple[float, float], radius: float = ..., **kwargs
+    ) -> None: ...
+    def set_radius(self, radius: float) -> None: ...
+    def get_radius(self) -> float: ...
+    radius = property(get_radius, set_radius)
+
+class Arc(Ellipse):
+    theta1: float
+    theta2: float
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        width: float,
+        height: float,
+        *,
+        angle: float = ...,
+        theta1: float = ...,
+        theta2: float = ...,
+        **kwargs,
+    ) -> None: ...
+
+def bbox_artist(
+    artist: artist.Artist,
+    renderer: RendererBase,
+    props: dict[str, Any] | None = ...,
+    fill: bool = ...,
+) -> None: ...
+def draw_bbox(
+    bbox: Bbox,
+    renderer: RendererBase,
+    color: ColorType = ...,
+    trans: Transform | None = ...,
+) -> None: ...
+
+class _Style:
+    def __new__(cls, stylename, **kwargs): ...
+    @classmethod
+    def get_styles(cls) -> dict[str, type]: ...
+    @classmethod
+    def pprint_styles(cls) -> str: ...
+    @classmethod
+    def register(cls, name: str, style: type) -> None: ...
+
+class BoxStyle(_Style):
+    class Square(BoxStyle):
+        pad: float
+        def __init__(self, pad: float = ...) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Circle(BoxStyle):
+        pad: float
+        def __init__(self, pad: float = ...) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Ellipse(BoxStyle):
+        pad: float
+        def __init__(self, pad: float = ...) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class LArrow(BoxStyle):
+        pad: float
+        def __init__(self, pad: float = ...) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class RArrow(LArrow):
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class DArrow(BoxStyle):
+        pad: float
+        def __init__(self, pad: float = ...) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Round(BoxStyle):
+        pad: float
+        rounding_size: float | None
+        def __init__(
+            self, pad: float = ..., rounding_size: float | None = ...
+        ) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Round4(BoxStyle):
+        pad: float
+        rounding_size: float | None
+        def __init__(
+            self, pad: float = ..., rounding_size: float | None = ...
+        ) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Sawtooth(BoxStyle):
+        pad: float
+        tooth_size: float | None
+        def __init__(
+            self, pad: float = ..., tooth_size: float | None = ...
+        ) -> None: ...
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+    class Roundtooth(Sawtooth):
+        def __call__(
+            self,
+            x0: float,
+            y0: float,
+            width: float,
+            height: float,
+            mutation_size: float,
+        ) -> Path: ...
+
+class ConnectionStyle(_Style):
+    class _Base(ConnectionStyle):
+        def __call__(
+            self,
+            posA: tuple[float, float],
+            posB: tuple[float, float],
+            shrinkA: float = ...,
+            shrinkB: float = ...,
+            patchA: Patch | None = ...,
+            patchB: Patch | None = ...,
+        ) -> Path: ...
+
+    class Arc3(_Base):
+        rad: float
+        def __init__(self, rad: float = ...) -> None: ...
+        def connect(
+            self, posA: tuple[float, float], posB: tuple[float, float]
+        ) -> Path: ...
+
+    class Angle3(_Base):
+        angleA: float
+        angleB: float
+        def __init__(self, angleA: float = ..., angleB: float = ...) -> None: ...
+        def connect(
+            self, posA: tuple[float, float], posB: tuple[float, float]
+        ) -> Path: ...
+
+    class Angle(_Base):
+        angleA: float
+        angleB: float
+        rad: float
+        def __init__(
+            self, angleA: float = ..., angleB: float = ..., rad: float = ...
+        ) -> None: ...
+        def connect(
+            self, posA: tuple[float, float], posB: tuple[float, float]
+        ) -> Path: ...
+
+    class Arc(_Base):
+        angleA: float
+        angleB: float
+        armA: float | None
+        armB: float | None
+        rad: float
+        def __init__(
+            self,
+            angleA: float = ...,
+            angleB: float = ...,
+            armA: float | None = ...,
+            armB: float | None = ...,
+            rad: float = ...,
+        ) -> None: ...
+        def connect(
+            self, posA: tuple[float, float], posB: tuple[float, float]
+        ) -> Path: ...
+
+    class Bar(_Base):
+        armA: float
+        armB: float
+        fraction: float
+        angle: float | None
+        def __init__(
+            self,
+            armA: float = ...,
+            armB: float = ...,
+            fraction: float = ...,
+            angle: float | None = ...,
+        ) -> None: ...
+        def connect(
+            self, posA: tuple[float, float], posB: tuple[float, float]
+        ) -> Path: ...
+
+class ArrowStyle(_Style):
+    class _Base(ArrowStyle):
+        @staticmethod
+        def ensure_quadratic_bezier(path: Path) -> list[float]: ...
+        def transmute(
+            self, path: Path, mutation_size: float, linewidth: float
+        ) -> tuple[Path, bool]: ...
+        def __call__(
+            self,
+            path: Path,
+            mutation_size: float,
+            linewidth: float,
+            aspect_ratio: float = ...,
+        ) -> tuple[Path, bool]: ...
+
+    class _Curve(_Base):
+        arrow: str
+        fillbegin: bool
+        fillend: bool
+        def __init__(
+            self,
+            head_length: float = ...,
+            head_width: float = ...,
+            widthA: float = ...,
+            widthB: float = ...,
+            lengthA: float = ...,
+            lengthB: float = ...,
+            angleA: float | None = ...,
+            angleB: float | None = ...,
+            scaleA: float | None = ...,
+            scaleB: float | None = ...,
+        ) -> None: ...
+
+    class Curve(_Curve):
+        def __init__(self) -> None: ...
+
+    class CurveA(_Curve):
+        arrow: str
+
+    class CurveB(_Curve):
+        arrow: str
+
+    class CurveAB(_Curve):
+        arrow: str
+
+    class CurveFilledA(_Curve):
+        arrow: str
+
+    class CurveFilledB(_Curve):
+        arrow: str
+
+    class CurveFilledAB(_Curve):
+        arrow: str
+
+    class BracketA(_Curve):
+        arrow: str
+        def __init__(
+            self, widthA: float = ..., lengthA: float = ..., angleA: float = ...
+        ) -> None: ...
+
+    class BracketB(_Curve):
+        arrow: str
+        def __init__(
+            self, widthB: float = ..., lengthB: float = ..., angleB: float = ...
+        ) -> None: ...
+
+    class BracketAB(_Curve):
+        arrow: str
+        def __init__(
+            self,
+            widthA: float = ...,
+            lengthA: float = ...,
+            angleA: float = ...,
+            widthB: float = ...,
+            lengthB: float = ...,
+            angleB: float = ...,
+        ) -> None: ...
+
+    class BarAB(_Curve):
+        arrow: str
+        def __init__(
+            self,
+            widthA: float = ...,
+            angleA: float = ...,
+            widthB: float = ...,
+            angleB: float = ...,
+        ) -> None: ...
+
+    class BracketCurve(_Curve):
+        arrow: str
+        def __init__(
+            self, widthA: float = ..., lengthA: float = ..., angleA: float | None = ...
+        ) -> None: ...
+
+    class CurveBracket(_Curve):
+        arrow: str
+        def __init__(
+            self, widthB: float = ..., lengthB: float = ..., angleB: float | None = ...
+        ) -> None: ...
+
+    class Simple(_Base):
+        def __init__(
+            self,
+            head_length: float = ...,
+            head_width: float = ...,
+            tail_width: float = ...,
+        ) -> None: ...
+
+    class Fancy(_Base):
+        def __init__(
+            self,
+            head_length: float = ...,
+            head_width: float = ...,
+            tail_width: float = ...,
+        ) -> None: ...
+
+    class Wedge(_Base):
+        tail_width: float
+        shrink_factor: float
+        def __init__(
+            self, tail_width: float = ..., shrink_factor: float = ...
+        ) -> None: ...
+
+class FancyBboxPatch(Patch):
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        width: float,
+        height: float,
+        boxstyle: str | BoxStyle = ...,
+        *,
+        mutation_scale: float = ...,
+        mutation_aspect: float = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_boxstyle(self, boxstyle: str | BoxStyle | None = ..., **kwargs) -> None: ...
+    def get_boxstyle(self) -> BoxStyle: ...
+    def set_mutation_scale(self, scale: float) -> None: ...
+    def get_mutation_scale(self) -> float: ...
+    def set_mutation_aspect(self, aspect: float) -> None: ...
+    def get_mutation_aspect(self) -> float: ...
+    def get_x(self) -> float: ...
+    def get_y(self) -> float: ...
+    def get_width(self) -> float: ...
+    def get_height(self) -> float: ...
+    def set_x(self, x: float) -> None: ...
+    def set_y(self, y: float) -> None: ...
+    def set_width(self, w: float) -> None: ...
+    def set_height(self, h: float) -> None: ...
+    @overload
+    def set_bounds(self, args: tuple[float, float, float, float], /) -> None: ...
+    @overload
+    def set_bounds(
+        self, left: float, bottom: float, width: float, height: float, /
+    ) -> None: ...
+    def get_bbox(self) -> Bbox: ...
+
+class FancyArrowPatch(Patch):
+    patchA: Patch
+    patchB: Patch
+    shrinkA: float
+    shrinkB: float
+    def __init__(
+        self,
+        posA: tuple[float, float] | None = ...,
+        posB: tuple[float, float] | None = ...,
+        *,
+        path: Path | None = ...,
+        arrowstyle: str | ArrowStyle = ...,
+        connectionstyle: str | ConnectionStyle = ...,
+        patchA: Patch | None = ...,
+        patchB: Patch | None = ...,
+        shrinkA: float = ...,
+        shrinkB: float = ...,
+        mutation_scale: float = ...,
+        mutation_aspect: float | None = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_positions(
+        self, posA: tuple[float, float], posB: tuple[float, float]
+    ) -> None: ...
+    def set_patchA(self, patchA: Patch) -> None: ...
+    def set_patchB(self, patchB: Patch) -> None: ...
+    def set_connectionstyle(self, connectionstyle: str | ConnectionStyle | None = ..., **kwargs) -> None: ...
+    def get_connectionstyle(self) -> ConnectionStyle: ...
+    def set_arrowstyle(self, arrowstyle: str | ArrowStyle | None = ..., **kwargs) -> None: ...
+    def get_arrowstyle(self) -> ArrowStyle: ...
+    def set_mutation_scale(self, scale: float) -> None: ...
+    def get_mutation_scale(self) -> float: ...
+    def set_mutation_aspect(self, aspect: float | None) -> None: ...
+    def get_mutation_aspect(self) -> float: ...
+
+class ConnectionPatch(FancyArrowPatch):
+    xy1: tuple[float, float]
+    xy2: tuple[float, float]
+    coords1: str | Transform
+    coords2: str | Transform | None
+    axesA: Axes | None
+    axesB: Axes | None
+    def __init__(
+        self,
+        xyA: tuple[float, float],
+        xyB: tuple[float, float],
+        coordsA: str | Transform,
+        coordsB: str | Transform | None = ...,
+        *,
+        axesA: Axes | None = ...,
+        axesB: Axes | None = ...,
+        arrowstyle: str | ArrowStyle = ...,
+        connectionstyle: str | ConnectionStyle = ...,
+        patchA: Patch | None = ...,
+        patchB: Patch | None = ...,
+        shrinkA: float = ...,
+        shrinkB: float = ...,
+        mutation_scale: float = ...,
+        mutation_aspect: float | None = ...,
+        clip_on: bool = ...,
+        **kwargs,
+    ) -> None: ...
+    def set_annotation_clip(self, b: bool | None) -> None: ...
+    def get_annotation_clip(self) -> bool | None: ...
diff --git a/lib/python3.12/site-packages/matplotlib/path.py b/lib/python3.12/site-packages/matplotlib/path.py
new file mode 100644
index 0000000000000000000000000000000000000000..3fa3fb262e27a31a116834a356314799d4539dae
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/path.py
@@ -0,0 +1,1114 @@
+r"""
+A module for dealing with the polylines used throughout Matplotlib.
+
+The primary class for polyline handling in Matplotlib is `Path`.  Almost all
+vector drawing makes use of `Path`\s somewhere in the drawing pipeline.
+
+Whilst a `Path` instance itself cannot be drawn, some `.Artist` subclasses,
+such as `.PathPatch` and `.PathCollection`, can be used for convenient `Path`
+visualisation.
+"""
+
+import copy
+from functools import lru_cache
+from weakref import WeakValueDictionary
+
+import numpy as np
+
+import matplotlib as mpl
+from . import _api, _path
+from .cbook import _to_unmasked_float_array, simple_linear_interpolation
+from .bezier import BezierSegment
+
+
+class Path:
+    """
+    A series of possibly disconnected, possibly closed, line and curve
+    segments.
+
+    The underlying storage is made up of two parallel numpy arrays:
+
+    - *vertices*: an (N, 2) float array of vertices
+    - *codes*: an N-length `numpy.uint8` array of path codes, or None
+
+    These two arrays always have the same length in the first
+    dimension.  For example, to represent a cubic curve, you must
+    provide three vertices and three `CURVE4` codes.
+
+    The code types are:
+
+    - `STOP`   :  1 vertex (ignored)
+        A marker for the end of the entire path (currently not required and
+        ignored)
+
+    - `MOVETO` :  1 vertex
+        Pick up the pen and move to the given vertex.
+
+    - `LINETO` :  1 vertex
+        Draw a line from the current position to the given vertex.
+
+    - `CURVE3` :  1 control point, 1 endpoint
+        Draw a quadratic Bézier curve from the current position, with the given
+        control point, to the given end point.
+
+    - `CURVE4` :  2 control points, 1 endpoint
+        Draw a cubic Bézier curve from the current position, with the given
+        control points, to the given end point.
+
+    - `CLOSEPOLY` : 1 vertex (ignored)
+        Draw a line segment to the start point of the current polyline.
+
+    If *codes* is None, it is interpreted as a `MOVETO` followed by a series
+    of `LINETO`.
+
+    Users of Path objects should not access the vertices and codes arrays
+    directly.  Instead, they should use `iter_segments` or `cleaned` to get the
+    vertex/code pairs.  This helps, in particular, to consistently handle the
+    case of *codes* being None.
+
+    Some behavior of Path objects can be controlled by rcParams. See the
+    rcParams whose keys start with 'path.'.
+
+    .. note::
+
+        The vertices and codes arrays should be treated as
+        immutable -- there are a number of optimizations and assumptions
+        made up front in the constructor that will not change when the
+        data changes.
+    """
+
+    code_type = np.uint8
+
+    # Path codes
+    STOP = code_type(0)         # 1 vertex
+    MOVETO = code_type(1)       # 1 vertex
+    LINETO = code_type(2)       # 1 vertex
+    CURVE3 = code_type(3)       # 2 vertices
+    CURVE4 = code_type(4)       # 3 vertices
+    CLOSEPOLY = code_type(79)   # 1 vertex
+
+    #: A dictionary mapping Path codes to the number of vertices that the
+    #: code expects.
+    NUM_VERTICES_FOR_CODE = {STOP: 1,
+                             MOVETO: 1,
+                             LINETO: 1,
+                             CURVE3: 2,
+                             CURVE4: 3,
+                             CLOSEPOLY: 1}
+
+    def __init__(self, vertices, codes=None, _interpolation_steps=1,
+                 closed=False, readonly=False):
+        """
+        Create a new path with the given vertices and codes.
+
+        Parameters
+        ----------
+        vertices : (N, 2) array-like
+            The path vertices, as an array, masked array or sequence of pairs.
+            Masked values, if any, will be converted to NaNs, which are then
+            handled correctly by the Agg PathIterator and other consumers of
+            path data, such as :meth:`iter_segments`.
+        codes : array-like or None, optional
+            N-length array of integers representing the codes of the path.
+            If not None, codes must be the same length as vertices.
+            If None, *vertices* will be treated as a series of line segments.
+        _interpolation_steps : int, optional
+            Used as a hint to certain projections, such as Polar, that this
+            path should be linearly interpolated immediately before drawing.
+            This attribute is primarily an implementation detail and is not
+            intended for public use.
+        closed : bool, optional
+            If *codes* is None and closed is True, vertices will be treated as
+            line segments of a closed polygon.  Note that the last vertex will
+            then be ignored (as the corresponding code will be set to
+            `CLOSEPOLY`).
+        readonly : bool, optional
+            Makes the path behave in an immutable way and sets the vertices
+            and codes as read-only arrays.
+        """
+        vertices = _to_unmasked_float_array(vertices)
+        _api.check_shape((None, 2), vertices=vertices)
+
+        if codes is not None and len(vertices):
+            codes = np.asarray(codes, self.code_type)
+            if codes.ndim != 1 or len(codes) != len(vertices):
+                raise ValueError("'codes' must be a 1D list or array with the "
+                                 "same length of 'vertices'. "
+                                 f"Your vertices have shape {vertices.shape} "
+                                 f"but your codes have shape {codes.shape}")
+            if len(codes) and codes[0] != self.MOVETO:
+                raise ValueError("The first element of 'code' must be equal "
+                                 f"to 'MOVETO' ({self.MOVETO}).  "
+                                 f"Your first code is {codes[0]}")
+        elif closed and len(vertices):
+            codes = np.empty(len(vertices), dtype=self.code_type)
+            codes[0] = self.MOVETO
+            codes[1:-1] = self.LINETO
+            codes[-1] = self.CLOSEPOLY
+
+        self._vertices = vertices
+        self._codes = codes
+        self._interpolation_steps = _interpolation_steps
+        self._update_values()
+
+        if readonly:
+            self._vertices.flags.writeable = False
+            if self._codes is not None:
+                self._codes.flags.writeable = False
+            self._readonly = True
+        else:
+            self._readonly = False
+
+    @classmethod
+    def _fast_from_codes_and_verts(cls, verts, codes, internals_from=None):
+        """
+        Create a Path instance without the expense of calling the constructor.
+
+        Parameters
+        ----------
+        verts : array-like
+        codes : array
+        internals_from : Path or None
+            If not None, another `Path` from which the attributes
+            ``should_simplify``, ``simplify_threshold``, and
+            ``interpolation_steps`` will be copied.  Note that ``readonly`` is
+            never copied, and always set to ``False`` by this constructor.
+        """
+        pth = cls.__new__(cls)
+        pth._vertices = _to_unmasked_float_array(verts)
+        pth._codes = codes
+        pth._readonly = False
+        if internals_from is not None:
+            pth._should_simplify = internals_from._should_simplify
+            pth._simplify_threshold = internals_from._simplify_threshold
+            pth._interpolation_steps = internals_from._interpolation_steps
+        else:
+            pth._should_simplify = True
+            pth._simplify_threshold = mpl.rcParams['path.simplify_threshold']
+            pth._interpolation_steps = 1
+        return pth
+
+    @classmethod
+    def _create_closed(cls, vertices):
+        """
+        Create a closed polygonal path going through *vertices*.
+
+        Unlike ``Path(..., closed=True)``, *vertices* should **not** end with
+        an entry for the CLOSEPATH; this entry is added by `._create_closed`.
+        """
+        v = _to_unmasked_float_array(vertices)
+        return cls(np.concatenate([v, v[:1]]), closed=True)
+
+    def _update_values(self):
+        self._simplify_threshold = mpl.rcParams['path.simplify_threshold']
+        self._should_simplify = (
+            self._simplify_threshold > 0 and
+            mpl.rcParams['path.simplify'] and
+            len(self._vertices) >= 128 and
+            (self._codes is None or np.all(self._codes <= Path.LINETO))
+        )
+
+    @property
+    def vertices(self):
+        """The vertices of the `Path` as an (N, 2) array."""
+        return self._vertices
+
+    @vertices.setter
+    def vertices(self, vertices):
+        if self._readonly:
+            raise AttributeError("Can't set vertices on a readonly Path")
+        self._vertices = vertices
+        self._update_values()
+
+    @property
+    def codes(self):
+        """
+        The list of codes in the `Path` as a 1D array.
+
+        Each code is one of `STOP`, `MOVETO`, `LINETO`, `CURVE3`, `CURVE4` or
+        `CLOSEPOLY`.  For codes that correspond to more than one vertex
+        (`CURVE3` and `CURVE4`), that code will be repeated so that the length
+        of `vertices` and `codes` is always the same.
+        """
+        return self._codes
+
+    @codes.setter
+    def codes(self, codes):
+        if self._readonly:
+            raise AttributeError("Can't set codes on a readonly Path")
+        self._codes = codes
+        self._update_values()
+
+    @property
+    def simplify_threshold(self):
+        """
+        The fraction of a pixel difference below which vertices will
+        be simplified out.
+        """
+        return self._simplify_threshold
+
+    @simplify_threshold.setter
+    def simplify_threshold(self, threshold):
+        self._simplify_threshold = threshold
+
+    @property
+    def should_simplify(self):
+        """
+        `True` if the vertices array should be simplified.
+        """
+        return self._should_simplify
+
+    @should_simplify.setter
+    def should_simplify(self, should_simplify):
+        self._should_simplify = should_simplify
+
+    @property
+    def readonly(self):
+        """
+        `True` if the `Path` is read-only.
+        """
+        return self._readonly
+
+    def copy(self):
+        """
+        Return a shallow copy of the `Path`, which will share the
+        vertices and codes with the source `Path`.
+        """
+        return copy.copy(self)
+
+    def __deepcopy__(self, memo=None):
+        """
+        Return a deepcopy of the `Path`.  The `Path` will not be
+        readonly, even if the source `Path` is.
+        """
+        # Deepcopying arrays (vertices, codes) strips the writeable=False flag.
+        p = copy.deepcopy(super(), memo)
+        p._readonly = False
+        return p
+
+    deepcopy = __deepcopy__
+
+    @classmethod
+    def make_compound_path_from_polys(cls, XY):
+        """
+        Make a compound `Path` object to draw a number of polygons with equal
+        numbers of sides.
+
+        .. plot:: gallery/misc/histogram_path.py
+
+        Parameters
+        ----------
+        XY : (numpolys, numsides, 2) array
+        """
+        # for each poly: 1 for the MOVETO, (numsides-1) for the LINETO, 1 for
+        # the CLOSEPOLY; the vert for the closepoly is ignored but we still
+        # need it to keep the codes aligned with the vertices
+        numpolys, numsides, two = XY.shape
+        if two != 2:
+            raise ValueError("The third dimension of 'XY' must be 2")
+        stride = numsides + 1
+        nverts = numpolys * stride
+        verts = np.zeros((nverts, 2))
+        codes = np.full(nverts, cls.LINETO, dtype=cls.code_type)
+        codes[0::stride] = cls.MOVETO
+        codes[numsides::stride] = cls.CLOSEPOLY
+        for i in range(numsides):
+            verts[i::stride] = XY[:, i]
+        return cls(verts, codes)
+
+    @classmethod
+    def make_compound_path(cls, *args):
+        r"""
+        Concatenate a list of `Path`\s into a single `Path`, removing all `STOP`\s.
+        """
+        if not args:
+            return Path(np.empty([0, 2], dtype=np.float32))
+        vertices = np.concatenate([path.vertices for path in args])
+        codes = np.empty(len(vertices), dtype=cls.code_type)
+        i = 0
+        for path in args:
+            size = len(path.vertices)
+            if path.codes is None:
+                if size:
+                    codes[i] = cls.MOVETO
+                    codes[i+1:i+size] = cls.LINETO
+            else:
+                codes[i:i+size] = path.codes
+            i += size
+        not_stop_mask = codes != cls.STOP  # Remove STOPs, as internal STOPs are a bug.
+        return cls(vertices[not_stop_mask], codes[not_stop_mask])
+
+    def __repr__(self):
+        return f"Path({self.vertices!r}, {self.codes!r})"
+
+    def __len__(self):
+        return len(self.vertices)
+
+    def iter_segments(self, transform=None, remove_nans=True, clip=None,
+                      snap=False, stroke_width=1.0, simplify=None,
+                      curves=True, sketch=None):
+        """
+        Iterate over all curve segments in the path.
+
+        Each iteration returns a pair ``(vertices, code)``, where ``vertices``
+        is a sequence of 1-3 coordinate pairs, and ``code`` is a `Path` code.
+
+        Additionally, this method can provide a number of standard cleanups and
+        conversions to the path.
+
+        Parameters
+        ----------
+        transform : None or :class:`~matplotlib.transforms.Transform`
+            If not None, the given affine transformation will be applied to the
+            path.
+        remove_nans : bool, optional
+            Whether to remove all NaNs from the path and skip over them using
+            MOVETO commands.
+        clip : None or (float, float, float, float), optional
+            If not None, must be a four-tuple (x1, y1, x2, y2)
+            defining a rectangle in which to clip the path.
+        snap : None or bool, optional
+            If True, snap all nodes to pixels; if False, don't snap them.
+            If None, snap if the path contains only segments
+            parallel to the x or y axes, and no more than 1024 of them.
+        stroke_width : float, optional
+            The width of the stroke being drawn (used for path snapping).
+        simplify : None or bool, optional
+            Whether to simplify the path by removing vertices
+            that do not affect its appearance.  If None, use the
+            :attr:`should_simplify` attribute.  See also :rc:`path.simplify`
+            and :rc:`path.simplify_threshold`.
+        curves : bool, optional
+            If True, curve segments will be returned as curve segments.
+            If False, all curves will be converted to line segments.
+        sketch : None or sequence, optional
+            If not None, must be a 3-tuple of the form
+            (scale, length, randomness), representing the sketch parameters.
+        """
+        if not len(self):
+            return
+
+        cleaned = self.cleaned(transform=transform,
+                               remove_nans=remove_nans, clip=clip,
+                               snap=snap, stroke_width=stroke_width,
+                               simplify=simplify, curves=curves,
+                               sketch=sketch)
+
+        # Cache these object lookups for performance in the loop.
+        NUM_VERTICES_FOR_CODE = self.NUM_VERTICES_FOR_CODE
+        STOP = self.STOP
+
+        vertices = iter(cleaned.vertices)
+        codes = iter(cleaned.codes)
+        for curr_vertices, code in zip(vertices, codes):
+            if code == STOP:
+                break
+            extra_vertices = NUM_VERTICES_FOR_CODE[code] - 1
+            if extra_vertices:
+                for i in range(extra_vertices):
+                    next(codes)
+                    curr_vertices = np.append(curr_vertices, next(vertices))
+            yield curr_vertices, code
+
+    def iter_bezier(self, **kwargs):
+        """
+        Iterate over each Bézier curve (lines included) in a `Path`.
+
+        Parameters
+        ----------
+        **kwargs
+            Forwarded to `.iter_segments`.
+
+        Yields
+        ------
+        B : `~matplotlib.bezier.BezierSegment`
+            The Bézier curves that make up the current path. Note in particular
+            that freestanding points are Bézier curves of order 0, and lines
+            are Bézier curves of order 1 (with two control points).
+        code : `~matplotlib.path.Path.code_type`
+            The code describing what kind of curve is being returned.
+            `MOVETO`, `LINETO`, `CURVE3`, and `CURVE4` correspond to
+            Bézier curves with 1, 2, 3, and 4 control points (respectively).
+            `CLOSEPOLY` is a `LINETO` with the control points correctly
+            chosen based on the start/end points of the current stroke.
+        """
+        first_vert = None
+        prev_vert = None
+        for verts, code in self.iter_segments(**kwargs):
+            if first_vert is None:
+                if code != Path.MOVETO:
+                    raise ValueError("Malformed path, must start with MOVETO.")
+            if code == Path.MOVETO:  # a point is like "CURVE1"
+                first_vert = verts
+                yield BezierSegment(np.array([first_vert])), code
+            elif code == Path.LINETO:  # "CURVE2"
+                yield BezierSegment(np.array([prev_vert, verts])), code
+            elif code == Path.CURVE3:
+                yield BezierSegment(np.array([prev_vert, verts[:2],
+                                              verts[2:]])), code
+            elif code == Path.CURVE4:
+                yield BezierSegment(np.array([prev_vert, verts[:2],
+                                              verts[2:4], verts[4:]])), code
+            elif code == Path.CLOSEPOLY:
+                yield BezierSegment(np.array([prev_vert, first_vert])), code
+            elif code == Path.STOP:
+                return
+            else:
+                raise ValueError(f"Invalid Path.code_type: {code}")
+            prev_vert = verts[-2:]
+
+    def _iter_connected_components(self):
+        """Return subpaths split at MOVETOs."""
+        if self.codes is None:
+            yield self
+        else:
+            idxs = np.append((self.codes == Path.MOVETO).nonzero()[0], len(self.codes))
+            for sl in map(slice, idxs, idxs[1:]):
+                yield Path._fast_from_codes_and_verts(
+                    self.vertices[sl], self.codes[sl], self)
+
+    def cleaned(self, transform=None, remove_nans=False, clip=None,
+                *, simplify=False, curves=False,
+                stroke_width=1.0, snap=False, sketch=None):
+        """
+        Return a new `Path` with vertices and codes cleaned according to the
+        parameters.
+
+        See Also
+        --------
+        Path.iter_segments : for details of the keyword arguments.
+        """
+        vertices, codes = _path.cleanup_path(
+            self, transform, remove_nans, clip, snap, stroke_width, simplify,
+            curves, sketch)
+        pth = Path._fast_from_codes_and_verts(vertices, codes, self)
+        if not simplify:
+            pth._should_simplify = False
+        return pth
+
+    def transformed(self, transform):
+        """
+        Return a transformed copy of the path.
+
+        See Also
+        --------
+        matplotlib.transforms.TransformedPath
+            A specialized path class that will cache the transformed result and
+            automatically update when the transform changes.
+        """
+        return Path(transform.transform(self.vertices), self.codes,
+                    self._interpolation_steps)
+
+    def contains_point(self, point, transform=None, radius=0.0):
+        """
+        Return whether the area enclosed by the path contains the given point.
+
+        The path is always treated as closed; i.e. if the last code is not
+        `CLOSEPOLY` an implicit segment connecting the last vertex to the first
+        vertex is assumed.
+
+        Parameters
+        ----------
+        point : (float, float)
+            The point (x, y) to check.
+        transform : `~matplotlib.transforms.Transform`, optional
+            If not ``None``, *point* will be compared to ``self`` transformed
+            by *transform*; i.e. for a correct check, *transform* should
+            transform the path into the coordinate system of *point*.
+        radius : float, default: 0
+            Additional margin on the path in coordinates of *point*.
+            The path is extended tangentially by *radius/2*; i.e. if you would
+            draw the path with a linewidth of *radius*, all points on the line
+            would still be considered to be contained in the area. Conversely,
+            negative values shrink the area: Points on the imaginary line
+            will be considered outside the area.
+
+        Returns
+        -------
+        bool
+
+        Notes
+        -----
+        The current algorithm has some limitations:
+
+        - The result is undefined for points exactly at the boundary
+          (i.e. at the path shifted by *radius/2*).
+        - The result is undefined if there is no enclosed area, i.e. all
+          vertices are on a straight line.
+        - If bounding lines start to cross each other due to *radius* shift,
+          the result is not guaranteed to be correct.
+        """
+        if transform is not None:
+            transform = transform.frozen()
+        # `point_in_path` does not handle nonlinear transforms, so we
+        # transform the path ourselves.  If *transform* is affine, letting
+        # `point_in_path` handle the transform avoids allocating an extra
+        # buffer.
+        if transform and not transform.is_affine:
+            self = transform.transform_path(self)
+            transform = None
+        return _path.point_in_path(point[0], point[1], radius, self, transform)
+
+    def contains_points(self, points, transform=None, radius=0.0):
+        """
+        Return whether the area enclosed by the path contains the given points.
+
+        The path is always treated as closed; i.e. if the last code is not
+        `CLOSEPOLY` an implicit segment connecting the last vertex to the first
+        vertex is assumed.
+
+        Parameters
+        ----------
+        points : (N, 2) array
+            The points to check. Columns contain x and y values.
+        transform : `~matplotlib.transforms.Transform`, optional
+            If not ``None``, *points* will be compared to ``self`` transformed
+            by *transform*; i.e. for a correct check, *transform* should
+            transform the path into the coordinate system of *points*.
+        radius : float, default: 0
+            Additional margin on the path in coordinates of *points*.
+            The path is extended tangentially by *radius/2*; i.e. if you would
+            draw the path with a linewidth of *radius*, all points on the line
+            would still be considered to be contained in the area. Conversely,
+            negative values shrink the area: Points on the imaginary line
+            will be considered outside the area.
+
+        Returns
+        -------
+        length-N bool array
+
+        Notes
+        -----
+        The current algorithm has some limitations:
+
+        - The result is undefined for points exactly at the boundary
+          (i.e. at the path shifted by *radius/2*).
+        - The result is undefined if there is no enclosed area, i.e. all
+          vertices are on a straight line.
+        - If bounding lines start to cross each other due to *radius* shift,
+          the result is not guaranteed to be correct.
+        """
+        if transform is not None:
+            transform = transform.frozen()
+        result = _path.points_in_path(points, radius, self, transform)
+        return result.astype('bool')
+
+    def contains_path(self, path, transform=None):
+        """
+        Return whether this (closed) path completely contains the given path.
+
+        If *transform* is not ``None``, the path will be transformed before
+        checking for containment.
+        """
+        if transform is not None:
+            transform = transform.frozen()
+        return _path.path_in_path(self, None, path, transform)
+
+    def get_extents(self, transform=None, **kwargs):
+        """
+        Get Bbox of the path.
+
+        Parameters
+        ----------
+        transform : `~matplotlib.transforms.Transform`, optional
+            Transform to apply to path before computing extents, if any.
+        **kwargs
+            Forwarded to `.iter_bezier`.
+
+        Returns
+        -------
+        matplotlib.transforms.Bbox
+            The extents of the path Bbox([[xmin, ymin], [xmax, ymax]])
+        """
+        from .transforms import Bbox
+        if transform is not None:
+            self = transform.transform_path(self)
+        if self.codes is None:
+            xys = self.vertices
+        elif len(np.intersect1d(self.codes, [Path.CURVE3, Path.CURVE4])) == 0:
+            # Optimization for the straight line case.
+            # Instead of iterating through each curve, consider
+            # each line segment's end-points
+            # (recall that STOP and CLOSEPOLY vertices are ignored)
+            xys = self.vertices[np.isin(self.codes,
+                                        [Path.MOVETO, Path.LINETO])]
+        else:
+            xys = []
+            for curve, code in self.iter_bezier(**kwargs):
+                # places where the derivative is zero can be extrema
+                _, dzeros = curve.axis_aligned_extrema()
+                # as can the ends of the curve
+                xys.append(curve([0, *dzeros, 1]))
+            xys = np.concatenate(xys)
+        if len(xys):
+            return Bbox([xys.min(axis=0), xys.max(axis=0)])
+        else:
+            return Bbox.null()
+
+    def intersects_path(self, other, filled=True):
+        """
+        Return whether if this path intersects another given path.
+
+        If *filled* is True, then this also returns True if one path completely
+        encloses the other (i.e., the paths are treated as filled).
+        """
+        return _path.path_intersects_path(self, other, filled)
+
+    def intersects_bbox(self, bbox, filled=True):
+        """
+        Return whether this path intersects a given `~.transforms.Bbox`.
+
+        If *filled* is True, then this also returns True if the path completely
+        encloses the `.Bbox` (i.e., the path is treated as filled).
+
+        The bounding box is always considered filled.
+        """
+        return _path.path_intersects_rectangle(
+            self, bbox.x0, bbox.y0, bbox.x1, bbox.y1, filled)
+
+    def interpolated(self, steps):
+        """
+        Return a new path with each segment divided into *steps* parts.
+
+        Codes other than `LINETO`, `MOVETO`, and `CLOSEPOLY` are not handled correctly.
+
+        Parameters
+        ----------
+        steps : int
+            The number of segments in the new path for each in the original.
+
+        Returns
+        -------
+        Path
+            The interpolated path.
+        """
+        if steps == 1 or len(self) == 0:
+            return self
+
+        if self.codes is not None and self.MOVETO in self.codes[1:]:
+            return self.make_compound_path(
+                *(p.interpolated(steps) for p in self._iter_connected_components()))
+
+        if self.codes is not None and self.CLOSEPOLY in self.codes and not np.all(
+                self.vertices[self.codes == self.CLOSEPOLY] == self.vertices[0]):
+            vertices = self.vertices.copy()
+            vertices[self.codes == self.CLOSEPOLY] = vertices[0]
+        else:
+            vertices = self.vertices
+
+        vertices = simple_linear_interpolation(vertices, steps)
+        codes = self.codes
+        if codes is not None:
+            new_codes = np.full((len(codes) - 1) * steps + 1, Path.LINETO,
+                                dtype=self.code_type)
+            new_codes[0::steps] = codes
+        else:
+            new_codes = None
+        return Path(vertices, new_codes)
+
+    def to_polygons(self, transform=None, width=0, height=0, closed_only=True):
+        """
+        Convert this path to a list of polygons or polylines.  Each
+        polygon/polyline is an (N, 2) array of vertices.  In other words,
+        each polygon has no `MOVETO` instructions or curves.  This
+        is useful for displaying in backends that do not support
+        compound paths or Bézier curves.
+
+        If *width* and *height* are both non-zero then the lines will
+        be simplified so that vertices outside of (0, 0), (width,
+        height) will be clipped.
+
+        The resulting polygons will be simplified if the
+        :attr:`Path.should_simplify` attribute of the path is `True`.
+
+        If *closed_only* is `True` (default), only closed polygons,
+        with the last point being the same as the first point, will be
+        returned.  Any unclosed polylines in the path will be
+        explicitly closed.  If *closed_only* is `False`, any unclosed
+        polygons in the path will be returned as unclosed polygons,
+        and the closed polygons will be returned explicitly closed by
+        setting the last point to the same as the first point.
+        """
+        if len(self.vertices) == 0:
+            return []
+
+        if transform is not None:
+            transform = transform.frozen()
+
+        if self.codes is None and (width == 0 or height == 0):
+            vertices = self.vertices
+            if closed_only:
+                if len(vertices) < 3:
+                    return []
+                elif np.any(vertices[0] != vertices[-1]):
+                    vertices = [*vertices, vertices[0]]
+
+            if transform is None:
+                return [vertices]
+            else:
+                return [transform.transform(vertices)]
+
+        # Deal with the case where there are curves and/or multiple
+        # subpaths (using extension code)
+        return _path.convert_path_to_polygons(
+            self, transform, width, height, closed_only)
+
+    _unit_rectangle = None
+
+    @classmethod
+    def unit_rectangle(cls):
+        """
+        Return a `Path` instance of the unit rectangle from (0, 0) to (1, 1).
+        """
+        if cls._unit_rectangle is None:
+            cls._unit_rectangle = cls([[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]],
+                                      closed=True, readonly=True)
+        return cls._unit_rectangle
+
+    _unit_regular_polygons = WeakValueDictionary()
+
+    @classmethod
+    def unit_regular_polygon(cls, numVertices):
+        """
+        Return a :class:`Path` instance for a unit regular polygon with the
+        given *numVertices* such that the circumscribing circle has radius 1.0,
+        centered at (0, 0).
+        """
+        if numVertices <= 16:
+            path = cls._unit_regular_polygons.get(numVertices)
+        else:
+            path = None
+        if path is None:
+            theta = ((2 * np.pi / numVertices) * np.arange(numVertices + 1)
+                     # This initial rotation is to make sure the polygon always
+                     # "points-up".
+                     + np.pi / 2)
+            verts = np.column_stack((np.cos(theta), np.sin(theta)))
+            path = cls(verts, closed=True, readonly=True)
+            if numVertices <= 16:
+                cls._unit_regular_polygons[numVertices] = path
+        return path
+
+    _unit_regular_stars = WeakValueDictionary()
+
+    @classmethod
+    def unit_regular_star(cls, numVertices, innerCircle=0.5):
+        """
+        Return a :class:`Path` for a unit regular star with the given
+        numVertices and radius of 1.0, centered at (0, 0).
+        """
+        if numVertices <= 16:
+            path = cls._unit_regular_stars.get((numVertices, innerCircle))
+        else:
+            path = None
+        if path is None:
+            ns2 = numVertices * 2
+            theta = (2*np.pi/ns2 * np.arange(ns2 + 1))
+            # This initial rotation is to make sure the polygon always
+            # "points-up"
+            theta += np.pi / 2.0
+            r = np.ones(ns2 + 1)
+            r[1::2] = innerCircle
+            verts = (r * np.vstack((np.cos(theta), np.sin(theta)))).T
+            path = cls(verts, closed=True, readonly=True)
+            if numVertices <= 16:
+                cls._unit_regular_stars[(numVertices, innerCircle)] = path
+        return path
+
+    @classmethod
+    def unit_regular_asterisk(cls, numVertices):
+        """
+        Return a :class:`Path` for a unit regular asterisk with the given
+        numVertices and radius of 1.0, centered at (0, 0).
+        """
+        return cls.unit_regular_star(numVertices, 0.0)
+
+    _unit_circle = None
+
+    @classmethod
+    def unit_circle(cls):
+        """
+        Return the readonly :class:`Path` of the unit circle.
+
+        For most cases, :func:`Path.circle` will be what you want.
+        """
+        if cls._unit_circle is None:
+            cls._unit_circle = cls.circle(center=(0, 0), radius=1,
+                                          readonly=True)
+        return cls._unit_circle
+
+    @classmethod
+    def circle(cls, center=(0., 0.), radius=1., readonly=False):
+        """
+        Return a `Path` representing a circle of a given radius and center.
+
+        Parameters
+        ----------
+        center : (float, float), default: (0, 0)
+            The center of the circle.
+        radius : float, default: 1
+            The radius of the circle.
+        readonly : bool
+            Whether the created path should have the "readonly" argument
+            set when creating the Path instance.
+
+        Notes
+        -----
+        The circle is approximated using 8 cubic Bézier curves, as described in
+
+          Lancaster, Don.  `Approximating a Circle or an Ellipse Using Four
+          Bezier Cubic Splines <https://www.tinaja.com/glib/ellipse4.pdf>`_.
+        """
+        MAGIC = 0.2652031
+        SQRTHALF = np.sqrt(0.5)
+        MAGIC45 = SQRTHALF * MAGIC
+
+        vertices = np.array([[0.0, -1.0],
+
+                             [MAGIC, -1.0],
+                             [SQRTHALF-MAGIC45, -SQRTHALF-MAGIC45],
+                             [SQRTHALF, -SQRTHALF],
+
+                             [SQRTHALF+MAGIC45, -SQRTHALF+MAGIC45],
+                             [1.0, -MAGIC],
+                             [1.0, 0.0],
+
+                             [1.0, MAGIC],
+                             [SQRTHALF+MAGIC45, SQRTHALF-MAGIC45],
+                             [SQRTHALF, SQRTHALF],
+
+                             [SQRTHALF-MAGIC45, SQRTHALF+MAGIC45],
+                             [MAGIC, 1.0],
+                             [0.0, 1.0],
+
+                             [-MAGIC, 1.0],
+                             [-SQRTHALF+MAGIC45, SQRTHALF+MAGIC45],
+                             [-SQRTHALF, SQRTHALF],
+
+                             [-SQRTHALF-MAGIC45, SQRTHALF-MAGIC45],
+                             [-1.0, MAGIC],
+                             [-1.0, 0.0],
+
+                             [-1.0, -MAGIC],
+                             [-SQRTHALF-MAGIC45, -SQRTHALF+MAGIC45],
+                             [-SQRTHALF, -SQRTHALF],
+
+                             [-SQRTHALF+MAGIC45, -SQRTHALF-MAGIC45],
+                             [-MAGIC, -1.0],
+                             [0.0, -1.0],
+
+                             [0.0, -1.0]],
+                            dtype=float)
+
+        codes = [cls.CURVE4] * 26
+        codes[0] = cls.MOVETO
+        codes[-1] = cls.CLOSEPOLY
+        return Path(vertices * radius + center, codes, readonly=readonly)
+
+    _unit_circle_righthalf = None
+
+    @classmethod
+    def unit_circle_righthalf(cls):
+        """
+        Return a `Path` of the right half of a unit circle.
+
+        See `Path.circle` for the reference on the approximation used.
+        """
+        if cls._unit_circle_righthalf is None:
+            MAGIC = 0.2652031
+            SQRTHALF = np.sqrt(0.5)
+            MAGIC45 = SQRTHALF * MAGIC
+
+            vertices = np.array(
+                [[0.0, -1.0],
+
+                 [MAGIC, -1.0],
+                 [SQRTHALF-MAGIC45, -SQRTHALF-MAGIC45],
+                 [SQRTHALF, -SQRTHALF],
+
+                 [SQRTHALF+MAGIC45, -SQRTHALF+MAGIC45],
+                 [1.0, -MAGIC],
+                 [1.0, 0.0],
+
+                 [1.0, MAGIC],
+                 [SQRTHALF+MAGIC45, SQRTHALF-MAGIC45],
+                 [SQRTHALF, SQRTHALF],
+
+                 [SQRTHALF-MAGIC45, SQRTHALF+MAGIC45],
+                 [MAGIC, 1.0],
+                 [0.0, 1.0],
+
+                 [0.0, -1.0]],
+
+                float)
+
+            codes = np.full(14, cls.CURVE4, dtype=cls.code_type)
+            codes[0] = cls.MOVETO
+            codes[-1] = cls.CLOSEPOLY
+
+            cls._unit_circle_righthalf = cls(vertices, codes, readonly=True)
+        return cls._unit_circle_righthalf
+
+    @classmethod
+    def arc(cls, theta1, theta2, n=None, is_wedge=False):
+        """
+        Return a `Path` for the unit circle arc from angles *theta1* to
+        *theta2* (in degrees).
+
+        *theta2* is unwrapped to produce the shortest arc within 360 degrees.
+        That is, if *theta2* > *theta1* + 360, the arc will be from *theta1* to
+        *theta2* - 360 and not a full circle plus some extra overlap.
+
+        If *n* is provided, it is the number of spline segments to make.
+        If *n* is not provided, the number of spline segments is
+        determined based on the delta between *theta1* and *theta2*.
+
+           Masionobe, L.  2003.  `Drawing an elliptical arc using
+           polylines, quadratic or cubic Bezier curves
+           <https://web.archive.org/web/20190318044212/http://www.spaceroots.org/documents/ellipse/index.html>`_.
+        """
+        halfpi = np.pi * 0.5
+
+        eta1 = theta1
+        eta2 = theta2 - 360 * np.floor((theta2 - theta1) / 360)
+        # Ensure 2pi range is not flattened to 0 due to floating-point errors,
+        # but don't try to expand existing 0 range.
+        if theta2 != theta1 and eta2 <= eta1:
+            eta2 += 360
+        eta1, eta2 = np.deg2rad([eta1, eta2])
+
+        # number of curve segments to make
+        if n is None:
+            n = int(2 ** np.ceil((eta2 - eta1) / halfpi))
+        if n < 1:
+            raise ValueError("n must be >= 1 or None")
+
+        deta = (eta2 - eta1) / n
+        t = np.tan(0.5 * deta)
+        alpha = np.sin(deta) * (np.sqrt(4.0 + 3.0 * t * t) - 1) / 3.0
+
+        steps = np.linspace(eta1, eta2, n + 1, True)
+        cos_eta = np.cos(steps)
+        sin_eta = np.sin(steps)
+
+        xA = cos_eta[:-1]
+        yA = sin_eta[:-1]
+        xA_dot = -yA
+        yA_dot = xA
+
+        xB = cos_eta[1:]
+        yB = sin_eta[1:]
+        xB_dot = -yB
+        yB_dot = xB
+
+        if is_wedge:
+            length = n * 3 + 4
+            vertices = np.zeros((length, 2), float)
+            codes = np.full(length, cls.CURVE4, dtype=cls.code_type)
+            vertices[1] = [xA[0], yA[0]]
+            codes[0:2] = [cls.MOVETO, cls.LINETO]
+            codes[-2:] = [cls.LINETO, cls.CLOSEPOLY]
+            vertex_offset = 2
+            end = length - 2
+        else:
+            length = n * 3 + 1
+            vertices = np.empty((length, 2), float)
+            codes = np.full(length, cls.CURVE4, dtype=cls.code_type)
+            vertices[0] = [xA[0], yA[0]]
+            codes[0] = cls.MOVETO
+            vertex_offset = 1
+            end = length
+
+        vertices[vertex_offset:end:3, 0] = xA + alpha * xA_dot
+        vertices[vertex_offset:end:3, 1] = yA + alpha * yA_dot
+        vertices[vertex_offset+1:end:3, 0] = xB - alpha * xB_dot
+        vertices[vertex_offset+1:end:3, 1] = yB - alpha * yB_dot
+        vertices[vertex_offset+2:end:3, 0] = xB
+        vertices[vertex_offset+2:end:3, 1] = yB
+
+        return cls(vertices, codes, readonly=True)
+
+    @classmethod
+    def wedge(cls, theta1, theta2, n=None):
+        """
+        Return a `Path` for the unit circle wedge from angles *theta1* to
+        *theta2* (in degrees).
+
+        *theta2* is unwrapped to produce the shortest wedge within 360 degrees.
+        That is, if *theta2* > *theta1* + 360, the wedge will be from *theta1*
+        to *theta2* - 360 and not a full circle plus some extra overlap.
+
+        If *n* is provided, it is the number of spline segments to make.
+        If *n* is not provided, the number of spline segments is
+        determined based on the delta between *theta1* and *theta2*.
+
+        See `Path.arc` for the reference on the approximation used.
+        """
+        return cls.arc(theta1, theta2, n, True)
+
+    @staticmethod
+    @lru_cache(8)
+    def hatch(hatchpattern, density=6):
+        """
+        Given a hatch specifier, *hatchpattern*, generates a `Path` that
+        can be used in a repeated hatching pattern.  *density* is the
+        number of lines per unit square.
+        """
+        from matplotlib.hatch import get_path
+        return (get_path(hatchpattern, density)
+                if hatchpattern is not None else None)
+
+    def clip_to_bbox(self, bbox, inside=True):
+        """
+        Clip the path to the given bounding box.
+
+        The path must be made up of one or more closed polygons.  This
+        algorithm will not behave correctly for unclosed paths.
+
+        If *inside* is `True`, clip to the inside of the box, otherwise
+        to the outside of the box.
+        """
+        verts = _path.clip_path_to_rect(self, bbox, inside)
+        paths = [Path(poly) for poly in verts]
+        return self.make_compound_path(*paths)
+
+
+def get_path_collection_extents(
+        master_transform, paths, transforms, offsets, offset_transform):
+    r"""
+    Get bounding box of a `.PathCollection`\s internal objects.
+
+    That is, given a sequence of `Path`\s, `.Transform`\s objects, and offsets, as found
+    in a `.PathCollection`, return the bounding box that encapsulates all of them.
+
+    Parameters
+    ----------
+    master_transform : `~matplotlib.transforms.Transform`
+        Global transformation applied to all paths.
+    paths : list of `Path`
+    transforms : list of `~matplotlib.transforms.Affine2DBase`
+        If non-empty, this overrides *master_transform*.
+    offsets : (N, 2) array-like
+    offset_transform : `~matplotlib.transforms.Affine2DBase`
+        Transform applied to the offsets before offsetting the path.
+
+    Notes
+    -----
+    The way that *paths*, *transforms* and *offsets* are combined follows the same
+    method as for collections: each is iterated over independently, so if you have 3
+    paths (A, B, C), 2 transforms (α, β) and 1 offset (O), their combinations are as
+    follows:
+
+    - (A, α, O)
+    - (B, β, O)
+    - (C, α, O)
+    """
+    from .transforms import Bbox
+    if len(paths) == 0:
+        raise ValueError("No paths provided")
+    if len(offsets) == 0:
+        raise ValueError("No offsets provided")
+    extents, minpos = _path.get_path_collection_extents(
+        master_transform, paths, np.atleast_3d(transforms),
+        offsets, offset_transform)
+    return Bbox.from_extents(*extents, minpos=minpos)
diff --git a/lib/python3.12/site-packages/matplotlib/path.pyi b/lib/python3.12/site-packages/matplotlib/path.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..464fc6d9a912e359d1deb0f3bb71a8ac349cfb6a
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/path.pyi
@@ -0,0 +1,140 @@
+from .bezier import BezierSegment
+from .transforms import Affine2D, Transform, Bbox
+from collections.abc import Generator, Iterable, Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from typing import Any, overload
+
+class Path:
+    code_type: type[np.uint8]
+    STOP: np.uint8
+    MOVETO: np.uint8
+    LINETO: np.uint8
+    CURVE3: np.uint8
+    CURVE4: np.uint8
+    CLOSEPOLY: np.uint8
+    NUM_VERTICES_FOR_CODE: dict[np.uint8, int]
+
+    def __init__(
+        self,
+        vertices: ArrayLike,
+        codes: ArrayLike | None = ...,
+        _interpolation_steps: int = ...,
+        closed: bool = ...,
+        readonly: bool = ...,
+    ) -> None: ...
+    @property
+    def vertices(self) -> ArrayLike: ...
+    @vertices.setter
+    def vertices(self, vertices: ArrayLike) -> None: ...
+    @property
+    def codes(self) -> ArrayLike | None: ...
+    @codes.setter
+    def codes(self, codes: ArrayLike) -> None: ...
+    @property
+    def simplify_threshold(self) -> float: ...
+    @simplify_threshold.setter
+    def simplify_threshold(self, threshold: float) -> None: ...
+    @property
+    def should_simplify(self) -> bool: ...
+    @should_simplify.setter
+    def should_simplify(self, should_simplify: bool) -> None: ...
+    @property
+    def readonly(self) -> bool: ...
+    def copy(self) -> Path: ...
+    def __deepcopy__(self, memo: dict[int, Any] | None = ...) -> Path: ...
+    deepcopy = __deepcopy__
+
+    @classmethod
+    def make_compound_path_from_polys(cls, XY: ArrayLike) -> Path: ...
+    @classmethod
+    def make_compound_path(cls, *args: Path) -> Path: ...
+    def __len__(self) -> int: ...
+    def iter_segments(
+        self,
+        transform: Transform | None = ...,
+        remove_nans: bool = ...,
+        clip: tuple[float, float, float, float] | None = ...,
+        snap: bool | None = ...,
+        stroke_width: float = ...,
+        simplify: bool | None = ...,
+        curves: bool = ...,
+        sketch: tuple[float, float, float] | None = ...,
+    ) -> Generator[tuple[np.ndarray, np.uint8], None, None]: ...
+    def iter_bezier(self, **kwargs) -> Generator[BezierSegment, None, None]: ...
+    def cleaned(
+        self,
+        transform: Transform | None = ...,
+        remove_nans: bool = ...,
+        clip: tuple[float, float, float, float] | None = ...,
+        *,
+        simplify: bool | None = ...,
+        curves: bool = ...,
+        stroke_width: float = ...,
+        snap: bool | None = ...,
+        sketch: tuple[float, float, float] | None = ...
+    ) -> Path: ...
+    def transformed(self, transform: Transform) -> Path: ...
+    def contains_point(
+        self,
+        point: tuple[float, float],
+        transform: Transform | None = ...,
+        radius: float = ...,
+    ) -> bool: ...
+    def contains_points(
+        self, points: ArrayLike, transform: Transform | None = ..., radius: float = ...
+    ) -> np.ndarray: ...
+    def contains_path(self, path: Path, transform: Transform | None = ...) -> bool: ...
+    def get_extents(self, transform: Transform | None = ..., **kwargs) -> Bbox: ...
+    def intersects_path(self, other: Path, filled: bool = ...) -> bool: ...
+    def intersects_bbox(self, bbox: Bbox, filled: bool = ...) -> bool: ...
+    def interpolated(self, steps: int) -> Path: ...
+    def to_polygons(
+        self,
+        transform: Transform | None = ...,
+        width: float = ...,
+        height: float = ...,
+        closed_only: bool = ...,
+    ) -> list[ArrayLike]: ...
+    @classmethod
+    def unit_rectangle(cls) -> Path: ...
+    @classmethod
+    def unit_regular_polygon(cls, numVertices: int) -> Path: ...
+    @classmethod
+    def unit_regular_star(cls, numVertices: int, innerCircle: float = ...) -> Path: ...
+    @classmethod
+    def unit_regular_asterisk(cls, numVertices: int) -> Path: ...
+    @classmethod
+    def unit_circle(cls) -> Path: ...
+    @classmethod
+    def circle(
+        cls,
+        center: tuple[float, float] = ...,
+        radius: float = ...,
+        readonly: bool = ...,
+    ) -> Path: ...
+    @classmethod
+    def unit_circle_righthalf(cls) -> Path: ...
+    @classmethod
+    def arc(
+        cls, theta1: float, theta2: float, n: int | None = ..., is_wedge: bool = ...
+    ) -> Path: ...
+    @classmethod
+    def wedge(cls, theta1: float, theta2: float, n: int | None = ...) -> Path: ...
+    @overload
+    @staticmethod
+    def hatch(hatchpattern: str, density: float = ...) -> Path: ...
+    @overload
+    @staticmethod
+    def hatch(hatchpattern: None, density: float = ...) -> None: ...
+    def clip_to_bbox(self, bbox: Bbox, inside: bool = ...) -> Path: ...
+
+def get_path_collection_extents(
+    master_transform: Transform,
+    paths: Sequence[Path],
+    transforms: Iterable[Affine2D],
+    offsets: ArrayLike,
+    offset_transform: Affine2D,
+) -> Bbox: ...
diff --git a/lib/python3.12/site-packages/matplotlib/patheffects.py b/lib/python3.12/site-packages/matplotlib/patheffects.py
new file mode 100644
index 0000000000000000000000000000000000000000..e7a0138bd7507a18f96e445572c59fdd2cde0e7c
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/patheffects.py
@@ -0,0 +1,511 @@
+"""
+Defines classes for path effects. The path effects are supported in `.Text`,
+`.Line2D` and `.Patch`.
+
+.. seealso::
+   :ref:`patheffects_guide`
+"""
+
+from matplotlib.backend_bases import RendererBase
+from matplotlib import colors as mcolors
+from matplotlib import patches as mpatches
+from matplotlib import transforms as mtransforms
+from matplotlib.path import Path
+import numpy as np
+
+
+class AbstractPathEffect:
+    """
+    A base class for path effects.
+
+    Subclasses should override the ``draw_path`` method to add effect
+    functionality.
+    """
+
+    def __init__(self, offset=(0., 0.)):
+        """
+        Parameters
+        ----------
+        offset : (float, float), default: (0, 0)
+            The (x, y) offset to apply to the path, measured in points.
+        """
+        self._offset = offset
+
+    def _offset_transform(self, renderer):
+        """Apply the offset to the given transform."""
+        return mtransforms.Affine2D().translate(
+            *map(renderer.points_to_pixels, self._offset))
+
+    def _update_gc(self, gc, new_gc_dict):
+        """
+        Update the given GraphicsContext with the given dict of properties.
+
+        The keys in the dictionary are used to identify the appropriate
+        ``set_`` method on the *gc*.
+        """
+        new_gc_dict = new_gc_dict.copy()
+
+        dashes = new_gc_dict.pop("dashes", None)
+        if dashes:
+            gc.set_dashes(**dashes)
+
+        for k, v in new_gc_dict.items():
+            set_method = getattr(gc, 'set_' + k, None)
+            if not callable(set_method):
+                raise AttributeError(f'Unknown property {k}')
+            set_method(v)
+        return gc
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace=None):
+        """
+        Derived should override this method. The arguments are the same
+        as :meth:`matplotlib.backend_bases.RendererBase.draw_path`
+        except the first argument is a renderer.
+        """
+        # Get the real renderer, not a PathEffectRenderer.
+        if isinstance(renderer, PathEffectRenderer):
+            renderer = renderer._renderer
+        return renderer.draw_path(gc, tpath, affine, rgbFace)
+
+
+class PathEffectRenderer(RendererBase):
+    """
+    Implements a Renderer which contains another renderer.
+
+    This proxy then intercepts draw calls, calling the appropriate
+    :class:`AbstractPathEffect` draw method.
+
+    .. note::
+        Not all methods have been overridden on this RendererBase subclass.
+        It may be necessary to add further methods to extend the PathEffects
+        capabilities further.
+    """
+
+    def __init__(self, path_effects, renderer):
+        """
+        Parameters
+        ----------
+        path_effects : iterable of :class:`AbstractPathEffect`
+            The path effects which this renderer represents.
+        renderer : `~matplotlib.backend_bases.RendererBase` subclass
+
+        """
+        self._path_effects = path_effects
+        self._renderer = renderer
+
+    def copy_with_path_effect(self, path_effects):
+        return self.__class__(path_effects, self._renderer)
+
+    def __getattribute__(self, name):
+        if name in ['flipy', 'get_canvas_width_height', 'new_gc',
+                    'points_to_pixels', '_text2path', 'height', 'width']:
+            return getattr(self._renderer, name)
+        else:
+            return object.__getattribute__(self, name)
+
+    def draw_path(self, gc, tpath, affine, rgbFace=None):
+        for path_effect in self._path_effects:
+            path_effect.draw_path(self._renderer, gc, tpath, affine,
+                                  rgbFace)
+
+    def draw_markers(
+            self, gc, marker_path, marker_trans, path, *args, **kwargs):
+        # We do a little shimmy so that all markers are drawn for each path
+        # effect in turn. Essentially, we induce recursion (depth 1) which is
+        # terminated once we have just a single path effect to work with.
+        if len(self._path_effects) == 1:
+            # Call the base path effect function - this uses the unoptimised
+            # approach of calling "draw_path" multiple times.
+            return super().draw_markers(gc, marker_path, marker_trans, path,
+                                        *args, **kwargs)
+
+        for path_effect in self._path_effects:
+            renderer = self.copy_with_path_effect([path_effect])
+            # Recursively call this method, only next time we will only have
+            # one path effect.
+            renderer.draw_markers(gc, marker_path, marker_trans, path,
+                                  *args, **kwargs)
+
+    def draw_path_collection(self, gc, master_transform, paths, *args,
+                             **kwargs):
+        # We do a little shimmy so that all paths are drawn for each path
+        # effect in turn. Essentially, we induce recursion (depth 1) which is
+        # terminated once we have just a single path effect to work with.
+        if len(self._path_effects) == 1:
+            # Call the base path effect function - this uses the unoptimised
+            # approach of calling "draw_path" multiple times.
+            return super().draw_path_collection(gc, master_transform, paths,
+                                                *args, **kwargs)
+
+        for path_effect in self._path_effects:
+            renderer = self.copy_with_path_effect([path_effect])
+            # Recursively call this method, only next time we will only have
+            # one path effect.
+            renderer.draw_path_collection(gc, master_transform, paths,
+                                          *args, **kwargs)
+
+    def open_group(self, s, gid=None):
+        return self._renderer.open_group(s, gid)
+
+    def close_group(self, s):
+        return self._renderer.close_group(s)
+
+
+class Normal(AbstractPathEffect):
+    """
+    The "identity" PathEffect.
+
+    The Normal PathEffect's sole purpose is to draw the original artist with
+    no special path effect.
+    """
+
+
+def _subclass_with_normal(effect_class):
+    """
+    Create a PathEffect class combining *effect_class* and a normal draw.
+    """
+
+    class withEffect(effect_class):
+        def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+            super().draw_path(renderer, gc, tpath, affine, rgbFace)
+            renderer.draw_path(gc, tpath, affine, rgbFace)
+
+    withEffect.__name__ = f"with{effect_class.__name__}"
+    withEffect.__qualname__ = f"with{effect_class.__name__}"
+    withEffect.__doc__ = f"""
+    A shortcut PathEffect for applying `.{effect_class.__name__}` and then
+    drawing the original Artist.
+
+    With this class you can use ::
+
+        artist.set_path_effects([patheffects.with{effect_class.__name__}()])
+
+    as a shortcut for ::
+
+        artist.set_path_effects([patheffects.{effect_class.__name__}(),
+                                 patheffects.Normal()])
+    """
+    # Docstring inheritance doesn't work for locally-defined subclasses.
+    withEffect.draw_path.__doc__ = effect_class.draw_path.__doc__
+    return withEffect
+
+
+class Stroke(AbstractPathEffect):
+    """A line based PathEffect which re-draws a stroke."""
+
+    def __init__(self, offset=(0, 0), **kwargs):
+        """
+        The path will be stroked with its gc updated with the given
+        keyword arguments, i.e., the keyword arguments should be valid
+        gc parameter values.
+        """
+        super().__init__(offset)
+        self._gc = kwargs
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+        """Draw the path with updated gc."""
+        gc0 = renderer.new_gc()  # Don't modify gc, but a copy!
+        gc0.copy_properties(gc)
+        gc0 = self._update_gc(gc0, self._gc)
+        renderer.draw_path(
+            gc0, tpath, affine + self._offset_transform(renderer), rgbFace)
+        gc0.restore()
+
+
+withStroke = _subclass_with_normal(effect_class=Stroke)
+
+
+class SimplePatchShadow(AbstractPathEffect):
+    """A simple shadow via a filled patch."""
+
+    def __init__(self, offset=(2, -2),
+                 shadow_rgbFace=None, alpha=None,
+                 rho=0.3, **kwargs):
+        """
+        Parameters
+        ----------
+        offset : (float, float), default: (2, -2)
+            The (x, y) offset of the shadow in points.
+        shadow_rgbFace : :mpltype:`color`
+            The shadow color.
+        alpha : float, default: 0.3
+            The alpha transparency of the created shadow patch.
+        rho : float, default: 0.3
+            A scale factor to apply to the rgbFace color if *shadow_rgbFace*
+            is not specified.
+        **kwargs
+            Extra keywords are stored and passed through to
+            :meth:`AbstractPathEffect._update_gc`.
+
+        """
+        super().__init__(offset)
+
+        if shadow_rgbFace is None:
+            self._shadow_rgbFace = shadow_rgbFace
+        else:
+            self._shadow_rgbFace = mcolors.to_rgba(shadow_rgbFace)
+
+        if alpha is None:
+            alpha = 0.3
+
+        self._alpha = alpha
+        self._rho = rho
+
+        #: The dictionary of keywords to update the graphics collection with.
+        self._gc = kwargs
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+        """
+        Overrides the standard draw_path to add the shadow offset and
+        necessary color changes for the shadow.
+        """
+        gc0 = renderer.new_gc()  # Don't modify gc, but a copy!
+        gc0.copy_properties(gc)
+
+        if self._shadow_rgbFace is None:
+            r, g, b = (rgbFace or (1., 1., 1.))[:3]
+            # Scale the colors by a factor to improve the shadow effect.
+            shadow_rgbFace = (r * self._rho, g * self._rho, b * self._rho)
+        else:
+            shadow_rgbFace = self._shadow_rgbFace
+
+        gc0.set_foreground("none")
+        gc0.set_alpha(self._alpha)
+        gc0.set_linewidth(0)
+
+        gc0 = self._update_gc(gc0, self._gc)
+        renderer.draw_path(
+            gc0, tpath, affine + self._offset_transform(renderer),
+            shadow_rgbFace)
+        gc0.restore()
+
+
+withSimplePatchShadow = _subclass_with_normal(effect_class=SimplePatchShadow)
+
+
+class SimpleLineShadow(AbstractPathEffect):
+    """A simple shadow via a line."""
+
+    def __init__(self, offset=(2, -2),
+                 shadow_color='k', alpha=0.3, rho=0.3, **kwargs):
+        """
+        Parameters
+        ----------
+        offset : (float, float), default: (2, -2)
+            The (x, y) offset to apply to the path, in points.
+        shadow_color : :mpltype:`color`, default: 'black'
+            The shadow color.
+            A value of ``None`` takes the original artist's color
+            with a scale factor of *rho*.
+        alpha : float, default: 0.3
+            The alpha transparency of the created shadow patch.
+        rho : float, default: 0.3
+            A scale factor to apply to the rgbFace color if *shadow_color*
+            is ``None``.
+        **kwargs
+            Extra keywords are stored and passed through to
+            :meth:`AbstractPathEffect._update_gc`.
+        """
+        super().__init__(offset)
+        if shadow_color is None:
+            self._shadow_color = shadow_color
+        else:
+            self._shadow_color = mcolors.to_rgba(shadow_color)
+        self._alpha = alpha
+        self._rho = rho
+        #: The dictionary of keywords to update the graphics collection with.
+        self._gc = kwargs
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+        """
+        Overrides the standard draw_path to add the shadow offset and
+        necessary color changes for the shadow.
+        """
+        gc0 = renderer.new_gc()  # Don't modify gc, but a copy!
+        gc0.copy_properties(gc)
+
+        if self._shadow_color is None:
+            r, g, b = (gc0.get_foreground() or (1., 1., 1.))[:3]
+            # Scale the colors by a factor to improve the shadow effect.
+            shadow_rgbFace = (r * self._rho, g * self._rho, b * self._rho)
+        else:
+            shadow_rgbFace = self._shadow_color
+
+        gc0.set_foreground(shadow_rgbFace)
+        gc0.set_alpha(self._alpha)
+
+        gc0 = self._update_gc(gc0, self._gc)
+        renderer.draw_path(
+            gc0, tpath, affine + self._offset_transform(renderer))
+        gc0.restore()
+
+
+class PathPatchEffect(AbstractPathEffect):
+    """
+    Draws a `.PathPatch` instance whose Path comes from the original
+    PathEffect artist.
+    """
+
+    def __init__(self, offset=(0, 0), **kwargs):
+        """
+        Parameters
+        ----------
+        offset : (float, float), default: (0, 0)
+            The (x, y) offset to apply to the path, in points.
+        **kwargs
+            All keyword arguments are passed through to the
+            :class:`~matplotlib.patches.PathPatch` constructor. The
+            properties which cannot be overridden are "path", "clip_box"
+            "transform" and "clip_path".
+        """
+        super().__init__(offset=offset)
+        self.patch = mpatches.PathPatch([], **kwargs)
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+        self.patch._path = tpath
+        self.patch.set_transform(affine + self._offset_transform(renderer))
+        self.patch.set_clip_box(gc.get_clip_rectangle())
+        clip_path = gc.get_clip_path()
+        if clip_path and self.patch.get_clip_path() is None:
+            self.patch.set_clip_path(*clip_path)
+        self.patch.draw(renderer)
+
+
+class TickedStroke(AbstractPathEffect):
+    """
+    A line-based PathEffect which draws a path with a ticked style.
+
+    This line style is frequently used to represent constraints in
+    optimization.  The ticks may be used to indicate that one side
+    of the line is invalid or to represent a closed boundary of a
+    domain (i.e. a wall or the edge of a pipe).
+
+    The spacing, length, and angle of ticks can be controlled.
+
+    This line style is sometimes referred to as a hatched line.
+
+    See also the :doc:`/gallery/misc/tickedstroke_demo` example.
+    """
+
+    def __init__(self, offset=(0, 0),
+                 spacing=10.0, angle=45.0, length=np.sqrt(2),
+                 **kwargs):
+        """
+        Parameters
+        ----------
+        offset : (float, float), default: (0, 0)
+            The (x, y) offset to apply to the path, in points.
+        spacing : float, default: 10.0
+            The spacing between ticks in points.
+        angle : float, default: 45.0
+            The angle between the path and the tick in degrees.  The angle
+            is measured as if you were an ant walking along the curve, with
+            zero degrees pointing directly ahead, 90 to your left, -90
+            to your right, and 180 behind you. To change side of the ticks,
+            change sign of the angle.
+        length : float, default: 1.414
+            The length of the tick relative to spacing.
+            Recommended length = 1.414 (sqrt(2)) when angle=45, length=1.0
+            when angle=90 and length=2.0 when angle=60.
+        **kwargs
+            Extra keywords are stored and passed through to
+            :meth:`AbstractPathEffect._update_gc`.
+
+        Examples
+        --------
+        See :doc:`/gallery/misc/tickedstroke_demo`.
+        """
+        super().__init__(offset)
+
+        self._spacing = spacing
+        self._angle = angle
+        self._length = length
+        self._gc = kwargs
+
+    def draw_path(self, renderer, gc, tpath, affine, rgbFace):
+        """Draw the path with updated gc."""
+        # Do not modify the input! Use copy instead.
+        gc0 = renderer.new_gc()
+        gc0.copy_properties(gc)
+
+        gc0 = self._update_gc(gc0, self._gc)
+        trans = affine + self._offset_transform(renderer)
+
+        theta = -np.radians(self._angle)
+        trans_matrix = np.array([[np.cos(theta), -np.sin(theta)],
+                                 [np.sin(theta), np.cos(theta)]])
+
+        # Convert spacing parameter to pixels.
+        spacing_px = renderer.points_to_pixels(self._spacing)
+
+        # Transform before evaluation because to_polygons works at resolution
+        # of one -- assuming it is working in pixel space.
+        transpath = affine.transform_path(tpath)
+
+        # Evaluate path to straight line segments that can be used to
+        # construct line ticks.
+        polys = transpath.to_polygons(closed_only=False)
+
+        for p in polys:
+            x = p[:, 0]
+            y = p[:, 1]
+
+            # Can not interpolate points or draw line if only one point in
+            # polyline.
+            if x.size < 2:
+                continue
+
+            # Find distance between points on the line
+            ds = np.hypot(x[1:] - x[:-1], y[1:] - y[:-1])
+
+            # Build parametric coordinate along curve
+            s = np.concatenate(([0.0], np.cumsum(ds)))
+            s_total = s[-1]
+
+            num = int(np.ceil(s_total / spacing_px)) - 1
+            # Pick parameter values for ticks.
+            s_tick = np.linspace(spacing_px/2, s_total - spacing_px/2, num)
+
+            # Find points along the parameterized curve
+            x_tick = np.interp(s_tick, s, x)
+            y_tick = np.interp(s_tick, s, y)
+
+            # Find unit vectors in local direction of curve
+            delta_s = self._spacing * .001
+            u = (np.interp(s_tick + delta_s, s, x) - x_tick) / delta_s
+            v = (np.interp(s_tick + delta_s, s, y) - y_tick) / delta_s
+
+            # Normalize slope into unit slope vector.
+            n = np.hypot(u, v)
+            mask = n == 0
+            n[mask] = 1.0
+
+            uv = np.array([u / n, v / n]).T
+            uv[mask] = np.array([0, 0]).T
+
+            # Rotate and scale unit vector into tick vector
+            dxy = np.dot(uv, trans_matrix) * self._length * spacing_px
+
+            # Build tick endpoints
+            x_end = x_tick + dxy[:, 0]
+            y_end = y_tick + dxy[:, 1]
+
+            # Interleave ticks to form Path vertices
+            xyt = np.empty((2 * num, 2), dtype=x_tick.dtype)
+            xyt[0::2, 0] = x_tick
+            xyt[1::2, 0] = x_end
+            xyt[0::2, 1] = y_tick
+            xyt[1::2, 1] = y_end
+
+            # Build up vector of Path codes
+            codes = np.tile([Path.MOVETO, Path.LINETO], num)
+
+            # Construct and draw resulting path
+            h = Path(xyt, codes)
+            # Transform back to data space during render
+            renderer.draw_path(gc0, h, affine.inverted() + trans, rgbFace)
+
+        gc0.restore()
+
+
+withTickedStroke = _subclass_with_normal(effect_class=TickedStroke)
diff --git a/lib/python3.12/site-packages/matplotlib/py.typed b/lib/python3.12/site-packages/matplotlib/py.typed
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/lib/python3.12/site-packages/matplotlib/pylab.py b/lib/python3.12/site-packages/matplotlib/pylab.py
new file mode 100644
index 0000000000000000000000000000000000000000..a50779cf6d264408f1f99a086a25cb5c9d525588
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/pylab.py
@@ -0,0 +1,67 @@
+"""
+`pylab` is a historic interface and its use is strongly discouraged. The equivalent
+replacement is `matplotlib.pyplot`.  See :ref:`api_interfaces` for a full overview
+of Matplotlib interfaces.
+
+`pylab` was designed to support a MATLAB-like way of working with all plotting related
+functions directly available in the global namespace. This was achieved through a
+wildcard import (``from pylab import *``).
+
+.. warning::
+   The use of `pylab` is discouraged for the following reasons:
+
+   ``from pylab import *`` imports all the functions from `matplotlib.pyplot`, `numpy`,
+   `numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into
+   the global namespace.
+
+   Such a pattern is considered bad practice in modern python, as it clutters the global
+   namespace. Even more severely, in the case of `pylab`, this will overwrite some
+   builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which
+   can lead to unexpected behavior.
+
+"""
+
+from matplotlib.cbook import flatten, silent_list
+
+import matplotlib as mpl
+
+from matplotlib.dates import (
+    date2num, num2date, datestr2num, drange, DateFormatter, DateLocator,
+    RRuleLocator, YearLocator, MonthLocator, WeekdayLocator, DayLocator,
+    HourLocator, MinuteLocator, SecondLocator, rrule, MO, TU, WE, TH, FR,
+    SA, SU, YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY,
+    relativedelta)
+
+# bring all the symbols in so folks can import them from
+# pylab in one fell swoop
+
+## We are still importing too many things from mlab; more cleanup is needed.
+
+from matplotlib.mlab import (
+    detrend, detrend_linear, detrend_mean, detrend_none, window_hanning,
+    window_none)
+
+from matplotlib import cbook, mlab, pyplot as plt
+from matplotlib.pyplot import *
+
+from numpy import *
+from numpy.fft import *
+from numpy.random import *
+from numpy.linalg import *
+
+import numpy as np
+import numpy.ma as ma
+
+# don't let numpy's datetime hide stdlib
+import datetime
+
+# This is needed, or bytes will be numpy.random.bytes from
+# "from numpy.random import *" above
+bytes = __import__("builtins").bytes
+# We also don't want the numpy version of these functions
+abs = __import__("builtins").abs
+bool = __import__("builtins").bool
+max = __import__("builtins").max
+min = __import__("builtins").min
+pow = __import__("builtins").pow
+round = __import__("builtins").round
diff --git a/lib/python3.12/site-packages/matplotlib/quiver.py b/lib/python3.12/site-packages/matplotlib/quiver.py
new file mode 100644
index 0000000000000000000000000000000000000000..e66f1f97b21f65ac3cdeaadd4ff6ef4b74ddaed8
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/quiver.py
@@ -0,0 +1,1228 @@
+"""
+Support for plotting vector fields.
+
+Presently this contains Quiver and Barb. Quiver plots an arrow in the
+direction of the vector, with the size of the arrow related to the
+magnitude of the vector.
+
+Barbs are like quiver in that they point along a vector, but
+the magnitude of the vector is given schematically by the presence of barbs
+or flags on the barb.
+
+This will also become a home for things such as standard
+deviation ellipses, which can and will be derived very easily from
+the Quiver code.
+"""
+
+import math
+
+import numpy as np
+from numpy import ma
+
+from matplotlib import _api, cbook, _docstring
+import matplotlib.artist as martist
+import matplotlib.collections as mcollections
+from matplotlib.patches import CirclePolygon
+import matplotlib.text as mtext
+import matplotlib.transforms as transforms
+
+
+_quiver_doc = """
+Plot a 2D field of arrows.
+
+Call signature::
+
+  quiver([X, Y], U, V, [C], /, **kwargs)
+
+*X*, *Y* define the arrow locations, *U*, *V* define the arrow directions, and
+*C* optionally sets the color. The arguments *X*, *Y*, *U*, *V*, *C* are
+positional-only.
+
+**Arrow length**
+
+The default settings auto-scales the length of the arrows to a reasonable size.
+To change this behavior see the *scale* and *scale_units* parameters.
+
+**Arrow shape**
+
+The arrow shape is determined by *width*, *headwidth*, *headlength* and
+*headaxislength*. See the notes below.
+
+**Arrow styling**
+
+Each arrow is internally represented by a filled polygon with a default edge
+linewidth of 0. As a result, an arrow is rather a filled area, not a line with
+a head, and `.PolyCollection` properties like *linewidth*, *edgecolor*,
+*facecolor*, etc. act accordingly.
+
+
+Parameters
+----------
+X, Y : 1D or 2D array-like, optional
+    The x and y coordinates of the arrow locations.
+
+    If not given, they will be generated as a uniform integer meshgrid based
+    on the dimensions of *U* and *V*.
+
+    If *X* and *Y* are 1D but *U*, *V* are 2D, *X*, *Y* are expanded to 2D
+    using ``X, Y = np.meshgrid(X, Y)``. In this case ``len(X)`` and ``len(Y)``
+    must match the column and row dimensions of *U* and *V*.
+
+U, V : 1D or 2D array-like
+    The x and y direction components of the arrow vectors. The interpretation
+    of these components (in data or in screen space) depends on *angles*.
+
+    *U* and *V* must have the same number of elements, matching the number of
+    arrow locations in *X*, *Y*. *U* and *V* may be masked. Locations masked
+    in any of *U*, *V*, and *C* will not be drawn.
+
+C : 1D or 2D array-like, optional
+    Numeric data that defines the arrow colors by colormapping via *norm* and
+    *cmap*.
+
+    This does not support explicit colors. If you want to set colors directly,
+    use *color* instead.  The size of *C* must match the number of arrow
+    locations.
+
+angles : {'uv', 'xy'} or array-like, default: 'uv'
+    Method for determining the angle of the arrows.
+
+    - 'uv':  Arrow directions are based on
+      :ref:`display coordinates <coordinate-systems>`; i.e. a 45° angle will
+      always show up as diagonal on the screen, irrespective of figure or Axes
+      aspect ratio or Axes data ranges. This is useful when the arrows represent
+      a quantity whose direction is not tied to the x and y data coordinates.
+
+      If *U* == *V* the orientation of the arrow on the plot is 45 degrees
+      counter-clockwise from the horizontal axis (positive to the right).
+
+    - 'xy': Arrow direction in data coordinates, i.e. the arrows point from
+      (x, y) to (x+u, y+v). This is ideal for vector fields or gradient plots
+      where the arrows should directly represent movements or gradients in the
+      x and y directions.
+
+    - Arbitrary angles may be specified explicitly as an array of values
+      in degrees, counter-clockwise from the horizontal axis.
+
+      In this case *U*, *V* is only used to determine the length of the
+      arrows.
+
+      For example, ``angles=[30, 60, 90]`` will orient the arrows at 30, 60, and 90
+      degrees respectively, regardless of the *U* and *V* components.
+
+    Note: inverting a data axis will correspondingly invert the
+    arrows only with ``angles='xy'``.
+
+pivot : {'tail', 'mid', 'middle', 'tip'}, default: 'tail'
+    The part of the arrow that is anchored to the *X*, *Y* grid. The arrow
+    rotates about this point.
+
+    'mid' is a synonym for 'middle'.
+
+scale : float, optional
+    Scales the length of the arrow inversely.
+
+    Number of data values represented by one unit of arrow length on the plot.
+    For example, if the data represents velocity in meters per second (m/s), the
+    scale parameter determines how many meters per second correspond to one unit of
+    arrow length relative to the width of the plot.
+    Smaller scale parameter makes the arrow longer.
+
+    By default, an autoscaling algorithm is used to scale the arrow length to a
+    reasonable size, which is based on the average vector length and the number of
+    vectors.
+
+    The arrow length unit is given by the *scale_units* parameter.
+
+scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
+
+    The physical image unit, which is used for rendering the scaled arrow data *U*, *V*.
+
+    The rendered arrow length is given by
+
+        length in x direction = $\\frac{u}{\\mathrm{scale}} \\mathrm{scale_unit}$
+
+        length in y direction = $\\frac{v}{\\mathrm{scale}} \\mathrm{scale_unit}$
+
+    For example, ``(u, v) = (0.5, 0)`` with ``scale=10, scale_unit="width"`` results
+    in a horizontal arrow with a length of *0.5 / 10 * "width"*, i.e. 0.05 times the
+    Axes width.
+
+    Supported values are:
+
+    - 'width' or 'height': The arrow length is scaled relative to the width or height
+       of the Axes.
+       For example, ``scale_units='width', scale=1.0``, will result in an arrow length
+       of width of the Axes.
+
+    - 'dots': The arrow length of the arrows is in measured in display dots (pixels).
+
+    - 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure.
+       This ensures that the arrows have a consistent physical size on the figure,
+       in inches, regardless of data values or plot scaling.
+       For example, ``(u, v) = (1, 0)`` with ``scale_units='inches', scale=2`` results
+       in a 0.5 inch-long arrow.
+
+    - 'x' or 'y': The arrow length is scaled relative to the x or y axis units.
+       For example, ``(u, v) = (0, 1)`` with ``scale_units='x', scale=1`` results
+       in a vertical arrow with the length of 1 x-axis unit.
+
+    - 'xy': Arrow length will be same as 'x' or 'y' units.
+       This is useful for creating vectors in the x-y plane where u and v have
+       the same units as x and y. To plot vectors in the x-y plane with u and v having
+       the same units as x and y, use ``angles='xy', scale_units='xy', scale=1``.
+
+    Note: Setting *scale_units* without setting scale does not have any effect because
+    the scale units only differ by a constant factor and that is rescaled through
+    autoscaling.
+
+units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
+    Affects the arrow size (except for the length). In particular, the shaft
+    *width* is measured in multiples of this unit.
+
+    Supported values are:
+
+    - 'width', 'height': The width or height of the Axes.
+    - 'dots', 'inches': Pixels or inches based on the figure dpi.
+    - 'x', 'y', 'xy': *X*, *Y* or :math:`\\sqrt{X^2 + Y^2}` in data units.
+
+    The following table summarizes how these values affect the visible arrow
+    size under zooming and figure size changes:
+
+    =================  =================   ==================
+    units              zoom                figure size change
+    =================  =================   ==================
+    'x', 'y', 'xy'     arrow size scales   —
+    'width', 'height'  —                   arrow size scales
+    'dots', 'inches'   —                   —
+    =================  =================   ==================
+
+width : float, optional
+    Shaft width in arrow units. All head parameters are relative to *width*.
+
+    The default depends on choice of *units* above, and number of vectors;
+    a typical starting value is about 0.005 times the width of the plot.
+
+headwidth : float, default: 3
+    Head width as multiple of shaft *width*. See the notes below.
+
+headlength : float, default: 5
+    Head length as multiple of shaft *width*. See the notes below.
+
+headaxislength : float, default: 4.5
+    Head length at shaft intersection as multiple of shaft *width*.
+    See the notes below.
+
+minshaft : float, default: 1
+    Length below which arrow scales, in units of head length. Do not
+    set this to less than 1, or small arrows will look terrible!
+
+minlength : float, default: 1
+    Minimum length as a multiple of shaft width; if an arrow length
+    is less than this, plot a dot (hexagon) of this diameter instead.
+
+color : :mpltype:`color` or list :mpltype:`color`, optional
+    Explicit color(s) for the arrows. If *C* has been set, *color* has no
+    effect.
+
+    This is a synonym for the `.PolyCollection` *facecolor* parameter.
+
+Other Parameters
+----------------
+data : indexable object, optional
+    DATA_PARAMETER_PLACEHOLDER
+
+**kwargs : `~matplotlib.collections.PolyCollection` properties, optional
+    All other keyword arguments are passed on to `.PolyCollection`:
+
+    %(PolyCollection:kwdoc)s
+
+Returns
+-------
+`~matplotlib.quiver.Quiver`
+
+See Also
+--------
+.Axes.quiverkey : Add a key to a quiver plot.
+
+Notes
+-----
+
+**Arrow shape**
+
+The arrow is drawn as a polygon using the nodes as shown below. The values
+*headwidth*, *headlength*, and *headaxislength* are in units of *width*.
+
+.. image:: /_static/quiver_sizes.svg
+   :width: 500px
+
+The defaults give a slightly swept-back arrow. Here are some guidelines how to
+get other head shapes:
+
+- To make the head a triangle, make *headaxislength* the same as *headlength*.
+- To make the arrow more pointed, reduce *headwidth* or increase *headlength*
+  and *headaxislength*.
+- To make the head smaller relative to the shaft, scale down all the head
+  parameters proportionally.
+- To remove the head completely, set all *head* parameters to 0.
+- To get a diamond-shaped head, make *headaxislength* larger than *headlength*.
+- Warning: For *headaxislength* < (*headlength* / *headwidth*), the "headaxis"
+  nodes (i.e. the ones connecting the head with the shaft) will protrude out
+  of the head in forward direction so that the arrow head looks broken.
+""" % _docstring.interpd.params
+
+_docstring.interpd.register(quiver_doc=_quiver_doc)
+
+
+class QuiverKey(martist.Artist):
+    """Labelled arrow for use as a quiver plot scale key."""
+    halign = {'N': 'center', 'S': 'center', 'E': 'left', 'W': 'right'}
+    valign = {'N': 'bottom', 'S': 'top', 'E': 'center', 'W': 'center'}
+    pivot = {'N': 'middle', 'S': 'middle', 'E': 'tip', 'W': 'tail'}
+
+    def __init__(self, Q, X, Y, U, label,
+                 *, angle=0, coordinates='axes', color=None, labelsep=0.1,
+                 labelpos='N', labelcolor=None, fontproperties=None,
+                 zorder=None, **kwargs):
+        """
+        Add a key to a quiver plot.
+
+        The positioning of the key depends on *X*, *Y*, *coordinates*, and
+        *labelpos*.  If *labelpos* is 'N' or 'S', *X*, *Y* give the position of
+        the middle of the key arrow.  If *labelpos* is 'E', *X*, *Y* positions
+        the head, and if *labelpos* is 'W', *X*, *Y* positions the tail; in
+        either of these two cases, *X*, *Y* is somewhere in the middle of the
+        arrow+label key object.
+
+        Parameters
+        ----------
+        Q : `~matplotlib.quiver.Quiver`
+            A `.Quiver` object as returned by a call to `~.Axes.quiver()`.
+        X, Y : float
+            The location of the key.
+        U : float
+            The length of the key.
+        label : str
+            The key label (e.g., length and units of the key).
+        angle : float, default: 0
+            The angle of the key arrow, in degrees anti-clockwise from the
+            horizontal axis.
+        coordinates : {'axes', 'figure', 'data', 'inches'}, default: 'axes'
+            Coordinate system and units for *X*, *Y*: 'axes' and 'figure' are
+            normalized coordinate systems with (0, 0) in the lower left and
+            (1, 1) in the upper right; 'data' are the axes data coordinates
+            (used for the locations of the vectors in the quiver plot itself);
+            'inches' is position in the figure in inches, with (0, 0) at the
+            lower left corner.
+        color : :mpltype:`color`
+            Overrides face and edge colors from *Q*.
+        labelpos : {'N', 'S', 'E', 'W'}
+            Position the label above, below, to the right, to the left of the
+            arrow, respectively.
+        labelsep : float, default: 0.1
+            Distance in inches between the arrow and the label.
+        labelcolor : :mpltype:`color`, default: :rc:`text.color`
+            Label color.
+        fontproperties : dict, optional
+            A dictionary with keyword arguments accepted by the
+            `~matplotlib.font_manager.FontProperties` initializer:
+            *family*, *style*, *variant*, *size*, *weight*.
+        zorder : float
+            The zorder of the key. The default is 0.1 above *Q*.
+        **kwargs
+            Any additional keyword arguments are used to override vector
+            properties taken from *Q*.
+        """
+        super().__init__()
+        self.Q = Q
+        self.X = X
+        self.Y = Y
+        self.U = U
+        self.angle = angle
+        self.coord = coordinates
+        self.color = color
+        self.label = label
+        self._labelsep_inches = labelsep
+
+        self.labelpos = labelpos
+        self.labelcolor = labelcolor
+        self.fontproperties = fontproperties or dict()
+        self.kw = kwargs
+        self.text = mtext.Text(
+            text=label,
+            horizontalalignment=self.halign[self.labelpos],
+            verticalalignment=self.valign[self.labelpos],
+            fontproperties=self.fontproperties)
+        if self.labelcolor is not None:
+            self.text.set_color(self.labelcolor)
+        self._dpi_at_last_init = None
+        self.zorder = zorder if zorder is not None else Q.zorder + 0.1
+
+    @property
+    def labelsep(self):
+        return self._labelsep_inches * self.Q.axes.get_figure(root=True).dpi
+
+    def _init(self):
+        if True:  # self._dpi_at_last_init != self.axes.get_figure().dpi
+            if self.Q._dpi_at_last_init != self.Q.axes.get_figure(root=True).dpi:
+                self.Q._init()
+            self._set_transform()
+            with cbook._setattr_cm(self.Q, pivot=self.pivot[self.labelpos],
+                                   # Hack: save and restore the Umask
+                                   Umask=ma.nomask):
+                u = self.U * np.cos(np.radians(self.angle))
+                v = self.U * np.sin(np.radians(self.angle))
+                self.verts = self.Q._make_verts([[0., 0.]],
+                                                np.array([u]), np.array([v]), 'uv')
+            kwargs = self.Q.polykw
+            kwargs.update(self.kw)
+            self.vector = mcollections.PolyCollection(
+                self.verts,
+                offsets=[(self.X, self.Y)],
+                offset_transform=self.get_transform(),
+                **kwargs)
+            if self.color is not None:
+                self.vector.set_color(self.color)
+            self.vector.set_transform(self.Q.get_transform())
+            self.vector.set_figure(self.get_figure())
+            self._dpi_at_last_init = self.Q.axes.get_figure(root=True).dpi
+
+    def _text_shift(self):
+        return {
+            "N": (0, +self.labelsep),
+            "S": (0, -self.labelsep),
+            "E": (+self.labelsep, 0),
+            "W": (-self.labelsep, 0),
+        }[self.labelpos]
+
+    @martist.allow_rasterization
+    def draw(self, renderer):
+        self._init()
+        self.vector.draw(renderer)
+        pos = self.get_transform().transform((self.X, self.Y))
+        self.text.set_position(pos + self._text_shift())
+        self.text.draw(renderer)
+        self.stale = False
+
+    def _set_transform(self):
+        fig = self.Q.axes.get_figure(root=False)
+        self.set_transform(_api.check_getitem({
+            "data": self.Q.axes.transData,
+            "axes": self.Q.axes.transAxes,
+            "figure": fig.transFigure,
+            "inches": fig.dpi_scale_trans,
+        }, coordinates=self.coord))
+
+    def set_figure(self, fig):
+        super().set_figure(fig)
+        self.text.set_figure(fig)
+
+    def contains(self, mouseevent):
+        if self._different_canvas(mouseevent):
+            return False, {}
+        # Maybe the dictionary should allow one to
+        # distinguish between a text hit and a vector hit.
+        if (self.text.contains(mouseevent)[0] or
+                self.vector.contains(mouseevent)[0]):
+            return True, {}
+        return False, {}
+
+
+def _parse_args(*args, caller_name='function'):
+    """
+    Helper function to parse positional parameters for colored vector plots.
+
+    This is currently used for Quiver and Barbs.
+
+    Parameters
+    ----------
+    *args : list
+        list of 2-5 arguments. Depending on their number they are parsed to::
+
+            U, V
+            U, V, C
+            X, Y, U, V
+            X, Y, U, V, C
+
+    caller_name : str
+        Name of the calling method (used in error messages).
+    """
+    X = Y = C = None
+
+    nargs = len(args)
+    if nargs == 2:
+        # The use of atleast_1d allows for handling scalar arguments while also
+        # keeping masked arrays
+        U, V = np.atleast_1d(*args)
+    elif nargs == 3:
+        U, V, C = np.atleast_1d(*args)
+    elif nargs == 4:
+        X, Y, U, V = np.atleast_1d(*args)
+    elif nargs == 5:
+        X, Y, U, V, C = np.atleast_1d(*args)
+    else:
+        raise _api.nargs_error(caller_name, takes="from 2 to 5", given=nargs)
+
+    nr, nc = (1, U.shape[0]) if U.ndim == 1 else U.shape
+
+    if X is not None:
+        X = X.ravel()
+        Y = Y.ravel()
+        if len(X) == nc and len(Y) == nr:
+            X, Y = (a.ravel() for a in np.meshgrid(X, Y))
+        elif len(X) != len(Y):
+            raise ValueError('X and Y must be the same size, but '
+                             f'X.size is {X.size} and Y.size is {Y.size}.')
+    else:
+        indexgrid = np.meshgrid(np.arange(nc), np.arange(nr))
+        X, Y = (np.ravel(a) for a in indexgrid)
+    # Size validation for U, V, C is left to the set_UVC method.
+    return X, Y, U, V, C
+
+
+def _check_consistent_shapes(*arrays):
+    all_shapes = {a.shape for a in arrays}
+    if len(all_shapes) != 1:
+        raise ValueError('The shapes of the passed in arrays do not match')
+
+
+class Quiver(mcollections.PolyCollection):
+    """
+    Specialized PolyCollection for arrows.
+
+    The only API method is set_UVC(), which can be used
+    to change the size, orientation, and color of the
+    arrows; their locations are fixed when the class is
+    instantiated.  Possibly this method will be useful
+    in animations.
+
+    Much of the work in this class is done in the draw()
+    method so that as much information as possible is available
+    about the plot.  In subsequent draw() calls, recalculation
+    is limited to things that might have changed, so there
+    should be no performance penalty from putting the calculations
+    in the draw() method.
+    """
+
+    _PIVOT_VALS = ('tail', 'middle', 'tip')
+
+    @_docstring.Substitution(_quiver_doc)
+    def __init__(self, ax, *args,
+                 scale=None, headwidth=3, headlength=5, headaxislength=4.5,
+                 minshaft=1, minlength=1, units='width', scale_units=None,
+                 angles='uv', width=None, color='k', pivot='tail', **kwargs):
+        """
+        The constructor takes one required argument, an Axes
+        instance, followed by the args and kwargs described
+        by the following pyplot interface documentation:
+        %s
+        """
+        self._axes = ax  # The attr actually set by the Artist.axes property.
+        X, Y, U, V, C = _parse_args(*args, caller_name='quiver')
+        self.X = X
+        self.Y = Y
+        self.XY = np.column_stack((X, Y))
+        self.N = len(X)
+        self.scale = scale
+        self.headwidth = headwidth
+        self.headlength = float(headlength)
+        self.headaxislength = headaxislength
+        self.minshaft = minshaft
+        self.minlength = minlength
+        self.units = units
+        self.scale_units = scale_units
+        self.angles = angles
+        self.width = width
+
+        if pivot.lower() == 'mid':
+            pivot = 'middle'
+        self.pivot = pivot.lower()
+        _api.check_in_list(self._PIVOT_VALS, pivot=self.pivot)
+
+        self.transform = kwargs.pop('transform', ax.transData)
+        kwargs.setdefault('facecolors', color)
+        kwargs.setdefault('linewidths', (0,))
+        super().__init__([], offsets=self.XY, offset_transform=self.transform,
+                         closed=False, **kwargs)
+        self.polykw = kwargs
+        self.set_UVC(U, V, C)
+        self._dpi_at_last_init = None
+
+    def _init(self):
+        """
+        Initialization delayed until first draw;
+        allow time for axes setup.
+        """
+        # It seems that there are not enough event notifications
+        # available to have this work on an as-needed basis at present.
+        if True:  # self._dpi_at_last_init != self.axes.figure.dpi
+            trans = self._set_transform()
+            self.span = trans.inverted().transform_bbox(self.axes.bbox).width
+            if self.width is None:
+                sn = np.clip(math.sqrt(self.N), 8, 25)
+                self.width = 0.06 * self.span / sn
+
+            # _make_verts sets self.scale if not already specified
+            if (self._dpi_at_last_init != self.axes.get_figure(root=True).dpi
+                    and self.scale is None):
+                self._make_verts(self.XY, self.U, self.V, self.angles)
+
+            self._dpi_at_last_init = self.axes.get_figure(root=True).dpi
+
+    def get_datalim(self, transData):
+        trans = self.get_transform()
+        offset_trf = self.get_offset_transform()
+        full_transform = (trans - transData) + (offset_trf - transData)
+        XY = full_transform.transform(self.XY)
+        bbox = transforms.Bbox.null()
+        bbox.update_from_data_xy(XY, ignore=True)
+        return bbox
+
+    @martist.allow_rasterization
+    def draw(self, renderer):
+        self._init()
+        verts = self._make_verts(self.XY, self.U, self.V, self.angles)
+        self.set_verts(verts, closed=False)
+        super().draw(renderer)
+        self.stale = False
+
+    def set_UVC(self, U, V, C=None):
+        # We need to ensure we have a copy, not a reference
+        # to an array that might change before draw().
+        U = ma.masked_invalid(U, copy=True).ravel()
+        V = ma.masked_invalid(V, copy=True).ravel()
+        if C is not None:
+            C = ma.masked_invalid(C, copy=True).ravel()
+        for name, var in zip(('U', 'V', 'C'), (U, V, C)):
+            if not (var is None or var.size == self.N or var.size == 1):
+                raise ValueError(f'Argument {name} has a size {var.size}'
+                                 f' which does not match {self.N},'
+                                 ' the number of arrow positions')
+
+        mask = ma.mask_or(U.mask, V.mask, copy=False, shrink=True)
+        if C is not None:
+            mask = ma.mask_or(mask, C.mask, copy=False, shrink=True)
+            if mask is ma.nomask:
+                C = C.filled()
+            else:
+                C = ma.array(C, mask=mask, copy=False)
+        self.U = U.filled(1)
+        self.V = V.filled(1)
+        self.Umask = mask
+        if C is not None:
+            self.set_array(C)
+        self.stale = True
+
+    def _dots_per_unit(self, units):
+        """Return a scale factor for converting from units to pixels."""
+        bb = self.axes.bbox
+        vl = self.axes.viewLim
+        return _api.check_getitem({
+            'x': bb.width / vl.width,
+            'y': bb.height / vl.height,
+            'xy': np.hypot(*bb.size) / np.hypot(*vl.size),
+            'width': bb.width,
+            'height': bb.height,
+            'dots': 1.,
+            'inches': self.axes.get_figure(root=True).dpi,
+        }, units=units)
+
+    def _set_transform(self):
+        """
+        Set the PolyCollection transform to go
+        from arrow width units to pixels.
+        """
+        dx = self._dots_per_unit(self.units)
+        self._trans_scale = dx  # pixels per arrow width unit
+        trans = transforms.Affine2D().scale(dx)
+        self.set_transform(trans)
+        return trans
+
+    # Calculate angles and lengths for segment between (x, y), (x+u, y+v)
+    def _angles_lengths(self, XY, U, V, eps=1):
+        xy = self.axes.transData.transform(XY)
+        uv = np.column_stack((U, V))
+        xyp = self.axes.transData.transform(XY + eps * uv)
+        dxy = xyp - xy
+        angles = np.arctan2(dxy[:, 1], dxy[:, 0])
+        lengths = np.hypot(*dxy.T) / eps
+        return angles, lengths
+
+    # XY is stacked [X, Y].
+    # See quiver() doc for meaning of X, Y, U, V, angles.
+    def _make_verts(self, XY, U, V, angles):
+        uv = (U + V * 1j)
+        str_angles = angles if isinstance(angles, str) else ''
+        if str_angles == 'xy' and self.scale_units == 'xy':
+            # Here eps is 1 so that if we get U, V by diffing
+            # the X, Y arrays, the vectors will connect the
+            # points, regardless of the axis scaling (including log).
+            angles, lengths = self._angles_lengths(XY, U, V, eps=1)
+        elif str_angles == 'xy' or self.scale_units == 'xy':
+            # Calculate eps based on the extents of the plot
+            # so that we don't end up with roundoff error from
+            # adding a small number to a large.
+            eps = np.abs(self.axes.dataLim.extents).max() * 0.001
+            angles, lengths = self._angles_lengths(XY, U, V, eps=eps)
+
+        if str_angles and self.scale_units == 'xy':
+            a = lengths
+        else:
+            a = np.abs(uv)
+
+        if self.scale is None:
+            sn = max(10, math.sqrt(self.N))
+            if self.Umask is not ma.nomask:
+                amean = a[~self.Umask].mean()
+            else:
+                amean = a.mean()
+            # crude auto-scaling
+            # scale is typical arrow length as a multiple of the arrow width
+            scale = 1.8 * amean * sn / self.span
+
+        if self.scale_units is None:
+            if self.scale is None:
+                self.scale = scale
+            widthu_per_lenu = 1.0
+        else:
+            if self.scale_units == 'xy':
+                dx = 1
+            else:
+                dx = self._dots_per_unit(self.scale_units)
+            widthu_per_lenu = dx / self._trans_scale
+            if self.scale is None:
+                self.scale = scale * widthu_per_lenu
+        length = a * (widthu_per_lenu / (self.scale * self.width))
+        X, Y = self._h_arrows(length)
+        if str_angles == 'xy':
+            theta = angles
+        elif str_angles == 'uv':
+            theta = np.angle(uv)
+        else:
+            theta = ma.masked_invalid(np.deg2rad(angles)).filled(0)
+        theta = theta.reshape((-1, 1))  # for broadcasting
+        xy = (X + Y * 1j) * np.exp(1j * theta) * self.width
+        XY = np.stack((xy.real, xy.imag), axis=2)
+        if self.Umask is not ma.nomask:
+            XY = ma.array(XY)
+            XY[self.Umask] = ma.masked
+            # This might be handled more efficiently with nans, given
+            # that nans will end up in the paths anyway.
+
+        return XY
+
+    def _h_arrows(self, length):
+        """Length is in arrow width units."""
+        # It might be possible to streamline the code
+        # and speed it up a bit by using complex (x, y)
+        # instead of separate arrays; but any gain would be slight.
+        minsh = self.minshaft * self.headlength
+        N = len(length)
+        length = length.reshape(N, 1)
+        # This number is chosen based on when pixel values overflow in Agg
+        # causing rendering errors
+        # length = np.minimum(length, 2 ** 16)
+        np.clip(length, 0, 2 ** 16, out=length)
+        # x, y: normal horizontal arrow
+        x = np.array([0, -self.headaxislength,
+                      -self.headlength, 0],
+                     np.float64)
+        x = x + np.array([0, 1, 1, 1]) * length
+        y = 0.5 * np.array([1, 1, self.headwidth, 0], np.float64)
+        y = np.repeat(y[np.newaxis, :], N, axis=0)
+        # x0, y0: arrow without shaft, for short vectors
+        x0 = np.array([0, minsh - self.headaxislength,
+                       minsh - self.headlength, minsh], np.float64)
+        y0 = 0.5 * np.array([1, 1, self.headwidth, 0], np.float64)
+        ii = [0, 1, 2, 3, 2, 1, 0, 0]
+        X = x[:, ii]
+        Y = y[:, ii]
+        Y[:, 3:-1] *= -1
+        X0 = x0[ii]
+        Y0 = y0[ii]
+        Y0[3:-1] *= -1
+        shrink = length / minsh if minsh != 0. else 0.
+        X0 = shrink * X0[np.newaxis, :]
+        Y0 = shrink * Y0[np.newaxis, :]
+        short = np.repeat(length < minsh, 8, axis=1)
+        # Now select X0, Y0 if short, otherwise X, Y
+        np.copyto(X, X0, where=short)
+        np.copyto(Y, Y0, where=short)
+        if self.pivot == 'middle':
+            X -= 0.5 * X[:, 3, np.newaxis]
+        elif self.pivot == 'tip':
+            # numpy bug? using -= does not work here unless we multiply by a
+            # float first, as with 'mid'.
+            X = X - X[:, 3, np.newaxis]
+        elif self.pivot != 'tail':
+            _api.check_in_list(["middle", "tip", "tail"], pivot=self.pivot)
+
+        tooshort = length < self.minlength
+        if tooshort.any():
+            # Use a heptagonal dot:
+            th = np.arange(0, 8, 1, np.float64) * (np.pi / 3.0)
+            x1 = np.cos(th) * self.minlength * 0.5
+            y1 = np.sin(th) * self.minlength * 0.5
+            X1 = np.repeat(x1[np.newaxis, :], N, axis=0)
+            Y1 = np.repeat(y1[np.newaxis, :], N, axis=0)
+            tooshort = np.repeat(tooshort, 8, 1)
+            np.copyto(X, X1, where=tooshort)
+            np.copyto(Y, Y1, where=tooshort)
+        # Mask handling is deferred to the caller, _make_verts.
+        return X, Y
+
+
+_barbs_doc = r"""
+Plot a 2D field of wind barbs.
+
+Call signature::
+
+  barbs([X, Y], U, V, [C], /, **kwargs)
+
+Where *X*, *Y* define the barb locations, *U*, *V* define the barb
+directions, and *C* optionally sets the color.
+
+The arguments *X*, *Y*, *U*, *V*, *C* are positional-only and may be
+1D or 2D. *U*, *V*, *C* may be masked arrays, but masked *X*, *Y*
+are not supported at present.
+
+Barbs are traditionally used in meteorology as a way to plot the speed
+and direction of wind observations, but can technically be used to
+plot any two dimensional vector quantity.  As opposed to arrows, which
+give vector magnitude by the length of the arrow, the barbs give more
+quantitative information about the vector magnitude by putting slanted
+lines or a triangle for various increments in magnitude, as show
+schematically below::
+
+  :                   /\    \
+  :                  /  \    \
+  :                 /    \    \    \
+  :                /      \    \    \
+  :               ------------------------------
+
+The largest increment is given by a triangle (or "flag"). After those
+come full lines (barbs). The smallest increment is a half line.  There
+is only, of course, ever at most 1 half line.  If the magnitude is
+small and only needs a single half-line and no full lines or
+triangles, the half-line is offset from the end of the barb so that it
+can be easily distinguished from barbs with a single full line.  The
+magnitude for the barb shown above would nominally be 65, using the
+standard increments of 50, 10, and 5.
+
+See also https://en.wikipedia.org/wiki/Wind_barb.
+
+Parameters
+----------
+X, Y : 1D or 2D array-like, optional
+    The x and y coordinates of the barb locations. See *pivot* for how the
+    barbs are drawn to the x, y positions.
+
+    If not given, they will be generated as a uniform integer meshgrid based
+    on the dimensions of *U* and *V*.
+
+    If *X* and *Y* are 1D but *U*, *V* are 2D, *X*, *Y* are expanded to 2D
+    using ``X, Y = np.meshgrid(X, Y)``. In this case ``len(X)`` and ``len(Y)``
+    must match the column and row dimensions of *U* and *V*.
+
+U, V : 1D or 2D array-like
+    The x and y components of the barb shaft.
+
+C : 1D or 2D array-like, optional
+    Numeric data that defines the barb colors by colormapping via *norm* and
+    *cmap*.
+
+    This does not support explicit colors. If you want to set colors directly,
+    use *barbcolor* instead.
+
+length : float, default: 7
+    Length of the barb in points; the other parts of the barb
+    are scaled against this.
+
+pivot : {'tip', 'middle'} or float, default: 'tip'
+    The part of the arrow that is anchored to the *X*, *Y* grid. The barb
+    rotates about this point. This can also be a number, which shifts the
+    start of the barb that many points away from grid point.
+
+barbcolor : :mpltype:`color` or color sequence
+    The color of all parts of the barb except for the flags.  This parameter
+    is analogous to the *edgecolor* parameter for polygons, which can be used
+    instead. However this parameter will override facecolor.
+
+flagcolor : :mpltype:`color` or color sequence
+    The color of any flags on the barb.  This parameter is analogous to the
+    *facecolor* parameter for polygons, which can be used instead. However,
+    this parameter will override facecolor.  If this is not set (and *C* has
+    not either) then *flagcolor* will be set to match *barbcolor* so that the
+    barb has a uniform color. If *C* has been set, *flagcolor* has no effect.
+
+sizes : dict, optional
+    A dictionary of coefficients specifying the ratio of a given
+    feature to the length of the barb. Only those values one wishes to
+    override need to be included.  These features include:
+
+    - 'spacing' - space between features (flags, full/half barbs)
+    - 'height' - height (distance from shaft to top) of a flag or full barb
+    - 'width' - width of a flag, twice the width of a full barb
+    - 'emptybarb' - radius of the circle used for low magnitudes
+
+fill_empty : bool, default: False
+    Whether the empty barbs (circles) that are drawn should be filled with
+    the flag color.  If they are not filled, the center is transparent.
+
+rounding : bool, default: True
+    Whether the vector magnitude should be rounded when allocating barb
+    components.  If True, the magnitude is rounded to the nearest multiple
+    of the half-barb increment.  If False, the magnitude is simply truncated
+    to the next lowest multiple.
+
+barb_increments : dict, optional
+    A dictionary of increments specifying values to associate with
+    different parts of the barb. Only those values one wishes to
+    override need to be included.
+
+    - 'half' - half barbs (Default is 5)
+    - 'full' - full barbs (Default is 10)
+    - 'flag' - flags (default is 50)
+
+flip_barb : bool or array-like of bool, default: False
+    Whether the lines and flags should point opposite to normal.
+    Normal behavior is for the barbs and lines to point right (comes from wind
+    barbs having these features point towards low pressure in the Northern
+    Hemisphere).
+
+    A single value is applied to all barbs. Individual barbs can be flipped by
+    passing a bool array of the same size as *U* and *V*.
+
+Returns
+-------
+barbs : `~matplotlib.quiver.Barbs`
+
+Other Parameters
+----------------
+data : indexable object, optional
+    DATA_PARAMETER_PLACEHOLDER
+
+**kwargs
+    The barbs can further be customized using `.PolyCollection` keyword
+    arguments:
+
+    %(PolyCollection:kwdoc)s
+""" % _docstring.interpd.params
+
+_docstring.interpd.register(barbs_doc=_barbs_doc)
+
+
+class Barbs(mcollections.PolyCollection):
+    """
+    Specialized PolyCollection for barbs.
+
+    The only API method is :meth:`set_UVC`, which can be used to
+    change the size, orientation, and color of the arrows.  Locations
+    are changed using the :meth:`set_offsets` collection method.
+    Possibly this method will be useful in animations.
+
+    There is one internal function :meth:`_find_tails` which finds
+    exactly what should be put on the barb given the vector magnitude.
+    From there :meth:`_make_barbs` is used to find the vertices of the
+    polygon to represent the barb based on this information.
+    """
+
+    # This may be an abuse of polygons here to render what is essentially maybe
+    # 1 triangle and a series of lines.  It works fine as far as I can tell
+    # however.
+
+    @_docstring.interpd
+    def __init__(self, ax, *args,
+                 pivot='tip', length=7, barbcolor=None, flagcolor=None,
+                 sizes=None, fill_empty=False, barb_increments=None,
+                 rounding=True, flip_barb=False, **kwargs):
+        """
+        The constructor takes one required argument, an Axes
+        instance, followed by the args and kwargs described
+        by the following pyplot interface documentation:
+        %(barbs_doc)s
+        """
+        self.sizes = sizes or dict()
+        self.fill_empty = fill_empty
+        self.barb_increments = barb_increments or dict()
+        self.rounding = rounding
+        self.flip = np.atleast_1d(flip_barb)
+        transform = kwargs.pop('transform', ax.transData)
+        self._pivot = pivot
+        self._length = length
+
+        # Flagcolor and barbcolor provide convenience parameters for
+        # setting the facecolor and edgecolor, respectively, of the barb
+        # polygon.  We also work here to make the flag the same color as the
+        # rest of the barb by default
+
+        if None in (barbcolor, flagcolor):
+            kwargs['edgecolors'] = 'face'
+            if flagcolor:
+                kwargs['facecolors'] = flagcolor
+            elif barbcolor:
+                kwargs['facecolors'] = barbcolor
+            else:
+                # Set to facecolor passed in or default to black
+                kwargs.setdefault('facecolors', 'k')
+        else:
+            kwargs['edgecolors'] = barbcolor
+            kwargs['facecolors'] = flagcolor
+
+        # Explicitly set a line width if we're not given one, otherwise
+        # polygons are not outlined and we get no barbs
+        if 'linewidth' not in kwargs and 'lw' not in kwargs:
+            kwargs['linewidth'] = 1
+
+        # Parse out the data arrays from the various configurations supported
+        x, y, u, v, c = _parse_args(*args, caller_name='barbs')
+        self.x = x
+        self.y = y
+        xy = np.column_stack((x, y))
+
+        # Make a collection
+        barb_size = self._length ** 2 / 4  # Empirically determined
+        super().__init__(
+            [], (barb_size,), offsets=xy, offset_transform=transform, **kwargs)
+        self.set_transform(transforms.IdentityTransform())
+
+        self.set_UVC(u, v, c)
+
+    def _find_tails(self, mag, rounding=True, half=5, full=10, flag=50):
+        """
+        Find how many of each of the tail pieces is necessary.
+
+        Parameters
+        ----------
+        mag : `~numpy.ndarray`
+            Vector magnitudes; must be non-negative (and an actual ndarray).
+        rounding : bool, default: True
+            Whether to round or to truncate to the nearest half-barb.
+        half, full, flag : float, defaults: 5, 10, 50
+            Increments for a half-barb, a barb, and a flag.
+
+        Returns
+        -------
+        n_flags, n_barbs : int array
+            For each entry in *mag*, the number of flags and barbs.
+        half_flag : bool array
+            For each entry in *mag*, whether a half-barb is needed.
+        empty_flag : bool array
+            For each entry in *mag*, whether nothing is drawn.
+        """
+        # If rounding, round to the nearest multiple of half, the smallest
+        # increment
+        if rounding:
+            mag = half * np.around(mag / half)
+        n_flags, mag = divmod(mag, flag)
+        n_barb, mag = divmod(mag, full)
+        half_flag = mag >= half
+        empty_flag = ~(half_flag | (n_flags > 0) | (n_barb > 0))
+        return n_flags.astype(int), n_barb.astype(int), half_flag, empty_flag
+
+    def _make_barbs(self, u, v, nflags, nbarbs, half_barb, empty_flag, length,
+                    pivot, sizes, fill_empty, flip):
+        """
+        Create the wind barbs.
+
+        Parameters
+        ----------
+        u, v
+            Components of the vector in the x and y directions, respectively.
+
+        nflags, nbarbs, half_barb, empty_flag
+            Respectively, the number of flags, number of barbs, flag for
+            half a barb, and flag for empty barb, ostensibly obtained from
+            :meth:`_find_tails`.
+
+        length
+            The length of the barb staff in points.
+
+        pivot : {"tip", "middle"} or number
+            The point on the barb around which the entire barb should be
+            rotated.  If a number, the start of the barb is shifted by that
+            many points from the origin.
+
+        sizes : dict
+            Coefficients specifying the ratio of a given feature to the length
+            of the barb. These features include:
+
+            - *spacing*: space between features (flags, full/half barbs).
+            - *height*: distance from shaft of top of a flag or full barb.
+            - *width*: width of a flag, twice the width of a full barb.
+            - *emptybarb*: radius of the circle used for low magnitudes.
+
+        fill_empty : bool
+            Whether the circle representing an empty barb should be filled or
+            not (this changes the drawing of the polygon).
+
+        flip : list of bool
+            Whether the features should be flipped to the other side of the
+            barb (useful for winds in the southern hemisphere).
+
+        Returns
+        -------
+        list of arrays of vertices
+            Polygon vertices for each of the wind barbs.  These polygons have
+            been rotated to properly align with the vector direction.
+        """
+
+        # These control the spacing and size of barb elements relative to the
+        # length of the shaft
+        spacing = length * sizes.get('spacing', 0.125)
+        full_height = length * sizes.get('height', 0.4)
+        full_width = length * sizes.get('width', 0.25)
+        empty_rad = length * sizes.get('emptybarb', 0.15)
+
+        # Controls y point where to pivot the barb.
+        pivot_points = dict(tip=0.0, middle=-length / 2.)
+
+        endx = 0.0
+        try:
+            endy = float(pivot)
+        except ValueError:
+            endy = pivot_points[pivot.lower()]
+
+        # Get the appropriate angle for the vector components.  The offset is
+        # due to the way the barb is initially drawn, going down the y-axis.
+        # This makes sense in a meteorological mode of thinking since there 0
+        # degrees corresponds to north (the y-axis traditionally)
+        angles = -(ma.arctan2(v, u) + np.pi / 2)
+
+        # Used for low magnitude.  We just get the vertices, so if we make it
+        # out here, it can be reused.  The center set here should put the
+        # center of the circle at the location(offset), rather than at the
+        # same point as the barb pivot; this seems more sensible.
+        circ = CirclePolygon((0, 0), radius=empty_rad).get_verts()
+        if fill_empty:
+            empty_barb = circ
+        else:
+            # If we don't want the empty one filled, we make a degenerate
+            # polygon that wraps back over itself
+            empty_barb = np.concatenate((circ, circ[::-1]))
+
+        barb_list = []
+        for index, angle in np.ndenumerate(angles):
+            # If the vector magnitude is too weak to draw anything, plot an
+            # empty circle instead
+            if empty_flag[index]:
+                # We can skip the transform since the circle has no preferred
+                # orientation
+                barb_list.append(empty_barb)
+                continue
+
+            poly_verts = [(endx, endy)]
+            offset = length
+
+            # Handle if this barb should be flipped
+            barb_height = -full_height if flip[index] else full_height
+
+            # Add vertices for each flag
+            for i in range(nflags[index]):
+                # The spacing that works for the barbs is a little to much for
+                # the flags, but this only occurs when we have more than 1
+                # flag.
+                if offset != length:
+                    offset += spacing / 2.
+                poly_verts.extend(
+                    [[endx, endy + offset],
+                     [endx + barb_height, endy - full_width / 2 + offset],
+                     [endx, endy - full_width + offset]])
+
+                offset -= full_width + spacing
+
+            # Add vertices for each barb.  These really are lines, but works
+            # great adding 3 vertices that basically pull the polygon out and
+            # back down the line
+            for i in range(nbarbs[index]):
+                poly_verts.extend(
+                    [(endx, endy + offset),
+                     (endx + barb_height, endy + offset + full_width / 2),
+                     (endx, endy + offset)])
+
+                offset -= spacing
+
+            # Add the vertices for half a barb, if needed
+            if half_barb[index]:
+                # If the half barb is the first on the staff, traditionally it
+                # is offset from the end to make it easy to distinguish from a
+                # barb with a full one
+                if offset == length:
+                    poly_verts.append((endx, endy + offset))
+                    offset -= 1.5 * spacing
+                poly_verts.extend(
+                    [(endx, endy + offset),
+                     (endx + barb_height / 2, endy + offset + full_width / 4),
+                     (endx, endy + offset)])
+
+            # Rotate the barb according the angle. Making the barb first and
+            # then rotating it made the math for drawing the barb really easy.
+            # Also, the transform framework makes doing the rotation simple.
+            poly_verts = transforms.Affine2D().rotate(-angle).transform(
+                poly_verts)
+            barb_list.append(poly_verts)
+
+        return barb_list
+
+    def set_UVC(self, U, V, C=None):
+        # We need to ensure we have a copy, not a reference to an array that
+        # might change before draw().
+        self.u = ma.masked_invalid(U, copy=True).ravel()
+        self.v = ma.masked_invalid(V, copy=True).ravel()
+
+        # Flip needs to have the same number of entries as everything else.
+        # Use broadcast_to to avoid a bloated array of identical values.
+        # (can't rely on actual broadcasting)
+        if len(self.flip) == 1:
+            flip = np.broadcast_to(self.flip, self.u.shape)
+        else:
+            flip = self.flip
+
+        if C is not None:
+            c = ma.masked_invalid(C, copy=True).ravel()
+            x, y, u, v, c, flip = cbook.delete_masked_points(
+                self.x.ravel(), self.y.ravel(), self.u, self.v, c,
+                flip.ravel())
+            _check_consistent_shapes(x, y, u, v, c, flip)
+        else:
+            x, y, u, v, flip = cbook.delete_masked_points(
+                self.x.ravel(), self.y.ravel(), self.u, self.v, flip.ravel())
+            _check_consistent_shapes(x, y, u, v, flip)
+
+        magnitude = np.hypot(u, v)
+        flags, barbs, halves, empty = self._find_tails(
+            magnitude, self.rounding, **self.barb_increments)
+
+        # Get the vertices for each of the barbs
+
+        plot_barbs = self._make_barbs(u, v, flags, barbs, halves, empty,
+                                      self._length, self._pivot, self.sizes,
+                                      self.fill_empty, flip)
+        self.set_verts(plot_barbs)
+
+        # Set the color array
+        if C is not None:
+            self.set_array(c)
+
+        # Update the offsets in case the masked data changed
+        xy = np.column_stack((x, y))
+        self._offsets = xy
+        self.stale = True
+
+    def set_offsets(self, xy):
+        """
+        Set the offsets for the barb polygons.  This saves the offsets passed
+        in and masks them as appropriate for the existing U/V data.
+
+        Parameters
+        ----------
+        xy : sequence of pairs of floats
+        """
+        self.x = xy[:, 0]
+        self.y = xy[:, 1]
+        x, y, u, v = cbook.delete_masked_points(
+            self.x.ravel(), self.y.ravel(), self.u, self.v)
+        _check_consistent_shapes(x, y, u, v)
+        xy = np.column_stack((x, y))
+        super().set_offsets(xy)
+        self.stale = True
diff --git a/lib/python3.12/site-packages/matplotlib/rcsetup.py b/lib/python3.12/site-packages/matplotlib/rcsetup.py
new file mode 100644
index 0000000000000000000000000000000000000000..c23d9f818454cda653ed6e2b08f6bb0e1045cbf4
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/rcsetup.py
@@ -0,0 +1,1371 @@
+"""
+The rcsetup module contains the validation code for customization using
+Matplotlib's rc settings.
+
+Each rc setting is assigned a function used to validate any attempted changes
+to that setting.  The validation functions are defined in the rcsetup module,
+and are used to construct the rcParams global object which stores the settings
+and is referenced throughout Matplotlib.
+
+The default values of the rc settings are set in the default matplotlibrc file.
+Any additions or deletions to the parameter set listed here should also be
+propagated to the :file:`lib/matplotlib/mpl-data/matplotlibrc` in Matplotlib's
+root source directory.
+"""
+
+import ast
+from functools import lru_cache, reduce
+from numbers import Real
+import operator
+import os
+import re
+
+import numpy as np
+
+from matplotlib import _api, cbook
+from matplotlib.backends import BackendFilter, backend_registry
+from matplotlib.cbook import ls_mapper
+from matplotlib.colors import Colormap, is_color_like
+from matplotlib._fontconfig_pattern import parse_fontconfig_pattern
+from matplotlib._enums import JoinStyle, CapStyle
+
+# Don't let the original cycler collide with our validating cycler
+from cycler import Cycler, cycler as ccycler
+
+
+@_api.caching_module_getattr
+class __getattr__:
+    @_api.deprecated(
+        "3.9",
+        alternative="``matplotlib.backends.backend_registry.list_builtin"
+            "(matplotlib.backends.BackendFilter.INTERACTIVE)``")
+    @property
+    def interactive_bk(self):
+        return backend_registry.list_builtin(BackendFilter.INTERACTIVE)
+
+    @_api.deprecated(
+        "3.9",
+        alternative="``matplotlib.backends.backend_registry.list_builtin"
+            "(matplotlib.backends.BackendFilter.NON_INTERACTIVE)``")
+    @property
+    def non_interactive_bk(self):
+        return backend_registry.list_builtin(BackendFilter.NON_INTERACTIVE)
+
+    @_api.deprecated(
+        "3.9",
+        alternative="``matplotlib.backends.backend_registry.list_builtin()``")
+    @property
+    def all_backends(self):
+        return backend_registry.list_builtin()
+
+
+class ValidateInStrings:
+    def __init__(self, key, valid, ignorecase=False, *,
+                 _deprecated_since=None):
+        """*valid* is a list of legal strings."""
+        self.key = key
+        self.ignorecase = ignorecase
+        self._deprecated_since = _deprecated_since
+
+        def func(s):
+            if ignorecase:
+                return s.lower()
+            else:
+                return s
+        self.valid = {func(k): k for k in valid}
+
+    def __call__(self, s):
+        if self._deprecated_since:
+            name, = (k for k, v in globals().items() if v is self)
+            _api.warn_deprecated(
+                self._deprecated_since, name=name, obj_type="function")
+        if self.ignorecase and isinstance(s, str):
+            s = s.lower()
+        if s in self.valid:
+            return self.valid[s]
+        msg = (f"{s!r} is not a valid value for {self.key}; supported values "
+               f"are {[*self.valid.values()]}")
+        if (isinstance(s, str)
+                and (s.startswith('"') and s.endswith('"')
+                     or s.startswith("'") and s.endswith("'"))
+                and s[1:-1] in self.valid):
+            msg += "; remove quotes surrounding your string"
+        raise ValueError(msg)
+
+
+@lru_cache
+def _listify_validator(scalar_validator, allow_stringlist=False, *,
+                       n=None, doc=None):
+    def f(s):
+        if isinstance(s, str):
+            try:
+                val = [scalar_validator(v.strip()) for v in s.split(',')
+                       if v.strip()]
+            except Exception:
+                if allow_stringlist:
+                    # Sometimes, a list of colors might be a single string
+                    # of single-letter colornames. So give that a shot.
+                    val = [scalar_validator(v.strip()) for v in s if v.strip()]
+                else:
+                    raise
+        # Allow any ordered sequence type -- generators, np.ndarray, pd.Series
+        # -- but not sets, whose iteration order is non-deterministic.
+        elif np.iterable(s) and not isinstance(s, (set, frozenset)):
+            # The condition on this list comprehension will preserve the
+            # behavior of filtering out any empty strings (behavior was
+            # from the original validate_stringlist()), while allowing
+            # any non-string/text scalar values such as numbers and arrays.
+            val = [scalar_validator(v) for v in s
+                   if not isinstance(v, str) or v]
+        else:
+            raise ValueError(
+                f"Expected str or other non-set iterable, but got {s}")
+        if n is not None and len(val) != n:
+            raise ValueError(
+                f"Expected {n} values, but there are {len(val)} values in {s}")
+        return val
+
+    try:
+        f.__name__ = f"{scalar_validator.__name__}list"
+    except AttributeError:  # class instance.
+        f.__name__ = f"{type(scalar_validator).__name__}List"
+    f.__qualname__ = f.__qualname__.rsplit(".", 1)[0] + "." + f.__name__
+    f.__doc__ = doc if doc is not None else scalar_validator.__doc__
+    return f
+
+
+def validate_any(s):
+    return s
+validate_anylist = _listify_validator(validate_any)
+
+
+def _validate_date(s):
+    try:
+        np.datetime64(s)
+        return s
+    except ValueError:
+        raise ValueError(
+            f'{s!r} should be a string that can be parsed by numpy.datetime64')
+
+
+def validate_bool(b):
+    """Convert b to ``bool`` or raise."""
+    if isinstance(b, str):
+        b = b.lower()
+    if b in ('t', 'y', 'yes', 'on', 'true', '1', 1, True):
+        return True
+    elif b in ('f', 'n', 'no', 'off', 'false', '0', 0, False):
+        return False
+    else:
+        raise ValueError(f'Cannot convert {b!r} to bool')
+
+
+def validate_axisbelow(s):
+    try:
+        return validate_bool(s)
+    except ValueError:
+        if isinstance(s, str):
+            if s == 'line':
+                return 'line'
+    raise ValueError(f'{s!r} cannot be interpreted as'
+                     ' True, False, or "line"')
+
+
+def validate_dpi(s):
+    """Confirm s is string 'figure' or convert s to float or raise."""
+    if s == 'figure':
+        return s
+    try:
+        return float(s)
+    except ValueError as e:
+        raise ValueError(f'{s!r} is not string "figure" and '
+                         f'could not convert {s!r} to float') from e
+
+
+def _make_type_validator(cls, *, allow_none=False):
+    """
+    Return a validator that converts inputs to *cls* or raises (and possibly
+    allows ``None`` as well).
+    """
+
+    def validator(s):
+        if (allow_none and
+                (s is None or cbook._str_lower_equal(s, "none"))):
+            return None
+        if cls is str and not isinstance(s, str):
+            raise ValueError(f'Could not convert {s!r} to str')
+        try:
+            return cls(s)
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f'Could not convert {s!r} to {cls.__name__}') from e
+
+    validator.__name__ = f"validate_{cls.__name__}"
+    if allow_none:
+        validator.__name__ += "_or_None"
+    validator.__qualname__ = (
+        validator.__qualname__.rsplit(".", 1)[0] + "." + validator.__name__)
+    return validator
+
+
+validate_string = _make_type_validator(str)
+validate_string_or_None = _make_type_validator(str, allow_none=True)
+validate_stringlist = _listify_validator(
+    validate_string, doc='return a list of strings')
+validate_int = _make_type_validator(int)
+validate_int_or_None = _make_type_validator(int, allow_none=True)
+validate_float = _make_type_validator(float)
+validate_float_or_None = _make_type_validator(float, allow_none=True)
+validate_floatlist = _listify_validator(
+    validate_float, doc='return a list of floats')
+
+
+def _validate_marker(s):
+    try:
+        return validate_int(s)
+    except ValueError as e:
+        try:
+            return validate_string(s)
+        except ValueError as e:
+            raise ValueError('Supported markers are [string, int]') from e
+
+
+_validate_markerlist = _listify_validator(
+    _validate_marker, doc='return a list of markers')
+
+
+def _validate_pathlike(s):
+    if isinstance(s, (str, os.PathLike)):
+        # Store value as str because savefig.directory needs to distinguish
+        # between "" (cwd) and "." (cwd, but gets updated by user selections).
+        return os.fsdecode(s)
+    else:
+        return validate_string(s)
+
+
+def validate_fonttype(s):
+    """
+    Confirm that this is a Postscript or PDF font type that we know how to
+    convert to.
+    """
+    fonttypes = {'type3':    3,
+                 'truetype': 42}
+    try:
+        fonttype = validate_int(s)
+    except ValueError:
+        try:
+            return fonttypes[s.lower()]
+        except KeyError as e:
+            raise ValueError('Supported Postscript/PDF font types are %s'
+                             % list(fonttypes)) from e
+    else:
+        if fonttype not in fonttypes.values():
+            raise ValueError(
+                'Supported Postscript/PDF font types are %s' %
+                list(fonttypes.values()))
+        return fonttype
+
+
+_auto_backend_sentinel = object()
+
+
+def validate_backend(s):
+    if s is _auto_backend_sentinel or backend_registry.is_valid_backend(s):
+        return s
+    else:
+        msg = (f"'{s}' is not a valid value for backend; supported values are "
+               f"{backend_registry.list_all()}")
+        raise ValueError(msg)
+
+
+def _validate_toolbar(s):
+    s = ValidateInStrings(
+        'toolbar', ['None', 'toolbar2', 'toolmanager'], ignorecase=True)(s)
+    if s == 'toolmanager':
+        _api.warn_external(
+            "Treat the new Tool classes introduced in v1.5 as experimental "
+            "for now; the API and rcParam may change in future versions.")
+    return s
+
+
+def validate_color_or_inherit(s):
+    """Return a valid color arg."""
+    if cbook._str_equal(s, 'inherit'):
+        return s
+    return validate_color(s)
+
+
+def validate_color_or_auto(s):
+    if cbook._str_equal(s, 'auto'):
+        return s
+    return validate_color(s)
+
+
+def validate_color_for_prop_cycle(s):
+    # N-th color cycle syntax can't go into the color cycle.
+    if isinstance(s, str) and re.match("^C[0-9]$", s):
+        raise ValueError(f"Cannot put cycle reference ({s!r}) in prop_cycler")
+    return validate_color(s)
+
+
+def _validate_color_or_linecolor(s):
+    if cbook._str_equal(s, 'linecolor'):
+        return s
+    elif cbook._str_equal(s, 'mfc') or cbook._str_equal(s, 'markerfacecolor'):
+        return 'markerfacecolor'
+    elif cbook._str_equal(s, 'mec') or cbook._str_equal(s, 'markeredgecolor'):
+        return 'markeredgecolor'
+    elif s is None:
+        return None
+    elif isinstance(s, str) and len(s) == 6 or len(s) == 8:
+        stmp = '#' + s
+        if is_color_like(stmp):
+            return stmp
+        if s.lower() == 'none':
+            return None
+    elif is_color_like(s):
+        return s
+
+    raise ValueError(f'{s!r} does not look like a color arg')
+
+
+def validate_color(s):
+    """Return a valid color arg."""
+    if isinstance(s, str):
+        if s.lower() == 'none':
+            return 'none'
+        if len(s) == 6 or len(s) == 8:
+            stmp = '#' + s
+            if is_color_like(stmp):
+                return stmp
+
+    if is_color_like(s):
+        return s
+
+    # If it is still valid, it must be a tuple (as a string from matplotlibrc).
+    try:
+        color = ast.literal_eval(s)
+    except (SyntaxError, ValueError):
+        pass
+    else:
+        if is_color_like(color):
+            return color
+
+    raise ValueError(f'{s!r} does not look like a color arg')
+
+
+validate_colorlist = _listify_validator(
+    validate_color, allow_stringlist=True, doc='return a list of colorspecs')
+
+
+def _validate_cmap(s):
+    _api.check_isinstance((str, Colormap), cmap=s)
+    return s
+
+
+def validate_aspect(s):
+    if s in ('auto', 'equal'):
+        return s
+    try:
+        return float(s)
+    except ValueError as e:
+        raise ValueError('not a valid aspect specification') from e
+
+
+def validate_fontsize_None(s):
+    if s is None or s == 'None':
+        return None
+    else:
+        return validate_fontsize(s)
+
+
+def validate_fontsize(s):
+    fontsizes = ['xx-small', 'x-small', 'small', 'medium', 'large',
+                 'x-large', 'xx-large', 'smaller', 'larger']
+    if isinstance(s, str):
+        s = s.lower()
+    if s in fontsizes:
+        return s
+    try:
+        return float(s)
+    except ValueError as e:
+        raise ValueError("%s is not a valid font size. Valid font sizes "
+                         "are %s." % (s, ", ".join(fontsizes))) from e
+
+
+validate_fontsizelist = _listify_validator(validate_fontsize)
+
+
+def validate_fontweight(s):
+    weights = [
+        'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman',
+        'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black']
+    # Note: Historically, weights have been case-sensitive in Matplotlib
+    if s in weights:
+        return s
+    try:
+        return int(s)
+    except (ValueError, TypeError) as e:
+        raise ValueError(f'{s} is not a valid font weight.') from e
+
+
+def validate_fontstretch(s):
+    stretchvalues = [
+        'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed',
+        'normal', 'semi-expanded', 'expanded', 'extra-expanded',
+        'ultra-expanded']
+    # Note: Historically, stretchvalues have been case-sensitive in Matplotlib
+    if s in stretchvalues:
+        return s
+    try:
+        return int(s)
+    except (ValueError, TypeError) as e:
+        raise ValueError(f'{s} is not a valid font stretch.') from e
+
+
+def validate_font_properties(s):
+    parse_fontconfig_pattern(s)
+    return s
+
+
+def _validate_mathtext_fallback(s):
+    _fallback_fonts = ['cm', 'stix', 'stixsans']
+    if isinstance(s, str):
+        s = s.lower()
+    if s is None or s == 'none':
+        return None
+    elif s.lower() in _fallback_fonts:
+        return s
+    else:
+        raise ValueError(
+            f"{s} is not a valid fallback font name. Valid fallback font "
+            f"names are {','.join(_fallback_fonts)}. Passing 'None' will turn "
+            "fallback off.")
+
+
+def validate_whiskers(s):
+    try:
+        return _listify_validator(validate_float, n=2)(s)
+    except (TypeError, ValueError):
+        try:
+            return float(s)
+        except ValueError as e:
+            raise ValueError("Not a valid whisker value [float, "
+                             "(float, float)]") from e
+
+
+def validate_ps_distiller(s):
+    if isinstance(s, str):
+        s = s.lower()
+    if s in ('none', None, 'false', False):
+        return None
+    else:
+        return ValidateInStrings('ps.usedistiller', ['ghostscript', 'xpdf'])(s)
+
+
+# A validator dedicated to the named line styles, based on the items in
+# ls_mapper, and a list of possible strings read from Line2D.set_linestyle
+_validate_named_linestyle = ValidateInStrings(
+    'linestyle',
+    [*ls_mapper.keys(), *ls_mapper.values(), 'None', 'none', ' ', ''],
+    ignorecase=True)
+
+
+def _validate_linestyle(ls):
+    """
+    A validator for all possible line styles, the named ones *and*
+    the on-off ink sequences.
+    """
+    if isinstance(ls, str):
+        try:  # Look first for a valid named line style, like '--' or 'solid'.
+            return _validate_named_linestyle(ls)
+        except ValueError:
+            pass
+        try:
+            ls = ast.literal_eval(ls)  # Parsing matplotlibrc.
+        except (SyntaxError, ValueError):
+            pass  # Will error with the ValueError at the end.
+
+    def _is_iterable_not_string_like(x):
+        # Explicitly exclude bytes/bytearrays so that they are not
+        # nonsensically interpreted as sequences of numbers (codepoints).
+        return np.iterable(x) and not isinstance(x, (str, bytes, bytearray))
+
+    if _is_iterable_not_string_like(ls):
+        if len(ls) == 2 and _is_iterable_not_string_like(ls[1]):
+            # (offset, (on, off, on, off, ...))
+            offset, onoff = ls
+        else:
+            # For backcompat: (on, off, on, off, ...); the offset is implicit.
+            offset = 0
+            onoff = ls
+
+        if (isinstance(offset, Real)
+                and len(onoff) % 2 == 0
+                and all(isinstance(elem, Real) for elem in onoff)):
+            return (offset, onoff)
+
+    raise ValueError(f"linestyle {ls!r} is not a valid on-off ink sequence.")
+
+
+validate_fillstyle = ValidateInStrings(
+    'markers.fillstyle', ['full', 'left', 'right', 'bottom', 'top', 'none'])
+
+
+validate_fillstylelist = _listify_validator(validate_fillstyle)
+
+
+def validate_markevery(s):
+    """
+    Validate the markevery property of a Line2D object.
+
+    Parameters
+    ----------
+    s : None, int, (int, int), slice, float, (float, float), or list[int]
+
+    Returns
+    -------
+    None, int, (int, int), slice, float, (float, float), or list[int]
+    """
+    # Validate s against type slice float int and None
+    if isinstance(s, (slice, float, int, type(None))):
+        return s
+    # Validate s against type tuple
+    if isinstance(s, tuple):
+        if (len(s) == 2
+                and (all(isinstance(e, int) for e in s)
+                     or all(isinstance(e, float) for e in s))):
+            return s
+        else:
+            raise TypeError(
+                "'markevery' tuple must be pair of ints or of floats")
+    # Validate s against type list
+    if isinstance(s, list):
+        if all(isinstance(e, int) for e in s):
+            return s
+        else:
+            raise TypeError(
+                "'markevery' list must have all elements of type int")
+    raise TypeError("'markevery' is of an invalid type")
+
+
+validate_markeverylist = _listify_validator(validate_markevery)
+
+
+def validate_bbox(s):
+    if isinstance(s, str):
+        s = s.lower()
+        if s == 'tight':
+            return s
+        if s == 'standard':
+            return None
+        raise ValueError("bbox should be 'tight' or 'standard'")
+    elif s is not None:
+        # Backwards compatibility. None is equivalent to 'standard'.
+        raise ValueError("bbox should be 'tight' or 'standard'")
+    return s
+
+
+def validate_sketch(s):
+
+    if isinstance(s, str):
+        s = s.lower().strip()
+        if s.startswith("(") and s.endswith(")"):
+            s = s[1:-1]
+    if s == 'none' or s is None:
+        return None
+    try:
+        return tuple(_listify_validator(validate_float, n=3)(s))
+    except ValueError as exc:
+        raise ValueError("Expected a (scale, length, randomness) tuple") from exc
+
+
+def _validate_greaterthan_minushalf(s):
+    s = validate_float(s)
+    if s > -0.5:
+        return s
+    else:
+        raise RuntimeError(f'Value must be >-0.5; got {s}')
+
+
+def _validate_greaterequal0_lessequal1(s):
+    s = validate_float(s)
+    if 0 <= s <= 1:
+        return s
+    else:
+        raise RuntimeError(f'Value must be >=0 and <=1; got {s}')
+
+
+def _validate_int_greaterequal0(s):
+    s = validate_int(s)
+    if s >= 0:
+        return s
+    else:
+        raise RuntimeError(f'Value must be >=0; got {s}')
+
+
+def validate_hatch(s):
+    r"""
+    Validate a hatch pattern.
+    A hatch pattern string can have any sequence of the following
+    characters: ``\ / | - + * . x o O``.
+    """
+    if not isinstance(s, str):
+        raise ValueError("Hatch pattern must be a string")
+    _api.check_isinstance(str, hatch_pattern=s)
+    unknown = set(s) - {'\\', '/', '|', '-', '+', '*', '.', 'x', 'o', 'O'}
+    if unknown:
+        raise ValueError("Unknown hatch symbol(s): %s" % list(unknown))
+    return s
+
+
+validate_hatchlist = _listify_validator(validate_hatch)
+validate_dashlist = _listify_validator(validate_floatlist)
+
+
+def _validate_minor_tick_ndivs(n):
+    """
+    Validate ndiv parameter related to the minor ticks.
+    It controls the number of minor ticks to be placed between
+    two major ticks.
+    """
+
+    if cbook._str_lower_equal(n, 'auto'):
+        return n
+    try:
+        n = _validate_int_greaterequal0(n)
+        return n
+    except (RuntimeError, ValueError):
+        pass
+
+    raise ValueError("'tick.minor.ndivs' must be 'auto' or non-negative int")
+
+
+_prop_validators = {
+        'color': _listify_validator(validate_color_for_prop_cycle,
+                                    allow_stringlist=True),
+        'linewidth': validate_floatlist,
+        'linestyle': _listify_validator(_validate_linestyle),
+        'facecolor': validate_colorlist,
+        'edgecolor': validate_colorlist,
+        'joinstyle': _listify_validator(JoinStyle),
+        'capstyle': _listify_validator(CapStyle),
+        'fillstyle': validate_fillstylelist,
+        'markerfacecolor': validate_colorlist,
+        'markersize': validate_floatlist,
+        'markeredgewidth': validate_floatlist,
+        'markeredgecolor': validate_colorlist,
+        'markevery': validate_markeverylist,
+        'alpha': validate_floatlist,
+        'marker': _validate_markerlist,
+        'hatch': validate_hatchlist,
+        'dashes': validate_dashlist,
+    }
+_prop_aliases = {
+        'c': 'color',
+        'lw': 'linewidth',
+        'ls': 'linestyle',
+        'fc': 'facecolor',
+        'ec': 'edgecolor',
+        'mfc': 'markerfacecolor',
+        'mec': 'markeredgecolor',
+        'mew': 'markeredgewidth',
+        'ms': 'markersize',
+    }
+
+
+def cycler(*args, **kwargs):
+    """
+    Create a `~cycler.Cycler` object much like :func:`cycler.cycler`,
+    but includes input validation.
+
+    Call signatures::
+
+      cycler(cycler)
+      cycler(label=values, label2=values2, ...)
+      cycler(label, values)
+
+    Form 1 copies a given `~cycler.Cycler` object.
+
+    Form 2 creates a `~cycler.Cycler` which cycles over one or more
+    properties simultaneously. If multiple properties are given, their
+    value lists must have the same length.
+
+    Form 3 creates a `~cycler.Cycler` for a single property. This form
+    exists for compatibility with the original cycler. Its use is
+    discouraged in favor of the kwarg form, i.e. ``cycler(label=values)``.
+
+    Parameters
+    ----------
+    cycler : Cycler
+        Copy constructor for Cycler.
+
+    label : str
+        The property key. Must be a valid `.Artist` property.
+        For example, 'color' or 'linestyle'. Aliases are allowed,
+        such as 'c' for 'color' and 'lw' for 'linewidth'.
+
+    values : iterable
+        Finite-length iterable of the property values. These values
+        are validated and will raise a ValueError if invalid.
+
+    Returns
+    -------
+    Cycler
+        A new :class:`~cycler.Cycler` for the given properties.
+
+    Examples
+    --------
+    Creating a cycler for a single property:
+
+    >>> c = cycler(color=['red', 'green', 'blue'])
+
+    Creating a cycler for simultaneously cycling over multiple properties
+    (e.g. red circle, green plus, blue cross):
+
+    >>> c = cycler(color=['red', 'green', 'blue'],
+    ...            marker=['o', '+', 'x'])
+
+    """
+    if args and kwargs:
+        raise TypeError("cycler() can only accept positional OR keyword "
+                        "arguments -- not both.")
+    elif not args and not kwargs:
+        raise TypeError("cycler() must have positional OR keyword arguments")
+
+    if len(args) == 1:
+        if not isinstance(args[0], Cycler):
+            raise TypeError("If only one positional argument given, it must "
+                            "be a Cycler instance.")
+        return validate_cycler(args[0])
+    elif len(args) == 2:
+        pairs = [(args[0], args[1])]
+    elif len(args) > 2:
+        raise _api.nargs_error('cycler', '0-2', len(args))
+    else:
+        pairs = kwargs.items()
+
+    validated = []
+    for prop, vals in pairs:
+        norm_prop = _prop_aliases.get(prop, prop)
+        validator = _prop_validators.get(norm_prop, None)
+        if validator is None:
+            raise TypeError("Unknown artist property: %s" % prop)
+        vals = validator(vals)
+        # We will normalize the property names as well to reduce
+        # the amount of alias handling code elsewhere.
+        validated.append((norm_prop, vals))
+
+    return reduce(operator.add, (ccycler(k, v) for k, v in validated))
+
+
+class _DunderChecker(ast.NodeVisitor):
+    def visit_Attribute(self, node):
+        if node.attr.startswith("__") and node.attr.endswith("__"):
+            raise ValueError("cycler strings with dunders are forbidden")
+        self.generic_visit(node)
+
+
+# A validator dedicated to the named legend loc
+_validate_named_legend_loc = ValidateInStrings(
+    'legend.loc',
+    [
+        "best",
+        "upper right", "upper left", "lower left", "lower right", "right",
+        "center left", "center right", "lower center", "upper center",
+        "center"],
+    ignorecase=True)
+
+
+def _validate_legend_loc(loc):
+    """
+    Confirm that loc is a type which rc.Params["legend.loc"] supports.
+
+    .. versionadded:: 3.8
+
+    Parameters
+    ----------
+    loc : str | int | (float, float) | str((float, float))
+        The location of the legend.
+
+    Returns
+    -------
+    loc : str | int | (float, float) or raise ValueError exception
+        The location of the legend.
+    """
+    if isinstance(loc, str):
+        try:
+            return _validate_named_legend_loc(loc)
+        except ValueError:
+            pass
+        try:
+            loc = ast.literal_eval(loc)
+        except (SyntaxError, ValueError):
+            pass
+    if isinstance(loc, int):
+        if 0 <= loc <= 10:
+            return loc
+    if isinstance(loc, tuple):
+        if len(loc) == 2 and all(isinstance(e, Real) for e in loc):
+            return loc
+    raise ValueError(f"{loc} is not a valid legend location.")
+
+
+def validate_cycler(s):
+    """Return a Cycler object from a string repr or the object itself."""
+    if isinstance(s, str):
+        # TODO: We might want to rethink this...
+        # While I think I have it quite locked down, it is execution of
+        # arbitrary code without sanitation.
+        # Combine this with the possibility that rcparams might come from the
+        # internet (future plans), this could be downright dangerous.
+        # I locked it down by only having the 'cycler()' function available.
+        # UPDATE: Partly plugging a security hole.
+        # I really should have read this:
+        # https://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html
+        # We should replace this eval with a combo of PyParsing and
+        # ast.literal_eval()
+        try:
+            _DunderChecker().visit(ast.parse(s))
+            s = eval(s, {'cycler': cycler, '__builtins__': {}})
+        except BaseException as e:
+            raise ValueError(f"{s!r} is not a valid cycler construction: {e}"
+                             ) from e
+    # Should make sure what comes from the above eval()
+    # is a Cycler object.
+    if isinstance(s, Cycler):
+        cycler_inst = s
+    else:
+        raise ValueError(f"Object is not a string or Cycler instance: {s!r}")
+
+    unknowns = cycler_inst.keys - (set(_prop_validators) | set(_prop_aliases))
+    if unknowns:
+        raise ValueError("Unknown artist properties: %s" % unknowns)
+
+    # Not a full validation, but it'll at least normalize property names
+    # A fuller validation would require v0.10 of cycler.
+    checker = set()
+    for prop in cycler_inst.keys:
+        norm_prop = _prop_aliases.get(prop, prop)
+        if norm_prop != prop and norm_prop in cycler_inst.keys:
+            raise ValueError(f"Cannot specify both {norm_prop!r} and alias "
+                             f"{prop!r} in the same prop_cycle")
+        if norm_prop in checker:
+            raise ValueError(f"Another property was already aliased to "
+                             f"{norm_prop!r}. Collision normalizing {prop!r}.")
+        checker.update([norm_prop])
+
+    # This is just an extra-careful check, just in case there is some
+    # edge-case I haven't thought of.
+    assert len(checker) == len(cycler_inst.keys)
+
+    # Now, it should be safe to mutate this cycler
+    for prop in cycler_inst.keys:
+        norm_prop = _prop_aliases.get(prop, prop)
+        cycler_inst.change_key(prop, norm_prop)
+
+    for key, vals in cycler_inst.by_key().items():
+        _prop_validators[key](vals)
+
+    return cycler_inst
+
+
+def validate_hist_bins(s):
+    valid_strs = ["auto", "sturges", "fd", "doane", "scott", "rice", "sqrt"]
+    if isinstance(s, str) and s in valid_strs:
+        return s
+    try:
+        return int(s)
+    except (TypeError, ValueError):
+        pass
+    try:
+        return validate_floatlist(s)
+    except ValueError:
+        pass
+    raise ValueError(f"'hist.bins' must be one of {valid_strs}, an int or"
+                     " a sequence of floats")
+
+
+class _ignorecase(list):
+    """A marker class indicating that a list-of-str is case-insensitive."""
+
+
+def _convert_validator_spec(key, conv):
+    if isinstance(conv, list):
+        ignorecase = isinstance(conv, _ignorecase)
+        return ValidateInStrings(key, conv, ignorecase=ignorecase)
+    else:
+        return conv
+
+
+# Mapping of rcParams to validators.
+# Converters given as lists or _ignorecase are converted to ValidateInStrings
+# immediately below.
+# The rcParams defaults are defined in lib/matplotlib/mpl-data/matplotlibrc, which
+# gets copied to matplotlib/mpl-data/matplotlibrc by the setup script.
+_validators = {
+    "backend":           validate_backend,
+    "backend_fallback":  validate_bool,
+    "figure.hooks":      validate_stringlist,
+    "toolbar":           _validate_toolbar,
+    "interactive":       validate_bool,
+    "timezone":          validate_string,
+
+    "webagg.port":            validate_int,
+    "webagg.address":         validate_string,
+    "webagg.open_in_browser": validate_bool,
+    "webagg.port_retries":    validate_int,
+
+    # line props
+    "lines.linewidth":       validate_float,  # line width in points
+    "lines.linestyle":       _validate_linestyle,  # solid line
+    "lines.color":           validate_color,  # first color in color cycle
+    "lines.marker":          _validate_marker,  # marker name
+    "lines.markerfacecolor": validate_color_or_auto,  # default color
+    "lines.markeredgecolor": validate_color_or_auto,  # default color
+    "lines.markeredgewidth": validate_float,
+    "lines.markersize":      validate_float,  # markersize, in points
+    "lines.antialiased":     validate_bool,  # antialiased (no jaggies)
+    "lines.dash_joinstyle":  JoinStyle,
+    "lines.solid_joinstyle": JoinStyle,
+    "lines.dash_capstyle":   CapStyle,
+    "lines.solid_capstyle":  CapStyle,
+    "lines.dashed_pattern":  validate_floatlist,
+    "lines.dashdot_pattern": validate_floatlist,
+    "lines.dotted_pattern":  validate_floatlist,
+    "lines.scale_dashes":    validate_bool,
+
+    # marker props
+    "markers.fillstyle": validate_fillstyle,
+
+    ## pcolor(mesh) props:
+    "pcolor.shading": ["auto", "flat", "nearest", "gouraud"],
+    "pcolormesh.snap": validate_bool,
+
+    ## patch props
+    "patch.linewidth":       validate_float,  # line width in points
+    "patch.edgecolor":       validate_color,
+    "patch.force_edgecolor": validate_bool,
+    "patch.facecolor":       validate_color,  # first color in cycle
+    "patch.antialiased":     validate_bool,  # antialiased (no jaggies)
+
+    ## hatch props
+    "hatch.color":     validate_color,
+    "hatch.linewidth": validate_float,
+
+    ## Histogram properties
+    "hist.bins": validate_hist_bins,
+
+    ## Boxplot properties
+    "boxplot.notch":       validate_bool,
+    "boxplot.vertical":    validate_bool,
+    "boxplot.whiskers":    validate_whiskers,
+    "boxplot.bootstrap":   validate_int_or_None,
+    "boxplot.patchartist": validate_bool,
+    "boxplot.showmeans":   validate_bool,
+    "boxplot.showcaps":    validate_bool,
+    "boxplot.showbox":     validate_bool,
+    "boxplot.showfliers":  validate_bool,
+    "boxplot.meanline":    validate_bool,
+
+    "boxplot.flierprops.color":           validate_color,
+    "boxplot.flierprops.marker":          _validate_marker,
+    "boxplot.flierprops.markerfacecolor": validate_color_or_auto,
+    "boxplot.flierprops.markeredgecolor": validate_color,
+    "boxplot.flierprops.markeredgewidth": validate_float,
+    "boxplot.flierprops.markersize":      validate_float,
+    "boxplot.flierprops.linestyle":       _validate_linestyle,
+    "boxplot.flierprops.linewidth":       validate_float,
+
+    "boxplot.boxprops.color":     validate_color,
+    "boxplot.boxprops.linewidth": validate_float,
+    "boxplot.boxprops.linestyle": _validate_linestyle,
+
+    "boxplot.whiskerprops.color":     validate_color,
+    "boxplot.whiskerprops.linewidth": validate_float,
+    "boxplot.whiskerprops.linestyle": _validate_linestyle,
+
+    "boxplot.capprops.color":     validate_color,
+    "boxplot.capprops.linewidth": validate_float,
+    "boxplot.capprops.linestyle": _validate_linestyle,
+
+    "boxplot.medianprops.color":     validate_color,
+    "boxplot.medianprops.linewidth": validate_float,
+    "boxplot.medianprops.linestyle": _validate_linestyle,
+
+    "boxplot.meanprops.color":           validate_color,
+    "boxplot.meanprops.marker":          _validate_marker,
+    "boxplot.meanprops.markerfacecolor": validate_color,
+    "boxplot.meanprops.markeredgecolor": validate_color,
+    "boxplot.meanprops.markersize":      validate_float,
+    "boxplot.meanprops.linestyle":       _validate_linestyle,
+    "boxplot.meanprops.linewidth":       validate_float,
+
+    ## font props
+    "font.family":     validate_stringlist,  # used by text object
+    "font.style":      validate_string,
+    "font.variant":    validate_string,
+    "font.stretch":    validate_fontstretch,
+    "font.weight":     validate_fontweight,
+    "font.size":       validate_float,  # Base font size in points
+    "font.serif":      validate_stringlist,
+    "font.sans-serif": validate_stringlist,
+    "font.cursive":    validate_stringlist,
+    "font.fantasy":    validate_stringlist,
+    "font.monospace":  validate_stringlist,
+
+    # text props
+    "text.color":          validate_color,
+    "text.usetex":         validate_bool,
+    "text.latex.preamble": validate_string,
+    "text.hinting":        ["default", "no_autohint", "force_autohint",
+                            "no_hinting", "auto", "native", "either", "none"],
+    "text.hinting_factor": validate_int,
+    "text.kerning_factor": validate_int,
+    "text.antialiased":    validate_bool,
+    "text.parse_math":     validate_bool,
+
+    "mathtext.cal":            validate_font_properties,
+    "mathtext.rm":             validate_font_properties,
+    "mathtext.tt":             validate_font_properties,
+    "mathtext.it":             validate_font_properties,
+    "mathtext.bf":             validate_font_properties,
+    "mathtext.bfit":           validate_font_properties,
+    "mathtext.sf":             validate_font_properties,
+    "mathtext.fontset":        ["dejavusans", "dejavuserif", "cm", "stix",
+                                "stixsans", "custom"],
+    "mathtext.default":        ["rm", "cal", "bfit", "it", "tt", "sf", "bf", "default",
+                                "bb", "frak", "scr", "regular"],
+    "mathtext.fallback":       _validate_mathtext_fallback,
+
+    "image.aspect":              validate_aspect,  # equal, auto, a number
+    "image.interpolation":       validate_string,
+    "image.interpolation_stage": ["auto", "data", "rgba"],
+    "image.cmap":                _validate_cmap,  # gray, jet, etc.
+    "image.lut":                 validate_int,  # lookup table
+    "image.origin":              ["upper", "lower"],
+    "image.resample":            validate_bool,
+    # Specify whether vector graphics backends will combine all images on a
+    # set of Axes into a single composite image
+    "image.composite_image": validate_bool,
+
+    # contour props
+    "contour.negative_linestyle": _validate_linestyle,
+    "contour.corner_mask":        validate_bool,
+    "contour.linewidth":          validate_float_or_None,
+    "contour.algorithm":          ["mpl2005", "mpl2014", "serial", "threaded"],
+
+    # errorbar props
+    "errorbar.capsize": validate_float,
+
+    # axis props
+    # alignment of x/y axis title
+    "xaxis.labellocation": ["left", "center", "right"],
+    "yaxis.labellocation": ["bottom", "center", "top"],
+
+    # Axes props
+    "axes.axisbelow":        validate_axisbelow,
+    "axes.facecolor":        validate_color,  # background color
+    "axes.edgecolor":        validate_color,  # edge color
+    "axes.linewidth":        validate_float,  # edge linewidth
+
+    "axes.spines.left":      validate_bool,  # Set visibility of axes spines,
+    "axes.spines.right":     validate_bool,  # i.e., the lines around the chart
+    "axes.spines.bottom":    validate_bool,  # denoting data boundary.
+    "axes.spines.top":       validate_bool,
+
+    "axes.titlesize":     validate_fontsize,  # Axes title fontsize
+    "axes.titlelocation": ["left", "center", "right"],  # Axes title alignment
+    "axes.titleweight":   validate_fontweight,  # Axes title font weight
+    "axes.titlecolor":    validate_color_or_auto,  # Axes title font color
+    # title location, axes units, None means auto
+    "axes.titley":        validate_float_or_None,
+    # pad from Axes top decoration to title in points
+    "axes.titlepad":      validate_float,
+    "axes.grid":          validate_bool,  # display grid or not
+    "axes.grid.which":    ["minor", "both", "major"],  # which grids are drawn
+    "axes.grid.axis":     ["x", "y", "both"],  # grid type
+    "axes.labelsize":     validate_fontsize,  # fontsize of x & y labels
+    "axes.labelpad":      validate_float,  # space between label and axis
+    "axes.labelweight":   validate_fontweight,  # fontsize of x & y labels
+    "axes.labelcolor":    validate_color,  # color of axis label
+    # use scientific notation if log10 of the axis range is smaller than the
+    # first or larger than the second
+    "axes.formatter.limits": _listify_validator(validate_int, n=2),
+    # use current locale to format ticks
+    "axes.formatter.use_locale": validate_bool,
+    "axes.formatter.use_mathtext": validate_bool,
+    # minimum exponent to format in scientific notation
+    "axes.formatter.min_exponent": validate_int,
+    "axes.formatter.useoffset": validate_bool,
+    "axes.formatter.offset_threshold": validate_int,
+    "axes.unicode_minus": validate_bool,
+    # This entry can be either a cycler object or a string repr of a
+    # cycler-object, which gets eval()'ed to create the object.
+    "axes.prop_cycle": validate_cycler,
+    # If "data", axes limits are set close to the data.
+    # If "round_numbers" axes limits are set to the nearest round numbers.
+    "axes.autolimit_mode": ["data", "round_numbers"],
+    "axes.xmargin": _validate_greaterthan_minushalf,  # margin added to xaxis
+    "axes.ymargin": _validate_greaterthan_minushalf,  # margin added to yaxis
+    "axes.zmargin": _validate_greaterthan_minushalf,  # margin added to zaxis
+
+    "polaraxes.grid":    validate_bool,  # display polar grid or not
+    "axes3d.grid":       validate_bool,  # display 3d grid
+    "axes3d.automargin": validate_bool,  # automatically add margin when
+                                         # manually setting 3D axis limits
+
+    "axes3d.xaxis.panecolor":    validate_color,  # 3d background pane
+    "axes3d.yaxis.panecolor":    validate_color,  # 3d background pane
+    "axes3d.zaxis.panecolor":    validate_color,  # 3d background pane
+
+    "axes3d.mouserotationstyle": ["azel", "trackball", "sphere", "arcball"],
+    "axes3d.trackballsize": validate_float,
+    "axes3d.trackballborder": validate_float,
+
+    # scatter props
+    "scatter.marker":     _validate_marker,
+    "scatter.edgecolors": validate_string,
+
+    "date.epoch": _validate_date,
+    "date.autoformatter.year":        validate_string,
+    "date.autoformatter.month":       validate_string,
+    "date.autoformatter.day":         validate_string,
+    "date.autoformatter.hour":        validate_string,
+    "date.autoformatter.minute":      validate_string,
+    "date.autoformatter.second":      validate_string,
+    "date.autoformatter.microsecond": validate_string,
+
+    'date.converter':          ['auto', 'concise'],
+    # for auto date locator, choose interval_multiples
+    'date.interval_multiples': validate_bool,
+
+    # legend properties
+    "legend.fancybox": validate_bool,
+    "legend.loc": _validate_legend_loc,
+
+    # the number of points in the legend line
+    "legend.numpoints":      validate_int,
+    # the number of points in the legend line for scatter
+    "legend.scatterpoints":  validate_int,
+    "legend.fontsize":       validate_fontsize,
+    "legend.title_fontsize": validate_fontsize_None,
+    # color of the legend
+    "legend.labelcolor":     _validate_color_or_linecolor,
+    # the relative size of legend markers vs. original
+    "legend.markerscale":    validate_float,
+    # using dict in rcParams not yet supported, so make sure it is bool
+    "legend.shadow":         validate_bool,
+    # whether or not to draw a frame around legend
+    "legend.frameon":        validate_bool,
+    # alpha value of the legend frame
+    "legend.framealpha":     validate_float_or_None,
+
+    ## the following dimensions are in fraction of the font size
+    "legend.borderpad":      validate_float,  # units are fontsize
+    # the vertical space between the legend entries
+    "legend.labelspacing":   validate_float,
+    # the length of the legend lines
+    "legend.handlelength":   validate_float,
+    # the length of the legend lines
+    "legend.handleheight":   validate_float,
+    # the space between the legend line and legend text
+    "legend.handletextpad":  validate_float,
+    # the border between the Axes and legend edge
+    "legend.borderaxespad":  validate_float,
+    # the border between the Axes and legend edge
+    "legend.columnspacing":  validate_float,
+    "legend.facecolor":      validate_color_or_inherit,
+    "legend.edgecolor":      validate_color_or_inherit,
+
+    # tick properties
+    "xtick.top":           validate_bool,      # draw ticks on top side
+    "xtick.bottom":        validate_bool,      # draw ticks on bottom side
+    "xtick.labeltop":      validate_bool,      # draw label on top
+    "xtick.labelbottom":   validate_bool,      # draw label on bottom
+    "xtick.major.size":    validate_float,     # major xtick size in points
+    "xtick.minor.size":    validate_float,     # minor xtick size in points
+    "xtick.major.width":   validate_float,     # major xtick width in points
+    "xtick.minor.width":   validate_float,     # minor xtick width in points
+    "xtick.major.pad":     validate_float,     # distance to label in points
+    "xtick.minor.pad":     validate_float,     # distance to label in points
+    "xtick.color":         validate_color,     # color of xticks
+    "xtick.labelcolor":    validate_color_or_inherit,  # color of xtick labels
+    "xtick.minor.visible": validate_bool,      # visibility of minor xticks
+    "xtick.minor.top":     validate_bool,      # draw top minor xticks
+    "xtick.minor.bottom":  validate_bool,      # draw bottom minor xticks
+    "xtick.major.top":     validate_bool,      # draw top major xticks
+    "xtick.major.bottom":  validate_bool,      # draw bottom major xticks
+    # number of minor xticks
+    "xtick.minor.ndivs":   _validate_minor_tick_ndivs,
+    "xtick.labelsize":     validate_fontsize,  # fontsize of xtick labels
+    "xtick.direction":     ["out", "in", "inout"],  # direction of xticks
+    "xtick.alignment":     ["center", "right", "left"],
+
+    "ytick.left":          validate_bool,      # draw ticks on left side
+    "ytick.right":         validate_bool,      # draw ticks on right side
+    "ytick.labelleft":     validate_bool,      # draw tick labels on left side
+    "ytick.labelright":    validate_bool,      # draw tick labels on right side
+    "ytick.major.size":    validate_float,     # major ytick size in points
+    "ytick.minor.size":    validate_float,     # minor ytick size in points
+    "ytick.major.width":   validate_float,     # major ytick width in points
+    "ytick.minor.width":   validate_float,     # minor ytick width in points
+    "ytick.major.pad":     validate_float,     # distance to label in points
+    "ytick.minor.pad":     validate_float,     # distance to label in points
+    "ytick.color":         validate_color,     # color of yticks
+    "ytick.labelcolor":    validate_color_or_inherit,  # color of ytick labels
+    "ytick.minor.visible": validate_bool,      # visibility of minor yticks
+    "ytick.minor.left":    validate_bool,      # draw left minor yticks
+    "ytick.minor.right":   validate_bool,      # draw right minor yticks
+    "ytick.major.left":    validate_bool,      # draw left major yticks
+    "ytick.major.right":   validate_bool,      # draw right major yticks
+    # number of minor yticks
+    "ytick.minor.ndivs":   _validate_minor_tick_ndivs,
+    "ytick.labelsize":     validate_fontsize,  # fontsize of ytick labels
+    "ytick.direction":     ["out", "in", "inout"],  # direction of yticks
+    "ytick.alignment":     [
+        "center", "top", "bottom", "baseline", "center_baseline"],
+
+    "grid.color":        validate_color,  # grid color
+    "grid.linestyle":    _validate_linestyle,  # solid
+    "grid.linewidth":    validate_float,     # in points
+    "grid.alpha":        validate_float,
+
+    ## figure props
+    # figure title
+    "figure.titlesize":   validate_fontsize,
+    "figure.titleweight": validate_fontweight,
+
+    # figure labels
+    "figure.labelsize":   validate_fontsize,
+    "figure.labelweight": validate_fontweight,
+
+    # figure size in inches: width by height
+    "figure.figsize":          _listify_validator(validate_float, n=2),
+    "figure.dpi":              validate_float,
+    "figure.facecolor":        validate_color,
+    "figure.edgecolor":        validate_color,
+    "figure.frameon":          validate_bool,
+    "figure.autolayout":       validate_bool,
+    "figure.max_open_warning": validate_int,
+    "figure.raise_window":     validate_bool,
+    "macosx.window_mode":      ["system", "tab", "window"],
+
+    "figure.subplot.left":   validate_float,
+    "figure.subplot.right":  validate_float,
+    "figure.subplot.bottom": validate_float,
+    "figure.subplot.top":    validate_float,
+    "figure.subplot.wspace": validate_float,
+    "figure.subplot.hspace": validate_float,
+
+    "figure.constrained_layout.use": validate_bool,  # run constrained_layout?
+    # wspace and hspace are fraction of adjacent subplots to use for space.
+    # Much smaller than above because we don't need room for the text.
+    "figure.constrained_layout.hspace": validate_float,
+    "figure.constrained_layout.wspace": validate_float,
+    # buffer around the Axes, in inches.
+    "figure.constrained_layout.h_pad": validate_float,
+    "figure.constrained_layout.w_pad": validate_float,
+
+    ## Saving figure's properties
+    'savefig.dpi':          validate_dpi,
+    'savefig.facecolor':    validate_color_or_auto,
+    'savefig.edgecolor':    validate_color_or_auto,
+    'savefig.orientation':  ['landscape', 'portrait'],
+    "savefig.format":       validate_string,
+    "savefig.bbox":         validate_bbox,  # "tight", or "standard" (= None)
+    "savefig.pad_inches":   validate_float,
+    # default directory in savefig dialog box
+    "savefig.directory":    _validate_pathlike,
+    "savefig.transparent":  validate_bool,
+
+    "tk.window_focus": validate_bool,  # Maintain shell focus for TkAgg
+
+    # Set the papersize/type
+    "ps.papersize":       _ignorecase(
+                                ["figure", "letter", "legal", "ledger",
+                                 *[f"{ab}{i}" for ab in "ab" for i in range(11)]]),
+    "ps.useafm":          validate_bool,
+    # use ghostscript or xpdf to distill ps output
+    "ps.usedistiller":    validate_ps_distiller,
+    "ps.distiller.res":   validate_int,  # dpi
+    "ps.fonttype":        validate_fonttype,  # 3 (Type3) or 42 (Truetype)
+    "pdf.compression":    validate_int,  # 0-9 compression level; 0 to disable
+    "pdf.inheritcolor":   validate_bool,  # skip color setting commands
+    # use only the 14 PDF core fonts embedded in every PDF viewing application
+    "pdf.use14corefonts": validate_bool,
+    "pdf.fonttype":       validate_fonttype,  # 3 (Type3) or 42 (Truetype)
+
+    "pgf.texsystem": ["xelatex", "lualatex", "pdflatex"],  # latex variant used
+    "pgf.rcfonts":   validate_bool,  # use mpl's rc settings for font config
+    "pgf.preamble":  validate_string,  # custom LaTeX preamble
+
+    # write raster image data into the svg file
+    "svg.image_inline": validate_bool,
+    "svg.fonttype": ["none", "path"],  # save text as text ("none") or "paths"
+    "svg.hashsalt": validate_string_or_None,
+    "svg.id": validate_string_or_None,
+
+    # set this when you want to generate hardcopy docstring
+    "docstring.hardcopy": validate_bool,
+
+    "path.simplify":           validate_bool,
+    "path.simplify_threshold": _validate_greaterequal0_lessequal1,
+    "path.snap":               validate_bool,
+    "path.sketch":             validate_sketch,
+    "path.effects":            validate_anylist,
+    "agg.path.chunksize":      validate_int,  # 0 to disable chunking
+
+    # key-mappings (multi-character mappings should be a list/tuple)
+    "keymap.fullscreen": validate_stringlist,
+    "keymap.home":       validate_stringlist,
+    "keymap.back":       validate_stringlist,
+    "keymap.forward":    validate_stringlist,
+    "keymap.pan":        validate_stringlist,
+    "keymap.zoom":       validate_stringlist,
+    "keymap.save":       validate_stringlist,
+    "keymap.quit":       validate_stringlist,
+    "keymap.quit_all":   validate_stringlist,  # e.g.: "W", "cmd+W", "Q"
+    "keymap.grid":       validate_stringlist,
+    "keymap.grid_minor": validate_stringlist,
+    "keymap.yscale":     validate_stringlist,
+    "keymap.xscale":     validate_stringlist,
+    "keymap.help":       validate_stringlist,
+    "keymap.copy":       validate_stringlist,
+
+    # Animation settings
+    "animation.html":         ["html5", "jshtml", "none"],
+    # Limit, in MB, of size of base64 encoded animation in HTML
+    # (i.e. IPython notebook)
+    "animation.embed_limit":  validate_float,
+    "animation.writer":       validate_string,
+    "animation.codec":        validate_string,
+    "animation.bitrate":      validate_int,
+    # Controls image format when frames are written to disk
+    "animation.frame_format": ["png", "jpeg", "tiff", "raw", "rgba", "ppm",
+                               "sgi", "bmp", "pbm", "svg"],
+    # Path to ffmpeg binary. If just binary name, subprocess uses $PATH.
+    "animation.ffmpeg_path":  _validate_pathlike,
+    # Additional arguments for ffmpeg movie writer (using pipes)
+    "animation.ffmpeg_args":  validate_stringlist,
+     # Path to convert binary. If just binary name, subprocess uses $PATH.
+    "animation.convert_path": _validate_pathlike,
+     # Additional arguments for convert movie writer (using pipes)
+    "animation.convert_args": validate_stringlist,
+
+    # Classic (pre 2.0) compatibility mode
+    # This is used for things that are hard to make backward compatible
+    # with a sane rcParam alone.  This does *not* turn on classic mode
+    # altogether.  For that use `matplotlib.style.use("classic")`.
+    "_internal.classic_mode": validate_bool
+}
+_hardcoded_defaults = {  # Defaults not inferred from
+    # lib/matplotlib/mpl-data/matplotlibrc...
+    # ... because they are private:
+    "_internal.classic_mode": False,
+    # ... because they are deprecated:
+    # No current deprecations.
+    # backend is handled separately when constructing rcParamsDefault.
+}
+_validators = {k: _convert_validator_spec(k, conv)
+               for k, conv in _validators.items()}
diff --git a/lib/python3.12/site-packages/matplotlib/rcsetup.pyi b/lib/python3.12/site-packages/matplotlib/rcsetup.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..1538dac7510ee54fff13977a408480bb2b45fa18
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/rcsetup.pyi
@@ -0,0 +1,159 @@
+from cycler import Cycler
+
+from collections.abc import Callable, Iterable
+from typing import Any, Literal, TypeVar
+from matplotlib.typing import ColorType, LineStyleType, MarkEveryType
+
+interactive_bk: list[str]
+non_interactive_bk: list[str]
+all_backends: list[str]
+
+_T = TypeVar("_T")
+
+def _listify_validator(s: Callable[[Any], _T]) -> Callable[[Any], list[_T]]: ...
+
+class ValidateInStrings:
+    key: str
+    ignorecase: bool
+    valid: dict[str, str]
+    def __init__(
+        self,
+        key: str,
+        valid: Iterable[str],
+        ignorecase: bool = ...,
+        *,
+        _deprecated_since: str | None = ...
+    ) -> None: ...
+    def __call__(self, s: Any) -> str: ...
+
+def validate_any(s: Any) -> Any: ...
+def validate_anylist(s: Any) -> list[Any]: ...
+def validate_bool(b: Any) -> bool: ...
+def validate_axisbelow(s: Any) -> bool | Literal["line"]: ...
+def validate_dpi(s: Any) -> Literal["figure"] | float: ...
+def validate_string(s: Any) -> str: ...
+def validate_string_or_None(s: Any) -> str | None: ...
+def validate_stringlist(s: Any) -> list[str]: ...
+def validate_int(s: Any) -> int: ...
+def validate_int_or_None(s: Any) -> int | None: ...
+def validate_float(s: Any) -> float: ...
+def validate_float_or_None(s: Any) -> float | None: ...
+def validate_floatlist(s: Any) -> list[float]: ...
+def _validate_marker(s: Any) -> int | str: ...
+def _validate_markerlist(s: Any) -> list[int | str]: ...
+def validate_fonttype(s: Any) -> int: ...
+
+_auto_backend_sentinel: object
+
+def validate_backend(s: Any) -> str: ...
+def validate_color_or_inherit(s: Any) -> Literal["inherit"] | ColorType: ...
+def validate_color_or_auto(s: Any) -> ColorType | Literal["auto"]: ...
+def validate_color_for_prop_cycle(s: Any) -> ColorType: ...
+def validate_color(s: Any) -> ColorType: ...
+def validate_colorlist(s: Any) -> list[ColorType]: ...
+def _validate_color_or_linecolor(
+    s: Any,
+) -> ColorType | Literal["linecolor", "markerfacecolor", "markeredgecolor"] | None: ...
+def validate_aspect(s: Any) -> Literal["auto", "equal"] | float: ...
+def validate_fontsize_None(
+    s: Any,
+) -> Literal[
+    "xx-small",
+    "x-small",
+    "small",
+    "medium",
+    "large",
+    "x-large",
+    "xx-large",
+    "smaller",
+    "larger",
+] | float | None: ...
+def validate_fontsize(
+    s: Any,
+) -> Literal[
+    "xx-small",
+    "x-small",
+    "small",
+    "medium",
+    "large",
+    "x-large",
+    "xx-large",
+    "smaller",
+    "larger",
+] | float: ...
+def validate_fontsizelist(
+    s: Any,
+) -> list[
+    Literal[
+        "xx-small",
+        "x-small",
+        "small",
+        "medium",
+        "large",
+        "x-large",
+        "xx-large",
+        "smaller",
+        "larger",
+    ]
+    | float
+]: ...
+def validate_fontweight(
+    s: Any,
+) -> Literal[
+    "ultralight",
+    "light",
+    "normal",
+    "regular",
+    "book",
+    "medium",
+    "roman",
+    "semibold",
+    "demibold",
+    "demi",
+    "bold",
+    "heavy",
+    "extra bold",
+    "black",
+] | int: ...
+def validate_fontstretch(
+    s: Any,
+) -> Literal[
+    "ultra-condensed",
+    "extra-condensed",
+    "condensed",
+    "semi-condensed",
+    "normal",
+    "semi-expanded",
+    "expanded",
+    "extra-expanded",
+    "ultra-expanded",
+] | int: ...
+def validate_font_properties(s: Any) -> dict[str, Any]: ...
+def validate_whiskers(s: Any) -> list[float] | float: ...
+def validate_ps_distiller(s: Any) -> None | Literal["ghostscript", "xpdf"]: ...
+
+validate_fillstyle: ValidateInStrings
+
+def validate_fillstylelist(
+    s: Any,
+) -> list[Literal["full", "left", "right", "bottom", "top", "none"]]: ...
+def validate_markevery(s: Any) -> MarkEveryType: ...
+def _validate_linestyle(s: Any) -> LineStyleType: ...
+def validate_markeverylist(s: Any) -> list[MarkEveryType]: ...
+def validate_bbox(s: Any) -> Literal["tight", "standard"] | None: ...
+def validate_sketch(s: Any) -> None | tuple[float, float, float]: ...
+def validate_hatch(s: Any) -> str: ...
+def validate_hatchlist(s: Any) -> list[str]: ...
+def validate_dashlist(s: Any) -> list[list[float]]: ...
+
+# TODO: copy cycler overloads?
+def cycler(*args, **kwargs) -> Cycler: ...
+def validate_cycler(s: Any) -> Cycler: ...
+def validate_hist_bins(
+    s: Any,
+) -> Literal["auto", "sturges", "fd", "doane", "scott", "rice", "sqrt"] | int | list[
+    float
+]: ...
+
+# At runtime is added in __init__.py
+defaultParams: dict[str, Any]
diff --git a/lib/python3.12/site-packages/matplotlib/sankey.py b/lib/python3.12/site-packages/matplotlib/sankey.py
new file mode 100644
index 0000000000000000000000000000000000000000..637cfc849f9dc8ef3916883d5870bcbdde67e632
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/sankey.py
@@ -0,0 +1,814 @@
+"""
+Module for creating Sankey diagrams using Matplotlib.
+"""
+
+import logging
+from types import SimpleNamespace
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib.path import Path
+from matplotlib.patches import PathPatch
+from matplotlib.transforms import Affine2D
+from matplotlib import _docstring
+
+_log = logging.getLogger(__name__)
+
+__author__ = "Kevin L. Davies"
+__credits__ = ["Yannick Copin"]
+__license__ = "BSD"
+__version__ = "2011/09/16"
+
+# Angles [deg/90]
+RIGHT = 0
+UP = 1
+# LEFT = 2
+DOWN = 3
+
+
+class Sankey:
+    """
+    Sankey diagram.
+
+      Sankey diagrams are a specific type of flow diagram, in which
+      the width of the arrows is shown proportionally to the flow
+      quantity.  They are typically used to visualize energy or
+      material or cost transfers between processes.
+      `Wikipedia (6/1/2011) <https://en.wikipedia.org/wiki/Sankey_diagram>`_
+
+    """
+
+    def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25,
+                 radius=0.1, shoulder=0.03, offset=0.15, head_angle=100,
+                 margin=0.4, tolerance=1e-6, **kwargs):
+        """
+        Create a new Sankey instance.
+
+        The optional arguments listed below are applied to all subdiagrams so
+        that there is consistent alignment and formatting.
+
+        In order to draw a complex Sankey diagram, create an instance of
+        `Sankey` by calling it without any kwargs::
+
+            sankey = Sankey()
+
+        Then add simple Sankey sub-diagrams::
+
+            sankey.add() # 1
+            sankey.add() # 2
+            #...
+            sankey.add() # n
+
+        Finally, create the full diagram::
+
+            sankey.finish()
+
+        Or, instead, simply daisy-chain those calls::
+
+            Sankey().add().add...  .add().finish()
+
+        Other Parameters
+        ----------------
+        ax : `~matplotlib.axes.Axes`
+            Axes onto which the data should be plotted.  If *ax* isn't
+            provided, new Axes will be created.
+        scale : float
+            Scaling factor for the flows.  *scale* sizes the width of the paths
+            in order to maintain proper layout.  The same scale is applied to
+            all subdiagrams.  The value should be chosen such that the product
+            of the scale and the sum of the inputs is approximately 1.0 (and
+            the product of the scale and the sum of the outputs is
+            approximately -1.0).
+        unit : str
+            The physical unit associated with the flow quantities.  If *unit*
+            is None, then none of the quantities are labeled.
+        format : str or callable
+            A Python number formatting string or callable used to label the
+            flows with their quantities (i.e., a number times a unit, where the
+            unit is given). If a format string is given, the label will be
+            ``format % quantity``. If a callable is given, it will be called
+            with ``quantity`` as an argument.
+        gap : float
+            Space between paths that break in/break away to/from the top or
+            bottom.
+        radius : float
+            Inner radius of the vertical paths.
+        shoulder : float
+            Size of the shoulders of output arrows.
+        offset : float
+            Text offset (from the dip or tip of the arrow).
+        head_angle : float
+            Angle, in degrees, of the arrow heads (and negative of the angle of
+            the tails).
+        margin : float
+            Minimum space between Sankey outlines and the edge of the plot
+            area.
+        tolerance : float
+            Acceptable maximum of the magnitude of the sum of flows.  The
+            magnitude of the sum of connected flows cannot be greater than
+            *tolerance*.
+        **kwargs
+            Any additional keyword arguments will be passed to `add`, which
+            will create the first subdiagram.
+
+        See Also
+        --------
+        Sankey.add
+        Sankey.finish
+
+        Examples
+        --------
+        .. plot:: gallery/specialty_plots/sankey_basics.py
+        """
+        # Check the arguments.
+        if gap < 0:
+            raise ValueError(
+                "'gap' is negative, which is not allowed because it would "
+                "cause the paths to overlap")
+        if radius > gap:
+            raise ValueError(
+                "'radius' is greater than 'gap', which is not allowed because "
+                "it would cause the paths to overlap")
+        if head_angle < 0:
+            raise ValueError(
+                "'head_angle' is negative, which is not allowed because it "
+                "would cause inputs to look like outputs and vice versa")
+        if tolerance < 0:
+            raise ValueError(
+                "'tolerance' is negative, but it must be a magnitude")
+
+        # Create Axes if necessary.
+        if ax is None:
+            import matplotlib.pyplot as plt
+            fig = plt.figure()
+            ax = fig.add_subplot(1, 1, 1, xticks=[], yticks=[])
+
+        self.diagrams = []
+
+        # Store the inputs.
+        self.ax = ax
+        self.unit = unit
+        self.format = format
+        self.scale = scale
+        self.gap = gap
+        self.radius = radius
+        self.shoulder = shoulder
+        self.offset = offset
+        self.margin = margin
+        self.pitch = np.tan(np.pi * (1 - head_angle / 180.0) / 2.0)
+        self.tolerance = tolerance
+
+        # Initialize the vertices of tight box around the diagram(s).
+        self.extent = np.array((np.inf, -np.inf, np.inf, -np.inf))
+
+        # If there are any kwargs, create the first subdiagram.
+        if len(kwargs):
+            self.add(**kwargs)
+
+    def _arc(self, quadrant=0, cw=True, radius=1, center=(0, 0)):
+        """
+        Return the codes and vertices for a rotated, scaled, and translated
+        90 degree arc.
+
+        Other Parameters
+        ----------------
+        quadrant : {0, 1, 2, 3}, default: 0
+            Uses 0-based indexing (0, 1, 2, or 3).
+        cw : bool, default: True
+            If True, the arc vertices are produced clockwise; counter-clockwise
+            otherwise.
+        radius : float, default: 1
+            The radius of the arc.
+        center : (float, float), default: (0, 0)
+            (x, y) tuple of the arc's center.
+        """
+        # Note:  It would be possible to use matplotlib's transforms to rotate,
+        # scale, and translate the arc, but since the angles are discrete,
+        # it's just as easy and maybe more efficient to do it here.
+        ARC_CODES = [Path.LINETO,
+                     Path.CURVE4,
+                     Path.CURVE4,
+                     Path.CURVE4,
+                     Path.CURVE4,
+                     Path.CURVE4,
+                     Path.CURVE4]
+        # Vertices of a cubic Bezier curve approximating a 90 deg arc
+        # These can be determined by Path.arc(0, 90).
+        ARC_VERTICES = np.array([[1.00000000e+00, 0.00000000e+00],
+                                 [1.00000000e+00, 2.65114773e-01],
+                                 [8.94571235e-01, 5.19642327e-01],
+                                 [7.07106781e-01, 7.07106781e-01],
+                                 [5.19642327e-01, 8.94571235e-01],
+                                 [2.65114773e-01, 1.00000000e+00],
+                                 # Insignificant
+                                 # [6.12303177e-17, 1.00000000e+00]])
+                                 [0.00000000e+00, 1.00000000e+00]])
+        if quadrant in (0, 2):
+            if cw:
+                vertices = ARC_VERTICES
+            else:
+                vertices = ARC_VERTICES[:, ::-1]  # Swap x and y.
+        else:  # 1, 3
+            # Negate x.
+            if cw:
+                # Swap x and y.
+                vertices = np.column_stack((-ARC_VERTICES[:, 1],
+                                             ARC_VERTICES[:, 0]))
+            else:
+                vertices = np.column_stack((-ARC_VERTICES[:, 0],
+                                             ARC_VERTICES[:, 1]))
+        if quadrant > 1:
+            radius = -radius  # Rotate 180 deg.
+        return list(zip(ARC_CODES, radius * vertices +
+                        np.tile(center, (ARC_VERTICES.shape[0], 1))))
+
+    def _add_input(self, path, angle, flow, length):
+        """
+        Add an input to a path and return its tip and label locations.
+        """
+        if angle is None:
+            return [0, 0], [0, 0]
+        else:
+            x, y = path[-1][1]  # Use the last point as a reference.
+            dipdepth = (flow / 2) * self.pitch
+            if angle == RIGHT:
+                x -= length
+                dip = [x + dipdepth, y + flow / 2.0]
+                path.extend([(Path.LINETO, [x, y]),
+                             (Path.LINETO, dip),
+                             (Path.LINETO, [x, y + flow]),
+                             (Path.LINETO, [x + self.gap, y + flow])])
+                label_location = [dip[0] - self.offset, dip[1]]
+            else:  # Vertical
+                x -= self.gap
+                if angle == UP:
+                    sign = 1
+                else:
+                    sign = -1
+
+                dip = [x - flow / 2, y - sign * (length - dipdepth)]
+                if angle == DOWN:
+                    quadrant = 2
+                else:
+                    quadrant = 1
+
+                # Inner arc isn't needed if inner radius is zero
+                if self.radius:
+                    path.extend(self._arc(quadrant=quadrant,
+                                          cw=angle == UP,
+                                          radius=self.radius,
+                                          center=(x + self.radius,
+                                                  y - sign * self.radius)))
+                else:
+                    path.append((Path.LINETO, [x, y]))
+                path.extend([(Path.LINETO, [x, y - sign * length]),
+                             (Path.LINETO, dip),
+                             (Path.LINETO, [x - flow, y - sign * length])])
+                path.extend(self._arc(quadrant=quadrant,
+                                      cw=angle == DOWN,
+                                      radius=flow + self.radius,
+                                      center=(x + self.radius,
+                                              y - sign * self.radius)))
+                path.append((Path.LINETO, [x - flow, y + sign * flow]))
+                label_location = [dip[0], dip[1] - sign * self.offset]
+
+            return dip, label_location
+
+    def _add_output(self, path, angle, flow, length):
+        """
+        Append an output to a path and return its tip and label locations.
+
+        .. note:: *flow* is negative for an output.
+        """
+        if angle is None:
+            return [0, 0], [0, 0]
+        else:
+            x, y = path[-1][1]  # Use the last point as a reference.
+            tipheight = (self.shoulder - flow / 2) * self.pitch
+            if angle == RIGHT:
+                x += length
+                tip = [x + tipheight, y + flow / 2.0]
+                path.extend([(Path.LINETO, [x, y]),
+                             (Path.LINETO, [x, y + self.shoulder]),
+                             (Path.LINETO, tip),
+                             (Path.LINETO, [x, y - self.shoulder + flow]),
+                             (Path.LINETO, [x, y + flow]),
+                             (Path.LINETO, [x - self.gap, y + flow])])
+                label_location = [tip[0] + self.offset, tip[1]]
+            else:  # Vertical
+                x += self.gap
+                if angle == UP:
+                    sign, quadrant = 1, 3
+                else:
+                    sign, quadrant = -1, 0
+
+                tip = [x - flow / 2.0, y + sign * (length + tipheight)]
+                # Inner arc isn't needed if inner radius is zero
+                if self.radius:
+                    path.extend(self._arc(quadrant=quadrant,
+                                          cw=angle == UP,
+                                          radius=self.radius,
+                                          center=(x - self.radius,
+                                                  y + sign * self.radius)))
+                else:
+                    path.append((Path.LINETO, [x, y]))
+                path.extend([(Path.LINETO, [x, y + sign * length]),
+                             (Path.LINETO, [x - self.shoulder,
+                                            y + sign * length]),
+                             (Path.LINETO, tip),
+                             (Path.LINETO, [x + self.shoulder - flow,
+                                            y + sign * length]),
+                             (Path.LINETO, [x - flow, y + sign * length])])
+                path.extend(self._arc(quadrant=quadrant,
+                                      cw=angle == DOWN,
+                                      radius=self.radius - flow,
+                                      center=(x - self.radius,
+                                              y + sign * self.radius)))
+                path.append((Path.LINETO, [x - flow, y + sign * flow]))
+                label_location = [tip[0], tip[1] + sign * self.offset]
+            return tip, label_location
+
+    def _revert(self, path, first_action=Path.LINETO):
+        """
+        A path is not simply reversible by path[::-1] since the code
+        specifies an action to take from the **previous** point.
+        """
+        reverse_path = []
+        next_code = first_action
+        for code, position in path[::-1]:
+            reverse_path.append((next_code, position))
+            next_code = code
+        return reverse_path
+        # This might be more efficient, but it fails because 'tuple' object
+        # doesn't support item assignment:
+        # path[1] = path[1][-1:0:-1]
+        # path[1][0] = first_action
+        # path[2] = path[2][::-1]
+        # return path
+
+    @_docstring.interpd
+    def add(self, patchlabel='', flows=None, orientations=None, labels='',
+            trunklength=1.0, pathlengths=0.25, prior=None, connect=(0, 0),
+            rotation=0, **kwargs):
+        """
+        Add a simple Sankey diagram with flows at the same hierarchical level.
+
+        Parameters
+        ----------
+        patchlabel : str
+            Label to be placed at the center of the diagram.
+            Note that *label* (not *patchlabel*) can be passed as keyword
+            argument to create an entry in the legend.
+
+        flows : list of float
+            Array of flow values.  By convention, inputs are positive and
+            outputs are negative.
+
+            Flows are placed along the top of the diagram from the inside out
+            in order of their index within *flows*.  They are placed along the
+            sides of the diagram from the top down and along the bottom from
+            the outside in.
+
+            If the sum of the inputs and outputs is
+            nonzero, the discrepancy will appear as a cubic Bézier curve along
+            the top and bottom edges of the trunk.
+
+        orientations : list of {-1, 0, 1}
+            List of orientations of the flows (or a single orientation to be
+            used for all flows).  Valid values are 0 (inputs from
+            the left, outputs to the right), 1 (from and to the top) or -1
+            (from and to the bottom).
+
+        labels : list of (str or None)
+            List of labels for the flows (or a single label to be used for all
+            flows).  Each label may be *None* (no label), or a labeling string.
+            If an entry is a (possibly empty) string, then the quantity for the
+            corresponding flow will be shown below the string.  However, if
+            the *unit* of the main diagram is None, then quantities are never
+            shown, regardless of the value of this argument.
+
+        trunklength : float
+            Length between the bases of the input and output groups (in
+            data-space units).
+
+        pathlengths : list of float
+            List of lengths of the vertical arrows before break-in or after
+            break-away.  If a single value is given, then it will be applied to
+            the first (inside) paths on the top and bottom, and the length of
+            all other arrows will be justified accordingly.  The *pathlengths*
+            are not applied to the horizontal inputs and outputs.
+
+        prior : int
+            Index of the prior diagram to which this diagram should be
+            connected.
+
+        connect : (int, int)
+            A (prior, this) tuple indexing the flow of the prior diagram and
+            the flow of this diagram which should be connected.  If this is the
+            first diagram or *prior* is *None*, *connect* will be ignored.
+
+        rotation : float
+            Angle of rotation of the diagram in degrees.  The interpretation of
+            the *orientations* argument will be rotated accordingly (e.g., if
+            *rotation* == 90, an *orientations* entry of 1 means to/from the
+            left).  *rotation* is ignored if this diagram is connected to an
+            existing one (using *prior* and *connect*).
+
+        Returns
+        -------
+        Sankey
+            The current `.Sankey` instance.
+
+        Other Parameters
+        ----------------
+        **kwargs
+           Additional keyword arguments set `matplotlib.patches.PathPatch`
+           properties, listed below.  For example, one may want to use
+           ``fill=False`` or ``label="A legend entry"``.
+
+        %(Patch:kwdoc)s
+
+        See Also
+        --------
+        Sankey.finish
+        """
+        # Check and preprocess the arguments.
+        flows = np.array([1.0, -1.0]) if flows is None else np.array(flows)
+        n = flows.shape[0]  # Number of flows
+        if rotation is None:
+            rotation = 0
+        else:
+            # In the code below, angles are expressed in deg/90.
+            rotation /= 90.0
+        if orientations is None:
+            orientations = 0
+        try:
+            orientations = np.broadcast_to(orientations, n)
+        except ValueError:
+            raise ValueError(
+                f"The shapes of 'flows' {np.shape(flows)} and 'orientations' "
+                f"{np.shape(orientations)} are incompatible"
+            ) from None
+        try:
+            labels = np.broadcast_to(labels, n)
+        except ValueError:
+            raise ValueError(
+                f"The shapes of 'flows' {np.shape(flows)} and 'labels' "
+                f"{np.shape(labels)} are incompatible"
+            ) from None
+        if trunklength < 0:
+            raise ValueError(
+                "'trunklength' is negative, which is not allowed because it "
+                "would cause poor layout")
+        if abs(np.sum(flows)) > self.tolerance:
+            _log.info("The sum of the flows is nonzero (%f; patchlabel=%r); "
+                      "is the system not at steady state?",
+                      np.sum(flows), patchlabel)
+        scaled_flows = self.scale * flows
+        gain = sum(max(flow, 0) for flow in scaled_flows)
+        loss = sum(min(flow, 0) for flow in scaled_flows)
+        if prior is not None:
+            if prior < 0:
+                raise ValueError("The index of the prior diagram is negative")
+            if min(connect) < 0:
+                raise ValueError(
+                    "At least one of the connection indices is negative")
+            if prior >= len(self.diagrams):
+                raise ValueError(
+                    f"The index of the prior diagram is {prior}, but there "
+                    f"are only {len(self.diagrams)} other diagrams")
+            if connect[0] >= len(self.diagrams[prior].flows):
+                raise ValueError(
+                    "The connection index to the source diagram is {}, but "
+                    "that diagram has only {} flows".format(
+                        connect[0], len(self.diagrams[prior].flows)))
+            if connect[1] >= n:
+                raise ValueError(
+                    f"The connection index to this diagram is {connect[1]}, "
+                    f"but this diagram has only {n} flows")
+            if self.diagrams[prior].angles[connect[0]] is None:
+                raise ValueError(
+                    f"The connection cannot be made, which may occur if the "
+                    f"magnitude of flow {connect[0]} of diagram {prior} is "
+                    f"less than the specified tolerance")
+            flow_error = (self.diagrams[prior].flows[connect[0]] +
+                          flows[connect[1]])
+            if abs(flow_error) >= self.tolerance:
+                raise ValueError(
+                    f"The scaled sum of the connected flows is {flow_error}, "
+                    f"which is not within the tolerance ({self.tolerance})")
+
+        # Determine if the flows are inputs.
+        are_inputs = [None] * n
+        for i, flow in enumerate(flows):
+            if flow >= self.tolerance:
+                are_inputs[i] = True
+            elif flow <= -self.tolerance:
+                are_inputs[i] = False
+            else:
+                _log.info(
+                    "The magnitude of flow %d (%f) is below the tolerance "
+                    "(%f).\nIt will not be shown, and it cannot be used in a "
+                    "connection.", i, flow, self.tolerance)
+
+        # Determine the angles of the arrows (before rotation).
+        angles = [None] * n
+        for i, (orient, is_input) in enumerate(zip(orientations, are_inputs)):
+            if orient == 1:
+                if is_input:
+                    angles[i] = DOWN
+                elif is_input is False:
+                    # Be specific since is_input can be None.
+                    angles[i] = UP
+            elif orient == 0:
+                if is_input is not None:
+                    angles[i] = RIGHT
+            else:
+                if orient != -1:
+                    raise ValueError(
+                        f"The value of orientations[{i}] is {orient}, "
+                        f"but it must be -1, 0, or 1")
+                if is_input:
+                    angles[i] = UP
+                elif is_input is False:
+                    angles[i] = DOWN
+
+        # Justify the lengths of the paths.
+        if np.iterable(pathlengths):
+            if len(pathlengths) != n:
+                raise ValueError(
+                    f"The lengths of 'flows' ({n}) and 'pathlengths' "
+                    f"({len(pathlengths)}) are incompatible")
+        else:  # Make pathlengths into a list.
+            urlength = pathlengths
+            ullength = pathlengths
+            lrlength = pathlengths
+            lllength = pathlengths
+            d = dict(RIGHT=pathlengths)
+            pathlengths = [d.get(angle, 0) for angle in angles]
+            # Determine the lengths of the top-side arrows
+            # from the middle outwards.
+            for i, (angle, is_input, flow) in enumerate(zip(angles, are_inputs,
+                                                            scaled_flows)):
+                if angle == DOWN and is_input:
+                    pathlengths[i] = ullength
+                    ullength += flow
+                elif angle == UP and is_input is False:
+                    pathlengths[i] = urlength
+                    urlength -= flow  # Flow is negative for outputs.
+            # Determine the lengths of the bottom-side arrows
+            # from the middle outwards.
+            for i, (angle, is_input, flow) in enumerate(reversed(list(zip(
+                  angles, are_inputs, scaled_flows)))):
+                if angle == UP and is_input:
+                    pathlengths[n - i - 1] = lllength
+                    lllength += flow
+                elif angle == DOWN and is_input is False:
+                    pathlengths[n - i - 1] = lrlength
+                    lrlength -= flow
+            # Determine the lengths of the left-side arrows
+            # from the bottom upwards.
+            has_left_input = False
+            for i, (angle, is_input, spec) in enumerate(reversed(list(zip(
+                  angles, are_inputs, zip(scaled_flows, pathlengths))))):
+                if angle == RIGHT:
+                    if is_input:
+                        if has_left_input:
+                            pathlengths[n - i - 1] = 0
+                        else:
+                            has_left_input = True
+            # Determine the lengths of the right-side arrows
+            # from the top downwards.
+            has_right_output = False
+            for i, (angle, is_input, spec) in enumerate(zip(
+                  angles, are_inputs, list(zip(scaled_flows, pathlengths)))):
+                if angle == RIGHT:
+                    if is_input is False:
+                        if has_right_output:
+                            pathlengths[i] = 0
+                        else:
+                            has_right_output = True
+
+        # Begin the subpaths, and smooth the transition if the sum of the flows
+        # is nonzero.
+        urpath = [(Path.MOVETO, [(self.gap - trunklength / 2.0),  # Upper right
+                                 gain / 2.0]),
+                  (Path.LINETO, [(self.gap - trunklength / 2.0) / 2.0,
+                                 gain / 2.0]),
+                  (Path.CURVE4, [(self.gap - trunklength / 2.0) / 8.0,
+                                 gain / 2.0]),
+                  (Path.CURVE4, [(trunklength / 2.0 - self.gap) / 8.0,
+                                 -loss / 2.0]),
+                  (Path.LINETO, [(trunklength / 2.0 - self.gap) / 2.0,
+                                 -loss / 2.0]),
+                  (Path.LINETO, [(trunklength / 2.0 - self.gap),
+                                 -loss / 2.0])]
+        llpath = [(Path.LINETO, [(trunklength / 2.0 - self.gap),  # Lower left
+                                 loss / 2.0]),
+                  (Path.LINETO, [(trunklength / 2.0 - self.gap) / 2.0,
+                                 loss / 2.0]),
+                  (Path.CURVE4, [(trunklength / 2.0 - self.gap) / 8.0,
+                                 loss / 2.0]),
+                  (Path.CURVE4, [(self.gap - trunklength / 2.0) / 8.0,
+                                 -gain / 2.0]),
+                  (Path.LINETO, [(self.gap - trunklength / 2.0) / 2.0,
+                                 -gain / 2.0]),
+                  (Path.LINETO, [(self.gap - trunklength / 2.0),
+                                 -gain / 2.0])]
+        lrpath = [(Path.LINETO, [(trunklength / 2.0 - self.gap),  # Lower right
+                                 loss / 2.0])]
+        ulpath = [(Path.LINETO, [self.gap - trunklength / 2.0,  # Upper left
+                                 gain / 2.0])]
+
+        # Add the subpaths and assign the locations of the tips and labels.
+        tips = np.zeros((n, 2))
+        label_locations = np.zeros((n, 2))
+        # Add the top-side inputs and outputs from the middle outwards.
+        for i, (angle, is_input, spec) in enumerate(zip(
+              angles, are_inputs, list(zip(scaled_flows, pathlengths)))):
+            if angle == DOWN and is_input:
+                tips[i, :], label_locations[i, :] = self._add_input(
+                    ulpath, angle, *spec)
+            elif angle == UP and is_input is False:
+                tips[i, :], label_locations[i, :] = self._add_output(
+                    urpath, angle, *spec)
+        # Add the bottom-side inputs and outputs from the middle outwards.
+        for i, (angle, is_input, spec) in enumerate(reversed(list(zip(
+              angles, are_inputs, list(zip(scaled_flows, pathlengths)))))):
+            if angle == UP and is_input:
+                tip, label_location = self._add_input(llpath, angle, *spec)
+                tips[n - i - 1, :] = tip
+                label_locations[n - i - 1, :] = label_location
+            elif angle == DOWN and is_input is False:
+                tip, label_location = self._add_output(lrpath, angle, *spec)
+                tips[n - i - 1, :] = tip
+                label_locations[n - i - 1, :] = label_location
+        # Add the left-side inputs from the bottom upwards.
+        has_left_input = False
+        for i, (angle, is_input, spec) in enumerate(reversed(list(zip(
+              angles, are_inputs, list(zip(scaled_flows, pathlengths)))))):
+            if angle == RIGHT and is_input:
+                if not has_left_input:
+                    # Make sure the lower path extends
+                    # at least as far as the upper one.
+                    if llpath[-1][1][0] > ulpath[-1][1][0]:
+                        llpath.append((Path.LINETO, [ulpath[-1][1][0],
+                                                     llpath[-1][1][1]]))
+                    has_left_input = True
+                tip, label_location = self._add_input(llpath, angle, *spec)
+                tips[n - i - 1, :] = tip
+                label_locations[n - i - 1, :] = label_location
+        # Add the right-side outputs from the top downwards.
+        has_right_output = False
+        for i, (angle, is_input, spec) in enumerate(zip(
+              angles, are_inputs, list(zip(scaled_flows, pathlengths)))):
+            if angle == RIGHT and is_input is False:
+                if not has_right_output:
+                    # Make sure the upper path extends
+                    # at least as far as the lower one.
+                    if urpath[-1][1][0] < lrpath[-1][1][0]:
+                        urpath.append((Path.LINETO, [lrpath[-1][1][0],
+                                                     urpath[-1][1][1]]))
+                    has_right_output = True
+                tips[i, :], label_locations[i, :] = self._add_output(
+                    urpath, angle, *spec)
+        # Trim any hanging vertices.
+        if not has_left_input:
+            ulpath.pop()
+            llpath.pop()
+        if not has_right_output:
+            lrpath.pop()
+            urpath.pop()
+
+        # Concatenate the subpaths in the correct order (clockwise from top).
+        path = (urpath + self._revert(lrpath) + llpath + self._revert(ulpath) +
+                [(Path.CLOSEPOLY, urpath[0][1])])
+
+        # Create a patch with the Sankey outline.
+        codes, vertices = zip(*path)
+        vertices = np.array(vertices)
+
+        def _get_angle(a, r):
+            if a is None:
+                return None
+            else:
+                return a + r
+
+        if prior is None:
+            if rotation != 0:  # By default, none of this is needed.
+                angles = [_get_angle(angle, rotation) for angle in angles]
+                rotate = Affine2D().rotate_deg(rotation * 90).transform_affine
+                tips = rotate(tips)
+                label_locations = rotate(label_locations)
+                vertices = rotate(vertices)
+            text = self.ax.text(0, 0, s=patchlabel, ha='center', va='center')
+        else:
+            rotation = (self.diagrams[prior].angles[connect[0]] -
+                        angles[connect[1]])
+            angles = [_get_angle(angle, rotation) for angle in angles]
+            rotate = Affine2D().rotate_deg(rotation * 90).transform_affine
+            tips = rotate(tips)
+            offset = self.diagrams[prior].tips[connect[0]] - tips[connect[1]]
+            translate = Affine2D().translate(*offset).transform_affine
+            tips = translate(tips)
+            label_locations = translate(rotate(label_locations))
+            vertices = translate(rotate(vertices))
+            kwds = dict(s=patchlabel, ha='center', va='center')
+            text = self.ax.text(*offset, **kwds)
+        if mpl.rcParams['_internal.classic_mode']:
+            fc = kwargs.pop('fc', kwargs.pop('facecolor', '#bfd1d4'))
+            lw = kwargs.pop('lw', kwargs.pop('linewidth', 0.5))
+        else:
+            fc = kwargs.pop('fc', kwargs.pop('facecolor', None))
+            lw = kwargs.pop('lw', kwargs.pop('linewidth', None))
+        if fc is None:
+            fc = self.ax._get_patches_for_fill.get_next_color()
+        patch = PathPatch(Path(vertices, codes), fc=fc, lw=lw, **kwargs)
+        self.ax.add_patch(patch)
+
+        # Add the path labels.
+        texts = []
+        for number, angle, label, location in zip(flows, angles, labels,
+                                                  label_locations):
+            if label is None or angle is None:
+                label = ''
+            elif self.unit is not None:
+                if isinstance(self.format, str):
+                    quantity = self.format % abs(number) + self.unit
+                elif callable(self.format):
+                    quantity = self.format(number)
+                else:
+                    raise TypeError(
+                        'format must be callable or a format string')
+                if label != '':
+                    label += "\n"
+                label += quantity
+            texts.append(self.ax.text(x=location[0], y=location[1],
+                                      s=label,
+                                      ha='center', va='center'))
+        # Text objects are placed even they are empty (as long as the magnitude
+        # of the corresponding flow is larger than the tolerance) in case the
+        # user wants to provide labels later.
+
+        # Expand the size of the diagram if necessary.
+        self.extent = (min(np.min(vertices[:, 0]),
+                           np.min(label_locations[:, 0]),
+                           self.extent[0]),
+                       max(np.max(vertices[:, 0]),
+                           np.max(label_locations[:, 0]),
+                           self.extent[1]),
+                       min(np.min(vertices[:, 1]),
+                           np.min(label_locations[:, 1]),
+                           self.extent[2]),
+                       max(np.max(vertices[:, 1]),
+                           np.max(label_locations[:, 1]),
+                           self.extent[3]))
+        # Include both vertices _and_ label locations in the extents; there are
+        # where either could determine the margins (e.g., arrow shoulders).
+
+        # Add this diagram as a subdiagram.
+        self.diagrams.append(
+            SimpleNamespace(patch=patch, flows=flows, angles=angles, tips=tips,
+                            text=text, texts=texts))
+
+        # Allow a daisy-chained call structure (see docstring for the class).
+        return self
+
+    def finish(self):
+        """
+        Adjust the Axes and return a list of information about the Sankey
+        subdiagram(s).
+
+        Returns a list of subdiagrams with the following fields:
+
+        ========  =============================================================
+        Field     Description
+        ========  =============================================================
+        *patch*   Sankey outline (a `~matplotlib.patches.PathPatch`).
+        *flows*   Flow values (positive for input, negative for output).
+        *angles*  List of angles of the arrows [deg/90].
+                  For example, if the diagram has not been rotated,
+                  an input to the top side has an angle of 3 (DOWN),
+                  and an output from the top side has an angle of 1 (UP).
+                  If a flow has been skipped (because its magnitude is less
+                  than *tolerance*), then its angle will be *None*.
+        *tips*    (N, 2)-array of the (x, y) positions of the tips (or "dips")
+                  of the flow paths.
+                  If the magnitude of a flow is less the *tolerance* of this
+                  `Sankey` instance, the flow is skipped and its tip will be at
+                  the center of the diagram.
+        *text*    `.Text` instance for the diagram label.
+        *texts*   List of `.Text` instances for the flow labels.
+        ========  =============================================================
+
+        See Also
+        --------
+        Sankey.add
+        """
+        self.ax.axis([self.extent[0] - self.margin,
+                      self.extent[1] + self.margin,
+                      self.extent[2] - self.margin,
+                      self.extent[3] + self.margin])
+        self.ax.set_aspect('equal', adjustable='datalim')
+        return self.diagrams
diff --git a/lib/python3.12/site-packages/matplotlib/spines.pyi b/lib/python3.12/site-packages/matplotlib/spines.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..ff2a1a40bf947005692ccaf2b95977e57a1747b6
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/spines.pyi
@@ -0,0 +1,83 @@
+from collections.abc import Callable, Iterator, MutableMapping
+from typing import Literal, TypeVar, overload
+
+import matplotlib.patches as mpatches
+from matplotlib.axes import Axes
+from matplotlib.axis import Axis
+from matplotlib.path import Path
+from matplotlib.transforms import Transform
+from matplotlib.typing import ColorType
+
+class Spine(mpatches.Patch):
+    axes: Axes
+    spine_type: str
+    axis: Axis | None
+    def __init__(self, axes: Axes, spine_type: str, path: Path, **kwargs) -> None: ...
+    def set_patch_arc(
+        self, center: tuple[float, float], radius: float, theta1: float, theta2: float
+    ) -> None: ...
+    def set_patch_circle(self, center: tuple[float, float], radius: float) -> None: ...
+    def set_patch_line(self) -> None: ...
+    def get_patch_transform(self) -> Transform: ...
+    def get_path(self) -> Path: ...
+    def register_axis(self, axis: Axis) -> None: ...
+    def clear(self) -> None: ...
+    def set_position(
+        self,
+        position: Literal["center", "zero"]
+        | tuple[Literal["outward", "axes", "data"], float],
+    ) -> None: ...
+    def get_position(
+        self,
+    ) -> Literal["center", "zero"] | tuple[
+        Literal["outward", "axes", "data"], float
+    ]: ...
+    def get_spine_transform(self) -> Transform: ...
+    def set_bounds(self, low: float | None = ..., high: float | None = ...) -> None: ...
+    def get_bounds(self) -> tuple[float, float]: ...
+
+    _T = TypeVar("_T", bound=Spine)
+    @classmethod
+    def linear_spine(
+        cls: type[_T],
+        axes: Axes,
+        spine_type: Literal["left", "right", "bottom", "top"],
+        **kwargs
+    ) -> _T: ...
+    @classmethod
+    def arc_spine(
+        cls: type[_T],
+        axes: Axes,
+        spine_type: Literal["left", "right", "bottom", "top"],
+        center: tuple[float, float],
+        radius: float,
+        theta1: float,
+        theta2: float,
+        **kwargs
+    ) -> _T: ...
+    @classmethod
+    def circular_spine(
+        cls: type[_T], axes: Axes, center: tuple[float, float], radius: float, **kwargs
+    ) -> _T: ...
+    def set_color(self, c: ColorType | None) -> None: ...
+
+class SpinesProxy:
+    def __init__(self, spine_dict: dict[str, Spine]) -> None: ...
+    def __getattr__(self, name: str) -> Callable[..., None]: ...
+    def __dir__(self) -> list[str]: ...
+
+class Spines(MutableMapping[str, Spine]):
+    def __init__(self, **kwargs: Spine) -> None: ...
+    @classmethod
+    def from_dict(cls, d: dict[str, Spine]) -> Spines: ...
+    def __getattr__(self, name: str) -> Spine: ...
+    @overload
+    def __getitem__(self, key: str) -> Spine: ...
+    @overload
+    def __getitem__(self, key: list[str]) -> SpinesProxy: ...
+    @overload
+    def __getitem__(self, key: slice) -> SpinesProxy: ...
+    def __setitem__(self, key: str, value: Spine) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
diff --git a/lib/python3.12/site-packages/matplotlib/stackplot.pyi b/lib/python3.12/site-packages/matplotlib/stackplot.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..9509f858a4bfbf6fd54fa1111077341b31ec03b2
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/stackplot.pyi
@@ -0,0 +1,20 @@
+from matplotlib.axes import Axes
+from matplotlib.collections import PolyCollection
+
+from collections.abc import Iterable
+from typing import Literal
+from numpy.typing import ArrayLike
+from matplotlib.typing import ColorType
+
+def stackplot(
+    axes: Axes,
+    x: ArrayLike,
+    *args: ArrayLike,
+    labels: Iterable[str] = ...,
+    colors: Iterable[ColorType] | None = ...,
+    hatch: Iterable[str] | str | None = ...,
+    baseline: Literal["zero", "sym", "wiggle", "weighted_wiggle"] = ...,
+    **kwargs
+) -> list[PolyCollection]: ...
+
+__all__ = ['stackplot']
diff --git a/lib/python3.12/site-packages/matplotlib/streamplot.pyi b/lib/python3.12/site-packages/matplotlib/streamplot.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..be745802044907a32084934576269eaf228e07e4
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/streamplot.pyi
@@ -0,0 +1,84 @@
+from matplotlib.axes import Axes
+from matplotlib.colors import Normalize, Colormap
+from matplotlib.collections import LineCollection, PatchCollection
+from matplotlib.patches import ArrowStyle
+from matplotlib.transforms import Transform
+
+from typing import Literal
+from numpy.typing import ArrayLike
+from .typing import ColorType
+
+def streamplot(
+    axes: Axes,
+    x: ArrayLike,
+    y: ArrayLike,
+    u: ArrayLike,
+    v: ArrayLike,
+    density: float | tuple[float, float] = ...,
+    linewidth: float | ArrayLike | None = ...,
+    color: ColorType | ArrayLike | None = ...,
+    cmap: str | Colormap | None = ...,
+    norm: str | Normalize | None = ...,
+    arrowsize: float = ...,
+    arrowstyle: str | ArrowStyle = ...,
+    minlength: float = ...,
+    transform: Transform | None = ...,
+    zorder: float | None = ...,
+    start_points: ArrayLike | None = ...,
+    maxlength: float = ...,
+    integration_direction: Literal["forward", "backward", "both"] = ...,
+    broken_streamlines: bool = ...,
+) -> StreamplotSet: ...
+
+class StreamplotSet:
+    lines: LineCollection
+    arrows: PatchCollection
+    def __init__(self, lines: LineCollection, arrows: PatchCollection) -> None: ...
+
+class DomainMap:
+    grid: Grid
+    mask: StreamMask
+    x_grid2mask: float
+    y_grid2mask: float
+    x_mask2grid: float
+    y_mask2grid: float
+    x_data2grid: float
+    y_data2grid: float
+    def __init__(self, grid: Grid, mask: StreamMask) -> None: ...
+    def grid2mask(self, xi: float, yi: float) -> tuple[int, int]: ...
+    def mask2grid(self, xm: float, ym: float) -> tuple[float, float]: ...
+    def data2grid(self, xd: float, yd: float) -> tuple[float, float]: ...
+    def grid2data(self, xg: float, yg: float) -> tuple[float, float]: ...
+    def start_trajectory(
+        self, xg: float, yg: float, broken_streamlines: bool = ...
+    ) -> None: ...
+    def reset_start_point(self, xg: float, yg: float) -> None: ...
+    def update_trajectory(self, xg, yg, broken_streamlines: bool = ...) -> None: ...
+    def undo_trajectory(self) -> None: ...
+
+class Grid:
+    nx: int
+    ny: int
+    dx: float
+    dy: float
+    x_origin: float
+    y_origin: float
+    width: float
+    height: float
+    def __init__(self, x: ArrayLike, y: ArrayLike) -> None: ...
+    @property
+    def shape(self) -> tuple[int, int]: ...
+    def within_grid(self, xi: float, yi: float) -> bool: ...
+
+class StreamMask:
+    nx: int
+    ny: int
+    shape: tuple[int, int]
+    def __init__(self, density: float | tuple[float, float]) -> None: ...
+    def __getitem__(self, args): ...
+
+class InvalidIndexError(Exception): ...
+class TerminateTrajectory(Exception): ...
+class OutOfBounds(IndexError): ...
+
+__all__ = ['streamplot']
diff --git a/lib/python3.12/site-packages/matplotlib/table.pyi b/lib/python3.12/site-packages/matplotlib/table.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..07d2427f66dc184efaf46af83e6733d157bc089b
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/table.pyi
@@ -0,0 +1,87 @@
+from .artist import Artist
+from .axes import Axes
+from .backend_bases import RendererBase
+from .patches import Rectangle
+from .path import Path
+from .text import Text
+from .transforms import Bbox
+from .typing import ColorType
+
+from collections.abc import Sequence
+from typing import Any, Literal, TYPE_CHECKING
+
+from pandas import DataFrame
+
+class Cell(Rectangle):
+    PAD: float
+    def __init__(
+        self,
+        xy: tuple[float, float],
+        width: float,
+        height: float,
+        *,
+        edgecolor: ColorType = ...,
+        facecolor: ColorType = ...,
+        fill: bool = ...,
+        text: str = ...,
+        loc: Literal["left", "center", "right"] = ...,
+        fontproperties: dict[str, Any] | None = ...,
+        visible_edges: str | None = ...
+    ) -> None: ...
+    def get_text(self) -> Text: ...
+    def set_fontsize(self, size: float) -> None: ...
+    def get_fontsize(self) -> float: ...
+    def auto_set_font_size(self, renderer: RendererBase) -> float: ...
+    def get_text_bounds(
+        self, renderer: RendererBase
+    ) -> tuple[float, float, float, float]: ...
+    def get_required_width(self, renderer: RendererBase) -> float: ...
+    def set_text_props(self, **kwargs) -> None: ...
+    @property
+    def visible_edges(self) -> str: ...
+    @visible_edges.setter
+    def visible_edges(self, value: str | None) -> None: ...
+    def get_path(self) -> Path: ...
+
+CustomCell = Cell
+
+class Table(Artist):
+    codes: dict[str, int]
+    FONTSIZE: float
+    AXESPAD: float
+    def __init__(
+        self, ax: Axes, loc: str | None = ..., bbox: Bbox | None = ..., **kwargs
+    ) -> None: ...
+    def add_cell(self, row: int, col: int, *args, **kwargs) -> Cell: ...
+    def __setitem__(self, position: tuple[int, int], cell: Cell) -> None: ...
+    def __getitem__(self, position: tuple[int, int]) -> Cell: ...
+    @property
+    def edges(self) -> str | None: ...
+    @edges.setter
+    def edges(self, value: str | None) -> None: ...
+    def draw(self, renderer) -> None: ...
+    def get_children(self) -> list[Artist]: ...
+    def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...
+    def auto_set_column_width(self, col: int | Sequence[int]) -> None: ...
+    def auto_set_font_size(self, value: bool = ...) -> None: ...
+    def scale(self, xscale: float, yscale: float) -> None: ...
+    def set_fontsize(self, size: float) -> None: ...
+    def get_celld(self) -> dict[tuple[int, int], Cell]: ...
+
+def table(
+    ax: Axes,
+    cellText: Sequence[Sequence[str]] | DataFrame | None = ...,
+    cellColours: Sequence[Sequence[ColorType]] | None = ...,
+    cellLoc: Literal["left", "center", "right"] = ...,
+    colWidths: Sequence[float] | None = ...,
+    rowLabels: Sequence[str] | None = ...,
+    rowColours: Sequence[ColorType] | None = ...,
+    rowLoc: Literal["left", "center", "right"] = ...,
+    colLabels: Sequence[str] | None = ...,
+    colColours: Sequence[ColorType] | None = ...,
+    colLoc: Literal["left", "center", "right"] = ...,
+    loc: str = ...,
+    bbox: Bbox | None = ...,
+    edges: str = ...,
+    **kwargs
+) -> Table: ...
diff --git a/lib/python3.12/site-packages/matplotlib/texmanager.pyi b/lib/python3.12/site-packages/matplotlib/texmanager.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..94f0d76fa814c6015fd4acefca5b1c1732645c85
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/texmanager.pyi
@@ -0,0 +1,38 @@
+from .backend_bases import RendererBase
+
+from matplotlib.typing import ColorType
+
+import numpy as np
+
+class TexManager:
+    texcache: str
+    @classmethod
+    def get_basefile(
+        cls, tex: str, fontsize: float, dpi: float | None = ...
+    ) -> str: ...
+    @classmethod
+    def get_font_preamble(cls) -> str: ...
+    @classmethod
+    def get_custom_preamble(cls) -> str: ...
+    @classmethod
+    def make_tex(cls, tex: str, fontsize: float) -> str: ...
+    @classmethod
+    def make_dvi(cls, tex: str, fontsize: float) -> str: ...
+    @classmethod
+    def make_png(cls, tex: str, fontsize: float, dpi: float) -> str: ...
+    @classmethod
+    def get_grey(
+        cls, tex: str, fontsize: float | None = ..., dpi: float | None = ...
+    ) -> np.ndarray: ...
+    @classmethod
+    def get_rgba(
+        cls,
+        tex: str,
+        fontsize: float | None = ...,
+        dpi: float | None = ...,
+        rgb: ColorType = ...,
+    ) -> np.ndarray: ...
+    @classmethod
+    def get_text_width_height_descent(
+        cls, tex: str, fontsize, renderer: RendererBase | None = ...
+    ) -> tuple[int, int, int]: ...
diff --git a/lib/python3.12/site-packages/matplotlib/text.py b/lib/python3.12/site-packages/matplotlib/text.py
new file mode 100644
index 0000000000000000000000000000000000000000..d18fc51b070c58a079f01b550bc9d2072c7e4d80
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/text.py
@@ -0,0 +1,2035 @@
+"""
+Classes for including text in a figure.
+"""
+
+import functools
+import logging
+import math
+from numbers import Real
+import weakref
+
+import numpy as np
+
+import matplotlib as mpl
+from . import _api, artist, cbook, _docstring
+from .artist import Artist
+from .font_manager import FontProperties
+from .patches import FancyArrowPatch, FancyBboxPatch, Rectangle
+from .textpath import TextPath, TextToPath  # noqa # Logically located here
+from .transforms import (
+    Affine2D, Bbox, BboxBase, BboxTransformTo, IdentityTransform, Transform)
+
+
+_log = logging.getLogger(__name__)
+
+
+def _get_textbox(text, renderer):
+    """
+    Calculate the bounding box of the text.
+
+    The bbox position takes text rotation into account, but the width and
+    height are those of the unrotated box (unlike `.Text.get_window_extent`).
+    """
+    # TODO : This function may move into the Text class as a method. As a
+    # matter of fact, the information from the _get_textbox function
+    # should be available during the Text._get_layout() call, which is
+    # called within the _get_textbox. So, it would better to move this
+    # function as a method with some refactoring of _get_layout method.
+
+    projected_xs = []
+    projected_ys = []
+
+    theta = np.deg2rad(text.get_rotation())
+    tr = Affine2D().rotate(-theta)
+
+    _, parts, d = text._get_layout(renderer)
+
+    for t, wh, x, y in parts:
+        w, h = wh
+
+        xt1, yt1 = tr.transform((x, y))
+        yt1 -= d
+        xt2, yt2 = xt1 + w, yt1 + h
+
+        projected_xs.extend([xt1, xt2])
+        projected_ys.extend([yt1, yt2])
+
+    xt_box, yt_box = min(projected_xs), min(projected_ys)
+    w_box, h_box = max(projected_xs) - xt_box, max(projected_ys) - yt_box
+
+    x_box, y_box = Affine2D().rotate(theta).transform((xt_box, yt_box))
+
+    return x_box, y_box, w_box, h_box
+
+
+def _get_text_metrics_with_cache(renderer, text, fontprop, ismath, dpi):
+    """Call ``renderer.get_text_width_height_descent``, caching the results."""
+    # Cached based on a copy of fontprop so that later in-place mutations of
+    # the passed-in argument do not mess up the cache.
+    return _get_text_metrics_with_cache_impl(
+        weakref.ref(renderer), text, fontprop.copy(), ismath, dpi)
+
+
+@functools.lru_cache(4096)
+def _get_text_metrics_with_cache_impl(
+        renderer_ref, text, fontprop, ismath, dpi):
+    # dpi is unused, but participates in cache invalidation (via the renderer).
+    return renderer_ref().get_text_width_height_descent(text, fontprop, ismath)
+
+
+@_docstring.interpd
+@_api.define_aliases({
+    "color": ["c"],
+    "fontproperties": ["font", "font_properties"],
+    "fontfamily": ["family"],
+    "fontname": ["name"],
+    "fontsize": ["size"],
+    "fontstretch": ["stretch"],
+    "fontstyle": ["style"],
+    "fontvariant": ["variant"],
+    "fontweight": ["weight"],
+    "horizontalalignment": ["ha"],
+    "verticalalignment": ["va"],
+    "multialignment": ["ma"],
+})
+class Text(Artist):
+    """Handle storing and drawing of text in window or data coordinates."""
+
+    zorder = 3
+    _charsize_cache = dict()
+
+    def __repr__(self):
+        return f"Text({self._x}, {self._y}, {self._text!r})"
+
+    def __init__(self,
+                 x=0, y=0, text='', *,
+                 color=None,           # defaults to rc params
+                 verticalalignment='baseline',
+                 horizontalalignment='left',
+                 multialignment=None,
+                 fontproperties=None,  # defaults to FontProperties()
+                 rotation=None,
+                 linespacing=None,
+                 rotation_mode=None,
+                 usetex=None,          # defaults to rcParams['text.usetex']
+                 wrap=False,
+                 transform_rotates_text=False,
+                 parse_math=None,    # defaults to rcParams['text.parse_math']
+                 antialiased=None,  # defaults to rcParams['text.antialiased']
+                 **kwargs
+                 ):
+        """
+        Create a `.Text` instance at *x*, *y* with string *text*.
+
+        The text is aligned relative to the anchor point (*x*, *y*) according
+        to ``horizontalalignment`` (default: 'left') and ``verticalalignment``
+        (default: 'baseline'). See also
+        :doc:`/gallery/text_labels_and_annotations/text_alignment`.
+
+        While Text accepts the 'label' keyword argument, by default it is not
+        added to the handles of a legend.
+
+        Valid keyword arguments are:
+
+        %(Text:kwdoc)s
+        """
+        super().__init__()
+        self._x, self._y = x, y
+        self._text = ''
+        self._reset_visual_defaults(
+            text=text,
+            color=color,
+            fontproperties=fontproperties,
+            usetex=usetex,
+            parse_math=parse_math,
+            wrap=wrap,
+            verticalalignment=verticalalignment,
+            horizontalalignment=horizontalalignment,
+            multialignment=multialignment,
+            rotation=rotation,
+            transform_rotates_text=transform_rotates_text,
+            linespacing=linespacing,
+            rotation_mode=rotation_mode,
+            antialiased=antialiased
+        )
+        self.update(kwargs)
+
+    def _reset_visual_defaults(
+        self,
+        text='',
+        color=None,
+        fontproperties=None,
+        usetex=None,
+        parse_math=None,
+        wrap=False,
+        verticalalignment='baseline',
+        horizontalalignment='left',
+        multialignment=None,
+        rotation=None,
+        transform_rotates_text=False,
+        linespacing=None,
+        rotation_mode=None,
+        antialiased=None
+    ):
+        self.set_text(text)
+        self.set_color(mpl._val_or_rc(color, "text.color"))
+        self.set_fontproperties(fontproperties)
+        self.set_usetex(usetex)
+        self.set_parse_math(mpl._val_or_rc(parse_math, 'text.parse_math'))
+        self.set_wrap(wrap)
+        self.set_verticalalignment(verticalalignment)
+        self.set_horizontalalignment(horizontalalignment)
+        self._multialignment = multialignment
+        self.set_rotation(rotation)
+        self._transform_rotates_text = transform_rotates_text
+        self._bbox_patch = None  # a FancyBboxPatch instance
+        self._renderer = None
+        if linespacing is None:
+            linespacing = 1.2  # Maybe use rcParam later.
+        self.set_linespacing(linespacing)
+        self.set_rotation_mode(rotation_mode)
+        self.set_antialiased(antialiased if antialiased is not None else
+                             mpl.rcParams['text.antialiased'])
+
+    def update(self, kwargs):
+        # docstring inherited
+        ret = []
+        kwargs = cbook.normalize_kwargs(kwargs, Text)
+        sentinel = object()  # bbox can be None, so use another sentinel.
+        # Update fontproperties first, as it has lowest priority.
+        fontproperties = kwargs.pop("fontproperties", sentinel)
+        if fontproperties is not sentinel:
+            ret.append(self.set_fontproperties(fontproperties))
+        # Update bbox last, as it depends on font properties.
+        bbox = kwargs.pop("bbox", sentinel)
+        ret.extend(super().update(kwargs))
+        if bbox is not sentinel:
+            ret.append(self.set_bbox(bbox))
+        return ret
+
+    def __getstate__(self):
+        d = super().__getstate__()
+        # remove the cached _renderer (if it exists)
+        d['_renderer'] = None
+        return d
+
+    def contains(self, mouseevent):
+        """
+        Return whether the mouse event occurred inside the axis-aligned
+        bounding-box of the text.
+        """
+        if (self._different_canvas(mouseevent) or not self.get_visible()
+                or self._renderer is None):
+            return False, {}
+        # Explicitly use Text.get_window_extent(self) and not
+        # self.get_window_extent() so that Annotation.contains does not
+        # accidentally cover the entire annotation bounding box.
+        bbox = Text.get_window_extent(self)
+        inside = (bbox.x0 <= mouseevent.x <= bbox.x1
+                  and bbox.y0 <= mouseevent.y <= bbox.y1)
+        cattr = {}
+        # if the text has a surrounding patch, also check containment for it,
+        # and merge the results with the results for the text.
+        if self._bbox_patch:
+            patch_inside, patch_cattr = self._bbox_patch.contains(mouseevent)
+            inside = inside or patch_inside
+            cattr["bbox_patch"] = patch_cattr
+        return inside, cattr
+
+    def _get_xy_display(self):
+        """
+        Get the (possibly unit converted) transformed x, y in display coords.
+        """
+        x, y = self.get_unitless_position()
+        return self.get_transform().transform((x, y))
+
+    def _get_multialignment(self):
+        if self._multialignment is not None:
+            return self._multialignment
+        else:
+            return self._horizontalalignment
+
+    def _char_index_at(self, x):
+        """
+        Calculate the index closest to the coordinate x in display space.
+
+        The position of text[index] is assumed to be the sum of the widths
+        of all preceding characters text[:index].
+
+        This works only on single line texts.
+        """
+        if not self._text:
+            return 0
+
+        text = self._text
+
+        fontproperties = str(self._fontproperties)
+        if fontproperties not in Text._charsize_cache:
+            Text._charsize_cache[fontproperties] = dict()
+
+        charsize_cache = Text._charsize_cache[fontproperties]
+        for char in set(text):
+            if char not in charsize_cache:
+                self.set_text(char)
+                bb = self.get_window_extent()
+                charsize_cache[char] = bb.x1 - bb.x0
+
+        self.set_text(text)
+        bb = self.get_window_extent()
+
+        size_accum = np.cumsum([0] + [charsize_cache[x] for x in text])
+        std_x = x - bb.x0
+        return (np.abs(size_accum - std_x)).argmin()
+
+    def get_rotation(self):
+        """Return the text angle in degrees between 0 and 360."""
+        if self.get_transform_rotates_text():
+            return self.get_transform().transform_angles(
+                [self._rotation], [self.get_unitless_position()]).item(0)
+        else:
+            return self._rotation
+
+    def get_transform_rotates_text(self):
+        """
+        Return whether rotations of the transform affect the text direction.
+        """
+        return self._transform_rotates_text
+
+    def set_rotation_mode(self, m):
+        """
+        Set text rotation mode.
+
+        Parameters
+        ----------
+        m : {None, 'default', 'anchor'}
+            If ``"default"``, the text will be first rotated, then aligned according
+            to their horizontal and vertical alignments.  If ``"anchor"``, then
+            alignment occurs before rotation. Passing ``None`` will set the rotation
+            mode to ``"default"``.
+        """
+        if m is None:
+            m = "default"
+        else:
+            _api.check_in_list(("anchor", "default"), rotation_mode=m)
+        self._rotation_mode = m
+        self.stale = True
+
+    def get_rotation_mode(self):
+        """Return the text rotation mode."""
+        return self._rotation_mode
+
+    def set_antialiased(self, antialiased):
+        """
+        Set whether to use antialiased rendering.
+
+        Parameters
+        ----------
+        antialiased : bool
+
+        Notes
+        -----
+        Antialiasing will be determined by :rc:`text.antialiased`
+        and the parameter *antialiased* will have no effect if the text contains
+        math expressions.
+        """
+        self._antialiased = antialiased
+        self.stale = True
+
+    def get_antialiased(self):
+        """Return whether antialiased rendering is used."""
+        return self._antialiased
+
+    def update_from(self, other):
+        # docstring inherited
+        super().update_from(other)
+        self._color = other._color
+        self._multialignment = other._multialignment
+        self._verticalalignment = other._verticalalignment
+        self._horizontalalignment = other._horizontalalignment
+        self._fontproperties = other._fontproperties.copy()
+        self._usetex = other._usetex
+        self._rotation = other._rotation
+        self._transform_rotates_text = other._transform_rotates_text
+        self._picker = other._picker
+        self._linespacing = other._linespacing
+        self._antialiased = other._antialiased
+        self.stale = True
+
+    def _get_layout(self, renderer):
+        """
+        Return the extent (bbox) of the text together with
+        multiple-alignment information. Note that it returns an extent
+        of a rotated text when necessary.
+        """
+        thisx, thisy = 0.0, 0.0
+        lines = self._get_wrapped_text().split("\n")  # Ensures lines is not empty.
+
+        ws = []
+        hs = []
+        xs = []
+        ys = []
+
+        # Full vertical extent of font, including ascenders and descenders:
+        _, lp_h, lp_d = _get_text_metrics_with_cache(
+            renderer, "lp", self._fontproperties,
+            ismath="TeX" if self.get_usetex() else False,
+            dpi=self.get_figure(root=True).dpi)
+        min_dy = (lp_h - lp_d) * self._linespacing
+
+        for i, line in enumerate(lines):
+            clean_line, ismath = self._preprocess_math(line)
+            if clean_line:
+                w, h, d = _get_text_metrics_with_cache(
+                    renderer, clean_line, self._fontproperties,
+                    ismath=ismath, dpi=self.get_figure(root=True).dpi)
+            else:
+                w = h = d = 0
+
+            # For multiline text, increase the line spacing when the text
+            # net-height (excluding baseline) is larger than that of a "l"
+            # (e.g., use of superscripts), which seems what TeX does.
+            h = max(h, lp_h)
+            d = max(d, lp_d)
+
+            ws.append(w)
+            hs.append(h)
+
+            # Metrics of the last line that are needed later:
+            baseline = (h - d) - thisy
+
+            if i == 0:
+                # position at baseline
+                thisy = -(h - d)
+            else:
+                # put baseline a good distance from bottom of previous line
+                thisy -= max(min_dy, (h - d) * self._linespacing)
+
+            xs.append(thisx)  # == 0.
+            ys.append(thisy)
+
+            thisy -= d
+
+        # Metrics of the last line that are needed later:
+        descent = d
+
+        # Bounding box definition:
+        width = max(ws)
+        xmin = 0
+        xmax = width
+        ymax = 0
+        ymin = ys[-1] - descent  # baseline of last line minus its descent
+
+        # get the rotation matrix
+        M = Affine2D().rotate_deg(self.get_rotation())
+
+        # now offset the individual text lines within the box
+        malign = self._get_multialignment()
+        if malign == 'left':
+            offset_layout = [(x, y) for x, y in zip(xs, ys)]
+        elif malign == 'center':
+            offset_layout = [(x + width / 2 - w / 2, y)
+                             for x, y, w in zip(xs, ys, ws)]
+        elif malign == 'right':
+            offset_layout = [(x + width - w, y)
+                             for x, y, w in zip(xs, ys, ws)]
+
+        # the corners of the unrotated bounding box
+        corners_horiz = np.array(
+            [(xmin, ymin), (xmin, ymax), (xmax, ymax), (xmax, ymin)])
+
+        # now rotate the bbox
+        corners_rotated = M.transform(corners_horiz)
+        # compute the bounds of the rotated box
+        xmin = corners_rotated[:, 0].min()
+        xmax = corners_rotated[:, 0].max()
+        ymin = corners_rotated[:, 1].min()
+        ymax = corners_rotated[:, 1].max()
+        width = xmax - xmin
+        height = ymax - ymin
+
+        # Now move the box to the target position offset the display
+        # bbox by alignment
+        halign = self._horizontalalignment
+        valign = self._verticalalignment
+
+        rotation_mode = self.get_rotation_mode()
+        if rotation_mode != "anchor":
+            # compute the text location in display coords and the offsets
+            # necessary to align the bbox with that location
+            if halign == 'center':
+                offsetx = (xmin + xmax) / 2
+            elif halign == 'right':
+                offsetx = xmax
+            else:
+                offsetx = xmin
+
+            if valign == 'center':
+                offsety = (ymin + ymax) / 2
+            elif valign == 'top':
+                offsety = ymax
+            elif valign == 'baseline':
+                offsety = ymin + descent
+            elif valign == 'center_baseline':
+                offsety = ymin + height - baseline / 2.0
+            else:
+                offsety = ymin
+        else:
+            xmin1, ymin1 = corners_horiz[0]
+            xmax1, ymax1 = corners_horiz[2]
+
+            if halign == 'center':
+                offsetx = (xmin1 + xmax1) / 2.0
+            elif halign == 'right':
+                offsetx = xmax1
+            else:
+                offsetx = xmin1
+
+            if valign == 'center':
+                offsety = (ymin1 + ymax1) / 2.0
+            elif valign == 'top':
+                offsety = ymax1
+            elif valign == 'baseline':
+                offsety = ymax1 - baseline
+            elif valign == 'center_baseline':
+                offsety = ymax1 - baseline / 2.0
+            else:
+                offsety = ymin1
+
+            offsetx, offsety = M.transform((offsetx, offsety))
+
+        xmin -= offsetx
+        ymin -= offsety
+
+        bbox = Bbox.from_bounds(xmin, ymin, width, height)
+
+        # now rotate the positions around the first (x, y) position
+        xys = M.transform(offset_layout) - (offsetx, offsety)
+
+        return bbox, list(zip(lines, zip(ws, hs), *xys.T)), descent
+
+    def set_bbox(self, rectprops):
+        """
+        Draw a bounding box around self.
+
+        Parameters
+        ----------
+        rectprops : dict with properties for `.patches.FancyBboxPatch`
+             The default boxstyle is 'square'. The mutation
+             scale of the `.patches.FancyBboxPatch` is set to the fontsize.
+
+        Examples
+        --------
+        ::
+
+            t.set_bbox(dict(facecolor='red', alpha=0.5))
+        """
+
+        if rectprops is not None:
+            props = rectprops.copy()
+            boxstyle = props.pop("boxstyle", None)
+            pad = props.pop("pad", None)
+            if boxstyle is None:
+                boxstyle = "square"
+                if pad is None:
+                    pad = 4  # points
+                pad /= self.get_size()  # to fraction of font size
+            else:
+                if pad is None:
+                    pad = 0.3
+            # boxstyle could be a callable or a string
+            if isinstance(boxstyle, str) and "pad" not in boxstyle:
+                boxstyle += ",pad=%0.2f" % pad
+            self._bbox_patch = FancyBboxPatch(
+                (0, 0), 1, 1,
+                boxstyle=boxstyle, transform=IdentityTransform(), **props)
+        else:
+            self._bbox_patch = None
+
+        self._update_clip_properties()
+
+    def get_bbox_patch(self):
+        """
+        Return the bbox Patch, or None if the `.patches.FancyBboxPatch`
+        is not made.
+        """
+        return self._bbox_patch
+
+    def update_bbox_position_size(self, renderer):
+        """
+        Update the location and the size of the bbox.
+
+        This method should be used when the position and size of the bbox needs
+        to be updated before actually drawing the bbox.
+        """
+        if self._bbox_patch:
+            # don't use self.get_unitless_position here, which refers to text
+            # position in Text:
+            posx = float(self.convert_xunits(self._x))
+            posy = float(self.convert_yunits(self._y))
+            posx, posy = self.get_transform().transform((posx, posy))
+
+            x_box, y_box, w_box, h_box = _get_textbox(self, renderer)
+            self._bbox_patch.set_bounds(0., 0., w_box, h_box)
+            self._bbox_patch.set_transform(
+                Affine2D()
+                .rotate_deg(self.get_rotation())
+                .translate(posx + x_box, posy + y_box))
+            fontsize_in_pixel = renderer.points_to_pixels(self.get_size())
+            self._bbox_patch.set_mutation_scale(fontsize_in_pixel)
+
+    def _update_clip_properties(self):
+        if self._bbox_patch:
+            clipprops = dict(clip_box=self.clipbox,
+                             clip_path=self._clippath,
+                             clip_on=self._clipon)
+            self._bbox_patch.update(clipprops)
+
+    def set_clip_box(self, clipbox):
+        # docstring inherited.
+        super().set_clip_box(clipbox)
+        self._update_clip_properties()
+
+    def set_clip_path(self, path, transform=None):
+        # docstring inherited.
+        super().set_clip_path(path, transform)
+        self._update_clip_properties()
+
+    def set_clip_on(self, b):
+        # docstring inherited.
+        super().set_clip_on(b)
+        self._update_clip_properties()
+
+    def get_wrap(self):
+        """Return whether the text can be wrapped."""
+        return self._wrap
+
+    def set_wrap(self, wrap):
+        """
+        Set whether the text can be wrapped.
+
+        Wrapping makes sure the text is confined to the (sub)figure box. It
+        does not take into account any other artists.
+
+        Parameters
+        ----------
+        wrap : bool
+
+        Notes
+        -----
+        Wrapping does not work together with
+        ``savefig(..., bbox_inches='tight')`` (which is also used internally
+        by ``%matplotlib inline`` in IPython/Jupyter). The 'tight' setting
+        rescales the canvas to accommodate all content and happens before
+        wrapping.
+        """
+        self._wrap = wrap
+
+    def _get_wrap_line_width(self):
+        """
+        Return the maximum line width for wrapping text based on the current
+        orientation.
+        """
+        x0, y0 = self.get_transform().transform(self.get_position())
+        figure_box = self.get_figure().get_window_extent()
+
+        # Calculate available width based on text alignment
+        alignment = self.get_horizontalalignment()
+        self.set_rotation_mode('anchor')
+        rotation = self.get_rotation()
+
+        left = self._get_dist_to_box(rotation, x0, y0, figure_box)
+        right = self._get_dist_to_box(
+            (180 + rotation) % 360, x0, y0, figure_box)
+
+        if alignment == 'left':
+            line_width = left
+        elif alignment == 'right':
+            line_width = right
+        else:
+            line_width = 2 * min(left, right)
+
+        return line_width
+
+    def _get_dist_to_box(self, rotation, x0, y0, figure_box):
+        """
+        Return the distance from the given points to the boundaries of a
+        rotated box, in pixels.
+        """
+        if rotation > 270:
+            quad = rotation - 270
+            h1 = (y0 - figure_box.y0) / math.cos(math.radians(quad))
+            h2 = (figure_box.x1 - x0) / math.cos(math.radians(90 - quad))
+        elif rotation > 180:
+            quad = rotation - 180
+            h1 = (x0 - figure_box.x0) / math.cos(math.radians(quad))
+            h2 = (y0 - figure_box.y0) / math.cos(math.radians(90 - quad))
+        elif rotation > 90:
+            quad = rotation - 90
+            h1 = (figure_box.y1 - y0) / math.cos(math.radians(quad))
+            h2 = (x0 - figure_box.x0) / math.cos(math.radians(90 - quad))
+        else:
+            h1 = (figure_box.x1 - x0) / math.cos(math.radians(rotation))
+            h2 = (figure_box.y1 - y0) / math.cos(math.radians(90 - rotation))
+
+        return min(h1, h2)
+
+    def _get_rendered_text_width(self, text):
+        """
+        Return the width of a given text string, in pixels.
+        """
+
+        w, h, d = _get_text_metrics_with_cache(
+            self._renderer, text, self.get_fontproperties(),
+            cbook.is_math_text(text),
+            self.get_figure(root=True).dpi)
+        return math.ceil(w)
+
+    def _get_wrapped_text(self):
+        """
+        Return a copy of the text string with new lines added so that the text
+        is wrapped relative to the parent figure (if `get_wrap` is True).
+        """
+        if not self.get_wrap():
+            return self.get_text()
+
+        # Not fit to handle breaking up latex syntax correctly, so
+        # ignore latex for now.
+        if self.get_usetex():
+            return self.get_text()
+
+        # Build the line incrementally, for a more accurate measure of length
+        line_width = self._get_wrap_line_width()
+        wrapped_lines = []
+
+        # New lines in the user's text force a split
+        unwrapped_lines = self.get_text().split('\n')
+
+        # Now wrap each individual unwrapped line
+        for unwrapped_line in unwrapped_lines:
+
+            sub_words = unwrapped_line.split(' ')
+            # Remove items from sub_words as we go, so stop when empty
+            while len(sub_words) > 0:
+                if len(sub_words) == 1:
+                    # Only one word, so just add it to the end
+                    wrapped_lines.append(sub_words.pop(0))
+                    continue
+
+                for i in range(2, len(sub_words) + 1):
+                    # Get width of all words up to and including here
+                    line = ' '.join(sub_words[:i])
+                    current_width = self._get_rendered_text_width(line)
+
+                    # If all these words are too wide, append all not including
+                    # last word
+                    if current_width > line_width:
+                        wrapped_lines.append(' '.join(sub_words[:i - 1]))
+                        sub_words = sub_words[i - 1:]
+                        break
+
+                    # Otherwise if all words fit in the width, append them all
+                    elif i == len(sub_words):
+                        wrapped_lines.append(' '.join(sub_words[:i]))
+                        sub_words = []
+                        break
+
+        return '\n'.join(wrapped_lines)
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        # docstring inherited
+
+        if renderer is not None:
+            self._renderer = renderer
+        if not self.get_visible():
+            return
+        if self.get_text() == '':
+            return
+
+        renderer.open_group('text', self.get_gid())
+
+        with self._cm_set(text=self._get_wrapped_text()):
+            bbox, info, descent = self._get_layout(renderer)
+            trans = self.get_transform()
+
+            # don't use self.get_position here, which refers to text
+            # position in Text:
+            x, y = self._x, self._y
+            if np.ma.is_masked(x):
+                x = np.nan
+            if np.ma.is_masked(y):
+                y = np.nan
+            posx = float(self.convert_xunits(x))
+            posy = float(self.convert_yunits(y))
+            posx, posy = trans.transform((posx, posy))
+            if np.isnan(posx) or np.isnan(posy):
+                return  # don't throw a warning here
+            if not np.isfinite(posx) or not np.isfinite(posy):
+                _log.warning("posx and posy should be finite values")
+                return
+            canvasw, canvash = renderer.get_canvas_width_height()
+
+            # Update the location and size of the bbox
+            # (`.patches.FancyBboxPatch`), and draw it.
+            if self._bbox_patch:
+                self.update_bbox_position_size(renderer)
+                self._bbox_patch.draw(renderer)
+
+            gc = renderer.new_gc()
+            gc.set_foreground(self.get_color())
+            gc.set_alpha(self.get_alpha())
+            gc.set_url(self._url)
+            gc.set_antialiased(self._antialiased)
+            self._set_gc_clip(gc)
+
+            angle = self.get_rotation()
+
+            for line, wh, x, y in info:
+
+                mtext = self if len(info) == 1 else None
+                x = x + posx
+                y = y + posy
+                if renderer.flipy():
+                    y = canvash - y
+                clean_line, ismath = self._preprocess_math(line)
+
+                if self.get_path_effects():
+                    from matplotlib.patheffects import PathEffectRenderer
+                    textrenderer = PathEffectRenderer(
+                        self.get_path_effects(), renderer)
+                else:
+                    textrenderer = renderer
+
+                if self.get_usetex():
+                    textrenderer.draw_tex(gc, x, y, clean_line,
+                                          self._fontproperties, angle,
+                                          mtext=mtext)
+                else:
+                    textrenderer.draw_text(gc, x, y, clean_line,
+                                           self._fontproperties, angle,
+                                           ismath=ismath, mtext=mtext)
+
+        gc.restore()
+        renderer.close_group('text')
+        self.stale = False
+
+    def get_color(self):
+        """Return the color of the text."""
+        return self._color
+
+    def get_fontproperties(self):
+        """Return the `.font_manager.FontProperties`."""
+        return self._fontproperties
+
+    def get_fontfamily(self):
+        """
+        Return the list of font families used for font lookup.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_family
+        """
+        return self._fontproperties.get_family()
+
+    def get_fontname(self):
+        """
+        Return the font name as a string.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_name
+        """
+        return self._fontproperties.get_name()
+
+    def get_fontstyle(self):
+        """
+        Return the font style as a string.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_style
+        """
+        return self._fontproperties.get_style()
+
+    def get_fontsize(self):
+        """
+        Return the font size as an integer.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_size_in_points
+        """
+        return self._fontproperties.get_size_in_points()
+
+    def get_fontvariant(self):
+        """
+        Return the font variant as a string.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_variant
+        """
+        return self._fontproperties.get_variant()
+
+    def get_fontweight(self):
+        """
+        Return the font weight as a string or a number.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_weight
+        """
+        return self._fontproperties.get_weight()
+
+    def get_stretch(self):
+        """
+        Return the font stretch as a string or a number.
+
+        See Also
+        --------
+        .font_manager.FontProperties.get_stretch
+        """
+        return self._fontproperties.get_stretch()
+
+    def get_horizontalalignment(self):
+        """
+        Return the horizontal alignment as a string.  Will be one of
+        'left', 'center' or 'right'.
+        """
+        return self._horizontalalignment
+
+    def get_unitless_position(self):
+        """Return the (x, y) unitless position of the text."""
+        # This will get the position with all unit information stripped away.
+        # This is here for convenience since it is done in several locations.
+        x = float(self.convert_xunits(self._x))
+        y = float(self.convert_yunits(self._y))
+        return x, y
+
+    def get_position(self):
+        """Return the (x, y) position of the text."""
+        # This should return the same data (possible unitized) as was
+        # specified with 'set_x' and 'set_y'.
+        return self._x, self._y
+
+    def get_text(self):
+        """Return the text string."""
+        return self._text
+
+    def get_verticalalignment(self):
+        """
+        Return the vertical alignment as a string.  Will be one of
+        'top', 'center', 'bottom', 'baseline' or 'center_baseline'.
+        """
+        return self._verticalalignment
+
+    def get_window_extent(self, renderer=None, dpi=None):
+        """
+        Return the `.Bbox` bounding the text, in display units.
+
+        In addition to being used internally, this is useful for specifying
+        clickable regions in a png file on a web page.
+
+        Parameters
+        ----------
+        renderer : Renderer, optional
+            A renderer is needed to compute the bounding box.  If the artist
+            has already been drawn, the renderer is cached; thus, it is only
+            necessary to pass this argument when calling `get_window_extent`
+            before the first draw.  In practice, it is usually easier to
+            trigger a draw first, e.g. by calling
+            `~.Figure.draw_without_rendering` or ``plt.show()``.
+
+        dpi : float, optional
+            The dpi value for computing the bbox, defaults to
+            ``self.get_figure(root=True).dpi`` (*not* the renderer dpi); should be set
+            e.g. if to match regions with a figure saved with a custom dpi value.
+        """
+        if not self.get_visible():
+            return Bbox.unit()
+
+        fig = self.get_figure(root=True)
+        if dpi is None:
+            dpi = fig.dpi
+        if self.get_text() == '':
+            with cbook._setattr_cm(fig, dpi=dpi):
+                tx, ty = self._get_xy_display()
+                return Bbox.from_bounds(tx, ty, 0, 0)
+
+        if renderer is not None:
+            self._renderer = renderer
+        if self._renderer is None:
+            self._renderer = fig._get_renderer()
+        if self._renderer is None:
+            raise RuntimeError(
+                "Cannot get window extent of text w/o renderer. You likely "
+                "want to call 'figure.draw_without_rendering()' first.")
+
+        with cbook._setattr_cm(fig, dpi=dpi):
+            bbox, info, descent = self._get_layout(self._renderer)
+            x, y = self.get_unitless_position()
+            x, y = self.get_transform().transform((x, y))
+            bbox = bbox.translated(x, y)
+            return bbox
+
+    def set_backgroundcolor(self, color):
+        """
+        Set the background color of the text by updating the bbox.
+
+        Parameters
+        ----------
+        color : :mpltype:`color`
+
+        See Also
+        --------
+        .set_bbox : To change the position of the bounding box
+        """
+        if self._bbox_patch is None:
+            self.set_bbox(dict(facecolor=color, edgecolor=color))
+        else:
+            self._bbox_patch.update(dict(facecolor=color))
+
+        self._update_clip_properties()
+        self.stale = True
+
+    def set_color(self, color):
+        """
+        Set the foreground color of the text
+
+        Parameters
+        ----------
+        color : :mpltype:`color`
+        """
+        # "auto" is only supported by axisartist, but we can just let it error
+        # out at draw time for simplicity.
+        if not cbook._str_equal(color, "auto"):
+            mpl.colors._check_color_like(color=color)
+        self._color = color
+        self.stale = True
+
+    def set_horizontalalignment(self, align):
+        """
+        Set the horizontal alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text_labels_and_annotations/text_alignment`.
+
+        Parameters
+        ----------
+        align : {'left', 'center', 'right'}
+        """
+        _api.check_in_list(['center', 'right', 'left'], align=align)
+        self._horizontalalignment = align
+        self.stale = True
+
+    def set_multialignment(self, align):
+        """
+        Set the text alignment for multiline texts.
+
+        The layout of the bounding box of all the lines is determined by the
+        horizontalalignment and verticalalignment properties. This property
+        controls the alignment of the text lines within that box.
+
+        Parameters
+        ----------
+        align : {'left', 'right', 'center'}
+        """
+        _api.check_in_list(['center', 'right', 'left'], align=align)
+        self._multialignment = align
+        self.stale = True
+
+    def set_linespacing(self, spacing):
+        """
+        Set the line spacing as a multiple of the font size.
+
+        The default line spacing is 1.2.
+
+        Parameters
+        ----------
+        spacing : float (multiple of font size)
+        """
+        _api.check_isinstance(Real, spacing=spacing)
+        self._linespacing = spacing
+        self.stale = True
+
+    def set_fontfamily(self, fontname):
+        """
+        Set the font family.  Can be either a single string, or a list of
+        strings in decreasing priority.  Each string may be either a real font
+        name or a generic font class name.  If the latter, the specific font
+        names will be looked up in the corresponding rcParams.
+
+        If a `Text` instance is constructed with ``fontfamily=None``, then the
+        font is set to :rc:`font.family`, and the
+        same is done when `set_fontfamily()` is called on an existing
+        `Text` instance.
+
+        Parameters
+        ----------
+        fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', \
+'monospace'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_family
+        """
+        self._fontproperties.set_family(fontname)
+        self.stale = True
+
+    def set_fontvariant(self, variant):
+        """
+        Set the font variant.
+
+        Parameters
+        ----------
+        variant : {'normal', 'small-caps'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_variant
+        """
+        self._fontproperties.set_variant(variant)
+        self.stale = True
+
+    def set_fontstyle(self, fontstyle):
+        """
+        Set the font style.
+
+        Parameters
+        ----------
+        fontstyle : {'normal', 'italic', 'oblique'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_style
+        """
+        self._fontproperties.set_style(fontstyle)
+        self.stale = True
+
+    def set_fontsize(self, fontsize):
+        """
+        Set the font size.
+
+        Parameters
+        ----------
+        fontsize : float or {'xx-small', 'x-small', 'small', 'medium', \
+'large', 'x-large', 'xx-large'}
+            If a float, the fontsize in points. The string values denote sizes
+            relative to the default font size.
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_size
+        """
+        self._fontproperties.set_size(fontsize)
+        self.stale = True
+
+    def get_math_fontfamily(self):
+        """
+        Return the font family name for math text rendered by Matplotlib.
+
+        The default value is :rc:`mathtext.fontset`.
+
+        See Also
+        --------
+        set_math_fontfamily
+        """
+        return self._fontproperties.get_math_fontfamily()
+
+    def set_math_fontfamily(self, fontfamily):
+        """
+        Set the font family for math text rendered by Matplotlib.
+
+        This does only affect Matplotlib's own math renderer. It has no effect
+        when rendering with TeX (``usetex=True``).
+
+        Parameters
+        ----------
+        fontfamily : str
+            The name of the font family.
+
+            Available font families are defined in the
+            :ref:`default matplotlibrc file
+            <customizing-with-matplotlibrc-files>`.
+
+        See Also
+        --------
+        get_math_fontfamily
+        """
+        self._fontproperties.set_math_fontfamily(fontfamily)
+
+    def set_fontweight(self, weight):
+        """
+        Set the font weight.
+
+        Parameters
+        ----------
+        weight : {a numeric value in range 0-1000, 'ultralight', 'light', \
+'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', \
+'demi', 'bold', 'heavy', 'extra bold', 'black'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_weight
+        """
+        self._fontproperties.set_weight(weight)
+        self.stale = True
+
+    def set_fontstretch(self, stretch):
+        """
+        Set the font stretch (horizontal condensation or expansion).
+
+        Parameters
+        ----------
+        stretch : {a numeric value in range 0-1000, 'ultra-condensed', \
+'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', \
+'expanded', 'extra-expanded', 'ultra-expanded'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_stretch
+        """
+        self._fontproperties.set_stretch(stretch)
+        self.stale = True
+
+    def set_position(self, xy):
+        """
+        Set the (*x*, *y*) position of the text.
+
+        Parameters
+        ----------
+        xy : (float, float)
+        """
+        self.set_x(xy[0])
+        self.set_y(xy[1])
+
+    def set_x(self, x):
+        """
+        Set the *x* position of the text.
+
+        Parameters
+        ----------
+        x : float
+        """
+        self._x = x
+        self.stale = True
+
+    def set_y(self, y):
+        """
+        Set the *y* position of the text.
+
+        Parameters
+        ----------
+        y : float
+        """
+        self._y = y
+        self.stale = True
+
+    def set_rotation(self, s):
+        """
+        Set the rotation of the text.
+
+        Parameters
+        ----------
+        s : float or {'vertical', 'horizontal'}
+            The rotation angle in degrees in mathematically positive direction
+            (counterclockwise). 'horizontal' equals 0, 'vertical' equals 90.
+        """
+        if isinstance(s, Real):
+            self._rotation = float(s) % 360
+        elif cbook._str_equal(s, 'horizontal') or s is None:
+            self._rotation = 0.
+        elif cbook._str_equal(s, 'vertical'):
+            self._rotation = 90.
+        else:
+            raise ValueError("rotation must be 'vertical', 'horizontal' or "
+                             f"a number, not {s}")
+        self.stale = True
+
+    def set_transform_rotates_text(self, t):
+        """
+        Whether rotations of the transform affect the text direction.
+
+        Parameters
+        ----------
+        t : bool
+        """
+        self._transform_rotates_text = t
+        self.stale = True
+
+    def set_verticalalignment(self, align):
+        """
+        Set the vertical alignment relative to the anchor point.
+
+        See also :doc:`/gallery/text_labels_and_annotations/text_alignment`.
+
+        Parameters
+        ----------
+        align : {'baseline', 'bottom', 'center', 'center_baseline', 'top'}
+        """
+        _api.check_in_list(
+            ['top', 'bottom', 'center', 'baseline', 'center_baseline'],
+            align=align)
+        self._verticalalignment = align
+        self.stale = True
+
+    def set_text(self, s):
+        r"""
+        Set the text string *s*.
+
+        It may contain newlines (``\n``) or math in LaTeX syntax.
+
+        Parameters
+        ----------
+        s : object
+            Any object gets converted to its `str` representation, except for
+            ``None`` which is converted to an empty string.
+        """
+        s = '' if s is None else str(s)
+        if s != self._text:
+            self._text = s
+            self.stale = True
+
+    def _preprocess_math(self, s):
+        """
+        Return the string *s* after mathtext preprocessing, and the kind of
+        mathtext support needed.
+
+        - If *self* is configured to use TeX, return *s* unchanged except that
+          a single space gets escaped, and the flag "TeX".
+        - Otherwise, if *s* is mathtext (has an even number of unescaped dollar
+          signs) and ``parse_math`` is not set to False, return *s* and the
+          flag True.
+        - Otherwise, return *s* with dollar signs unescaped, and the flag
+          False.
+        """
+        if self.get_usetex():
+            if s == " ":
+                s = r"\ "
+            return s, "TeX"
+        elif not self.get_parse_math():
+            return s, False
+        elif cbook.is_math_text(s):
+            return s, True
+        else:
+            return s.replace(r"\$", "$"), False
+
+    def set_fontproperties(self, fp):
+        """
+        Set the font properties that control the text.
+
+        Parameters
+        ----------
+        fp : `.font_manager.FontProperties` or `str` or `pathlib.Path`
+            If a `str`, it is interpreted as a fontconfig pattern parsed by
+            `.FontProperties`.  If a `pathlib.Path`, it is interpreted as the
+            absolute path to a font file.
+        """
+        self._fontproperties = FontProperties._from_any(fp).copy()
+        self.stale = True
+
+    @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
+    def set_usetex(self, usetex):
+        """
+        Parameters
+        ----------
+        usetex : bool or None
+            Whether to render using TeX, ``None`` means to use
+            :rc:`text.usetex`.
+        """
+        if usetex is None:
+            self._usetex = mpl.rcParams['text.usetex']
+        else:
+            self._usetex = bool(usetex)
+        self.stale = True
+
+    def get_usetex(self):
+        """Return whether this `Text` object uses TeX for rendering."""
+        return self._usetex
+
+    def set_parse_math(self, parse_math):
+        """
+        Override switch to disable any mathtext parsing for this `Text`.
+
+        Parameters
+        ----------
+        parse_math : bool
+            If False, this `Text` will never use mathtext.  If True, mathtext
+            will be used if there is an even number of unescaped dollar signs.
+        """
+        self._parse_math = bool(parse_math)
+
+    def get_parse_math(self):
+        """Return whether mathtext parsing is considered for this `Text`."""
+        return self._parse_math
+
+    def set_fontname(self, fontname):
+        """
+        Alias for `set_fontfamily`.
+
+        One-way alias only: the getter differs.
+
+        Parameters
+        ----------
+        fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', \
+'monospace'}
+
+        See Also
+        --------
+        .font_manager.FontProperties.set_family
+
+        """
+        self.set_fontfamily(fontname)
+
+
+class OffsetFrom:
+    """Callable helper class for working with `Annotation`."""
+
+    def __init__(self, artist, ref_coord, unit="points"):
+        """
+        Parameters
+        ----------
+        artist : `~matplotlib.artist.Artist` or `.BboxBase` or `.Transform`
+            The object to compute the offset from.
+
+        ref_coord : (float, float)
+            If *artist* is an `.Artist` or `.BboxBase`, this values is
+            the location to of the offset origin in fractions of the
+            *artist* bounding box.
+
+            If *artist* is a transform, the offset origin is the
+            transform applied to this value.
+
+        unit : {'points, 'pixels'}, default: 'points'
+            The screen units to use (pixels or points) for the offset input.
+        """
+        self._artist = artist
+        x, y = ref_coord  # Make copy when ref_coord is an array (and check the shape).
+        self._ref_coord = x, y
+        self.set_unit(unit)
+
+    def set_unit(self, unit):
+        """
+        Set the unit for input to the transform used by ``__call__``.
+
+        Parameters
+        ----------
+        unit : {'points', 'pixels'}
+        """
+        _api.check_in_list(["points", "pixels"], unit=unit)
+        self._unit = unit
+
+    def get_unit(self):
+        """Return the unit for input to the transform used by ``__call__``."""
+        return self._unit
+
+    def __call__(self, renderer):
+        """
+        Return the offset transform.
+
+        Parameters
+        ----------
+        renderer : `RendererBase`
+            The renderer to use to compute the offset
+
+        Returns
+        -------
+        `Transform`
+            Maps (x, y) in pixel or point units to screen units
+            relative to the given artist.
+        """
+        if isinstance(self._artist, Artist):
+            bbox = self._artist.get_window_extent(renderer)
+            xf, yf = self._ref_coord
+            x = bbox.x0 + bbox.width * xf
+            y = bbox.y0 + bbox.height * yf
+        elif isinstance(self._artist, BboxBase):
+            bbox = self._artist
+            xf, yf = self._ref_coord
+            x = bbox.x0 + bbox.width * xf
+            y = bbox.y0 + bbox.height * yf
+        elif isinstance(self._artist, Transform):
+            x, y = self._artist.transform(self._ref_coord)
+        else:
+            _api.check_isinstance((Artist, BboxBase, Transform), artist=self._artist)
+        scale = 1 if self._unit == "pixels" else renderer.points_to_pixels(1)
+        return Affine2D().scale(scale).translate(x, y)
+
+
+class _AnnotationBase:
+    def __init__(self,
+                 xy,
+                 xycoords='data',
+                 annotation_clip=None):
+
+        x, y = xy  # Make copy when xy is an array (and check the shape).
+        self.xy = x, y
+        self.xycoords = xycoords
+        self.set_annotation_clip(annotation_clip)
+
+        self._draggable = None
+
+    def _get_xy(self, renderer, xy, coords):
+        x, y = xy
+        xcoord, ycoord = coords if isinstance(coords, tuple) else (coords, coords)
+        if xcoord == 'data':
+            x = float(self.convert_xunits(x))
+        if ycoord == 'data':
+            y = float(self.convert_yunits(y))
+        return self._get_xy_transform(renderer, coords).transform((x, y))
+
+    def _get_xy_transform(self, renderer, coords):
+
+        if isinstance(coords, tuple):
+            xcoord, ycoord = coords
+            from matplotlib.transforms import blended_transform_factory
+            tr1 = self._get_xy_transform(renderer, xcoord)
+            tr2 = self._get_xy_transform(renderer, ycoord)
+            return blended_transform_factory(tr1, tr2)
+        elif callable(coords):
+            tr = coords(renderer)
+            if isinstance(tr, BboxBase):
+                return BboxTransformTo(tr)
+            elif isinstance(tr, Transform):
+                return tr
+            else:
+                raise TypeError(
+                    f"xycoords callable must return a BboxBase or Transform, not a "
+                    f"{type(tr).__name__}")
+        elif isinstance(coords, Artist):
+            bbox = coords.get_window_extent(renderer)
+            return BboxTransformTo(bbox)
+        elif isinstance(coords, BboxBase):
+            return BboxTransformTo(coords)
+        elif isinstance(coords, Transform):
+            return coords
+        elif not isinstance(coords, str):
+            raise TypeError(
+                f"'xycoords' must be an instance of str, tuple[str, str], Artist, "
+                f"Transform, or Callable, not a {type(coords).__name__}")
+
+        if coords == 'data':
+            return self.axes.transData
+        elif coords == 'polar':
+            from matplotlib.projections import PolarAxes
+            tr = PolarAxes.PolarTransform(apply_theta_transforms=False)
+            trans = tr + self.axes.transData
+            return trans
+
+        try:
+            bbox_name, unit = coords.split()
+        except ValueError:  # i.e. len(coords.split()) != 2.
+            raise ValueError(f"{coords!r} is not a valid coordinate") from None
+
+        bbox0, xy0 = None, None
+
+        # if unit is offset-like
+        if bbox_name == "figure":
+            bbox0 = self.get_figure(root=False).figbbox
+        elif bbox_name == "subfigure":
+            bbox0 = self.get_figure(root=False).bbox
+        elif bbox_name == "axes":
+            bbox0 = self.axes.bbox
+
+        # reference x, y in display coordinate
+        if bbox0 is not None:
+            xy0 = bbox0.p0
+        elif bbox_name == "offset":
+            xy0 = self._get_position_xy(renderer)
+        else:
+            raise ValueError(f"{coords!r} is not a valid coordinate")
+
+        if unit == "points":
+            tr = Affine2D().scale(
+                self.get_figure(root=True).dpi / 72)  # dpi/72 dots per point
+        elif unit == "pixels":
+            tr = Affine2D()
+        elif unit == "fontsize":
+            tr = Affine2D().scale(
+                self.get_size() * self.get_figure(root=True).dpi / 72)
+        elif unit == "fraction":
+            tr = Affine2D().scale(*bbox0.size)
+        else:
+            raise ValueError(f"{unit!r} is not a recognized unit")
+
+        return tr.translate(*xy0)
+
+    def set_annotation_clip(self, b):
+        """
+        Set the annotation's clipping behavior.
+
+        Parameters
+        ----------
+        b : bool or None
+            - True: The annotation will be clipped when ``self.xy`` is
+              outside the Axes.
+            - False: The annotation will always be drawn.
+            - None: The annotation will be clipped when ``self.xy`` is
+              outside the Axes and ``self.xycoords == "data"``.
+        """
+        self._annotation_clip = b
+
+    def get_annotation_clip(self):
+        """
+        Return the annotation's clipping behavior.
+
+        See `set_annotation_clip` for the meaning of return values.
+        """
+        return self._annotation_clip
+
+    def _get_position_xy(self, renderer):
+        """Return the pixel position of the annotated point."""
+        return self._get_xy(renderer, self.xy, self.xycoords)
+
+    def _check_xy(self, renderer=None):
+        """Check whether the annotation at *xy_pixel* should be drawn."""
+        if renderer is None:
+            renderer = self.get_figure(root=True)._get_renderer()
+        b = self.get_annotation_clip()
+        if b or (b is None and self.xycoords == "data"):
+            # check if self.xy is inside the Axes.
+            xy_pixel = self._get_position_xy(renderer)
+            return self.axes.contains_point(xy_pixel)
+        return True
+
+    def draggable(self, state=None, use_blit=False):
+        """
+        Set whether the annotation is draggable with the mouse.
+
+        Parameters
+        ----------
+        state : bool or None
+            - True or False: set the draggability.
+            - None: toggle the draggability.
+        use_blit : bool, default: False
+            Use blitting for faster image composition. For details see
+            :ref:`func-animation`.
+
+        Returns
+        -------
+        DraggableAnnotation or None
+            If the annotation is draggable, the corresponding
+            `.DraggableAnnotation` helper is returned.
+        """
+        from matplotlib.offsetbox import DraggableAnnotation
+        is_draggable = self._draggable is not None
+
+        # if state is None we'll toggle
+        if state is None:
+            state = not is_draggable
+
+        if state:
+            if self._draggable is None:
+                self._draggable = DraggableAnnotation(self, use_blit)
+        else:
+            if self._draggable is not None:
+                self._draggable.disconnect()
+            self._draggable = None
+
+        return self._draggable
+
+
+class Annotation(Text, _AnnotationBase):
+    """
+    An `.Annotation` is a `.Text` that can refer to a specific position *xy*.
+    Optionally an arrow pointing from the text to *xy* can be drawn.
+
+    Attributes
+    ----------
+    xy
+        The annotated position.
+    xycoords
+        The coordinate system for *xy*.
+    arrow_patch
+        A `.FancyArrowPatch` to point from *xytext* to *xy*.
+    """
+
+    def __str__(self):
+        return f"Annotation({self.xy[0]:g}, {self.xy[1]:g}, {self._text!r})"
+
+    def __init__(self, text, xy,
+                 xytext=None,
+                 xycoords='data',
+                 textcoords=None,
+                 arrowprops=None,
+                 annotation_clip=None,
+                 **kwargs):
+        """
+        Annotate the point *xy* with text *text*.
+
+        In the simplest form, the text is placed at *xy*.
+
+        Optionally, the text can be displayed in another position *xytext*.
+        An arrow pointing from the text to the annotated point *xy* can then
+        be added by defining *arrowprops*.
+
+        Parameters
+        ----------
+        text : str
+            The text of the annotation.
+
+        xy : (float, float)
+            The point *(x, y)* to annotate. The coordinate system is determined
+            by *xycoords*.
+
+        xytext : (float, float), default: *xy*
+            The position *(x, y)* to place the text at. The coordinate system
+            is determined by *textcoords*.
+
+        xycoords : single or two-tuple of str or `.Artist` or `.Transform` or \
+callable, default: 'data'
+
+            The coordinate system that *xy* is given in. The following types
+            of values are supported:
+
+            - One of the following strings:
+
+              ==================== ============================================
+              Value                Description
+              ==================== ============================================
+              'figure points'      Points from the lower left of the figure
+              'figure pixels'      Pixels from the lower left of the figure
+              'figure fraction'    Fraction of figure from lower left
+              'subfigure points'   Points from the lower left of the subfigure
+              'subfigure pixels'   Pixels from the lower left of the subfigure
+              'subfigure fraction' Fraction of subfigure from lower left
+              'axes points'        Points from lower left corner of the Axes
+              'axes pixels'        Pixels from lower left corner of the Axes
+              'axes fraction'      Fraction of Axes from lower left
+              'data'               Use the coordinate system of the object
+                                   being annotated (default)
+              'polar'              *(theta, r)* if not native 'data'
+                                   coordinates
+              ==================== ============================================
+
+              Note that 'subfigure pixels' and 'figure pixels' are the same
+              for the parent figure, so users who want code that is usable in
+              a subfigure can use 'subfigure pixels'.
+
+            - An `.Artist`: *xy* is interpreted as a fraction of the artist's
+              `~matplotlib.transforms.Bbox`. E.g. *(0, 0)* would be the lower
+              left corner of the bounding box and *(0.5, 1)* would be the
+              center top of the bounding box.
+
+            - A `.Transform` to transform *xy* to screen coordinates.
+
+            - A function with one of the following signatures::
+
+                def transform(renderer) -> Bbox
+                def transform(renderer) -> Transform
+
+              where *renderer* is a `.RendererBase` subclass.
+
+              The result of the function is interpreted like the `.Artist` and
+              `.Transform` cases above.
+
+            - A tuple *(xcoords, ycoords)* specifying separate coordinate
+              systems for *x* and *y*. *xcoords* and *ycoords* must each be
+              of one of the above described types.
+
+            See :ref:`plotting-guide-annotation` for more details.
+
+        textcoords : single or two-tuple of str or `.Artist` or `.Transform` \
+or callable, default: value of *xycoords*
+            The coordinate system that *xytext* is given in.
+
+            All *xycoords* values are valid as well as the following strings:
+
+            =================   =================================================
+            Value               Description
+            =================   =================================================
+            'offset points'     Offset, in points, from the *xy* value
+            'offset pixels'     Offset, in pixels, from the *xy* value
+            'offset fontsize'   Offset, relative to fontsize, from the *xy* value
+            =================   =================================================
+
+        arrowprops : dict, optional
+            The properties used to draw a `.FancyArrowPatch` arrow between the
+            positions *xy* and *xytext*.  Defaults to None, i.e. no arrow is
+            drawn.
+
+            For historical reasons there are two different ways to specify
+            arrows, "simple" and "fancy":
+
+            **Simple arrow:**
+
+            If *arrowprops* does not contain the key 'arrowstyle' the
+            allowed keys are:
+
+            ==========  =================================================
+            Key         Description
+            ==========  =================================================
+            width       The width of the arrow in points
+            headwidth   The width of the base of the arrow head in points
+            headlength  The length of the arrow head in points
+            shrink      Fraction of total length to shrink from both ends
+            ?           Any `.FancyArrowPatch` property
+            ==========  =================================================
+
+            The arrow is attached to the edge of the text box, the exact
+            position (corners or centers) depending on where it's pointing to.
+
+            **Fancy arrow:**
+
+            This is used if 'arrowstyle' is provided in the *arrowprops*.
+
+            Valid keys are the following `.FancyArrowPatch` parameters:
+
+            ===============  ===================================
+            Key              Description
+            ===============  ===================================
+            arrowstyle       The arrow style
+            connectionstyle  The connection style
+            relpos           See below; default is (0.5, 0.5)
+            patchA           Default is bounding box of the text
+            patchB           Default is None
+            shrinkA          In points. Default is 2 points
+            shrinkB          In points. Default is 2 points
+            mutation_scale   Default is text size (in points)
+            mutation_aspect  Default is 1
+            ?                Any `.FancyArrowPatch` property
+            ===============  ===================================
+
+            The exact starting point position of the arrow is defined by
+            *relpos*. It's a tuple of relative coordinates of the text box,
+            where (0, 0) is the lower left corner and (1, 1) is the upper
+            right corner. Values <0 and >1 are supported and specify points
+            outside the text box. By default (0.5, 0.5), so the starting point
+            is centered in the text box.
+
+        annotation_clip : bool or None, default: None
+            Whether to clip (i.e. not draw) the annotation when the annotation
+            point *xy* is outside the Axes area.
+
+            - If *True*, the annotation will be clipped when *xy* is outside
+              the Axes.
+            - If *False*, the annotation will always be drawn.
+            - If *None*, the annotation will be clipped when *xy* is outside
+              the Axes and *xycoords* is 'data'.
+
+        **kwargs
+            Additional kwargs are passed to `.Text`.
+
+        Returns
+        -------
+        `.Annotation`
+
+        See Also
+        --------
+        :ref:`annotations`
+
+        """
+        _AnnotationBase.__init__(self,
+                                 xy,
+                                 xycoords=xycoords,
+                                 annotation_clip=annotation_clip)
+        # warn about wonky input data
+        if (xytext is None and
+                textcoords is not None and
+                textcoords != xycoords):
+            _api.warn_external("You have used the `textcoords` kwarg, but "
+                               "not the `xytext` kwarg.  This can lead to "
+                               "surprising results.")
+
+        # clean up textcoords and assign default
+        if textcoords is None:
+            textcoords = self.xycoords
+        self._textcoords = textcoords
+
+        # cleanup xytext defaults
+        if xytext is None:
+            xytext = self.xy
+        x, y = xytext
+
+        self.arrowprops = arrowprops
+        if arrowprops is not None:
+            arrowprops = arrowprops.copy()
+            if "arrowstyle" in arrowprops:
+                self._arrow_relpos = arrowprops.pop("relpos", (0.5, 0.5))
+            else:
+                # modified YAArrow API to be used with FancyArrowPatch
+                for key in ['width', 'headwidth', 'headlength', 'shrink']:
+                    arrowprops.pop(key, None)
+            self.arrow_patch = FancyArrowPatch((0, 0), (1, 1), **arrowprops)
+        else:
+            self.arrow_patch = None
+
+        # Must come last, as some kwargs may be propagated to arrow_patch.
+        Text.__init__(self, x, y, text, **kwargs)
+
+    def contains(self, mouseevent):
+        if self._different_canvas(mouseevent):
+            return False, {}
+        contains, tinfo = Text.contains(self, mouseevent)
+        if self.arrow_patch is not None:
+            in_patch, _ = self.arrow_patch.contains(mouseevent)
+            contains = contains or in_patch
+        return contains, tinfo
+
+    @property
+    def xycoords(self):
+        return self._xycoords
+
+    @xycoords.setter
+    def xycoords(self, xycoords):
+        def is_offset(s):
+            return isinstance(s, str) and s.startswith("offset")
+
+        if (isinstance(xycoords, tuple) and any(map(is_offset, xycoords))
+                or is_offset(xycoords)):
+            raise ValueError("xycoords cannot be an offset coordinate")
+        self._xycoords = xycoords
+
+    @property
+    def xyann(self):
+        """
+        The text position.
+
+        See also *xytext* in `.Annotation`.
+        """
+        return self.get_position()
+
+    @xyann.setter
+    def xyann(self, xytext):
+        self.set_position(xytext)
+
+    def get_anncoords(self):
+        """
+        Return the coordinate system to use for `.Annotation.xyann`.
+
+        See also *xycoords* in `.Annotation`.
+        """
+        return self._textcoords
+
+    def set_anncoords(self, coords):
+        """
+        Set the coordinate system to use for `.Annotation.xyann`.
+
+        See also *xycoords* in `.Annotation`.
+        """
+        self._textcoords = coords
+
+    anncoords = property(get_anncoords, set_anncoords, doc="""
+        The coordinate system to use for `.Annotation.xyann`.""")
+
+    def set_figure(self, fig):
+        # docstring inherited
+        if self.arrow_patch is not None:
+            self.arrow_patch.set_figure(fig)
+        Artist.set_figure(self, fig)
+
+    def update_positions(self, renderer):
+        """
+        Update the pixel positions of the annotation text and the arrow patch.
+        """
+        # generate transformation
+        self.set_transform(self._get_xy_transform(renderer, self.anncoords))
+
+        arrowprops = self.arrowprops
+        if arrowprops is None:
+            return
+
+        bbox = Text.get_window_extent(self, renderer)
+
+        arrow_end = x1, y1 = self._get_position_xy(renderer)  # Annotated pos.
+
+        ms = arrowprops.get("mutation_scale", self.get_size())
+        self.arrow_patch.set_mutation_scale(ms)
+
+        if "arrowstyle" not in arrowprops:
+            # Approximately simulate the YAArrow.
+            shrink = arrowprops.get('shrink', 0.0)
+            width = arrowprops.get('width', 4)
+            headwidth = arrowprops.get('headwidth', 12)
+            headlength = arrowprops.get('headlength', 12)
+
+            # NB: ms is in pts
+            stylekw = dict(head_length=headlength / ms,
+                           head_width=headwidth / ms,
+                           tail_width=width / ms)
+
+            self.arrow_patch.set_arrowstyle('simple', **stylekw)
+
+            # using YAArrow style:
+            # pick the corner of the text bbox closest to annotated point.
+            xpos = [(bbox.x0, 0), ((bbox.x0 + bbox.x1) / 2, 0.5), (bbox.x1, 1)]
+            ypos = [(bbox.y0, 0), ((bbox.y0 + bbox.y1) / 2, 0.5), (bbox.y1, 1)]
+            x, relposx = min(xpos, key=lambda v: abs(v[0] - x1))
+            y, relposy = min(ypos, key=lambda v: abs(v[0] - y1))
+            self._arrow_relpos = (relposx, relposy)
+            r = np.hypot(y - y1, x - x1)
+            shrink_pts = shrink * r / renderer.points_to_pixels(1)
+            self.arrow_patch.shrinkA = self.arrow_patch.shrinkB = shrink_pts
+
+        # adjust the starting point of the arrow relative to the textbox.
+        # TODO : Rotation needs to be accounted.
+        arrow_begin = bbox.p0 + bbox.size * self._arrow_relpos
+        # The arrow is drawn from arrow_begin to arrow_end.  It will be first
+        # clipped by patchA and patchB.  Then it will be shrunk by shrinkA and
+        # shrinkB (in points).  If patchA is not set, self.bbox_patch is used.
+        self.arrow_patch.set_positions(arrow_begin, arrow_end)
+
+        if "patchA" in arrowprops:
+            patchA = arrowprops["patchA"]
+        elif self._bbox_patch:
+            patchA = self._bbox_patch
+        elif self.get_text() == "":
+            patchA = None
+        else:
+            pad = renderer.points_to_pixels(4)
+            patchA = Rectangle(
+                xy=(bbox.x0 - pad / 2, bbox.y0 - pad / 2),
+                width=bbox.width + pad, height=bbox.height + pad,
+                transform=IdentityTransform(), clip_on=False)
+        self.arrow_patch.set_patchA(patchA)
+
+    @artist.allow_rasterization
+    def draw(self, renderer):
+        # docstring inherited
+        if renderer is not None:
+            self._renderer = renderer
+        if not self.get_visible() or not self._check_xy(renderer):
+            return
+        # Update text positions before `Text.draw` would, so that the
+        # FancyArrowPatch is correctly positioned.
+        self.update_positions(renderer)
+        self.update_bbox_position_size(renderer)
+        if self.arrow_patch is not None:  # FancyArrowPatch
+            if (self.arrow_patch.get_figure(root=False) is None and
+                    (fig := self.get_figure(root=False)) is not None):
+                self.arrow_patch.set_figure(fig)
+            self.arrow_patch.draw(renderer)
+        # Draw text, including FancyBboxPatch, after FancyArrowPatch.
+        # Otherwise, a wedge arrowstyle can land partly on top of the Bbox.
+        Text.draw(self, renderer)
+
+    def get_window_extent(self, renderer=None):
+        # docstring inherited
+        # This block is the same as in Text.get_window_extent, but we need to
+        # set the renderer before calling update_positions().
+        if not self.get_visible() or not self._check_xy(renderer):
+            return Bbox.unit()
+        if renderer is not None:
+            self._renderer = renderer
+        if self._renderer is None:
+            self._renderer = self.get_figure(root=True)._get_renderer()
+        if self._renderer is None:
+            raise RuntimeError('Cannot get window extent without renderer')
+
+        self.update_positions(self._renderer)
+
+        text_bbox = Text.get_window_extent(self)
+        bboxes = [text_bbox]
+
+        if self.arrow_patch is not None:
+            bboxes.append(self.arrow_patch.get_window_extent())
+
+        return Bbox.union(bboxes)
+
+    def get_tightbbox(self, renderer=None):
+        # docstring inherited
+        if not self._check_xy(renderer):
+            return Bbox.null()
+        return super().get_tightbbox(renderer)
+
+
+_docstring.interpd.register(Annotation=Annotation.__init__.__doc__)
diff --git a/lib/python3.12/site-packages/matplotlib/text.pyi b/lib/python3.12/site-packages/matplotlib/text.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..d65a3dc4c7da2754b35e59f79e47318e55effa7e
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/text.pyi
@@ -0,0 +1,181 @@
+from .artist import Artist
+from .backend_bases import RendererBase
+from .font_manager import FontProperties
+from .offsetbox import DraggableAnnotation
+from .path import Path
+from .patches import FancyArrowPatch, FancyBboxPatch
+from .textpath import (  # noqa: F401, reexported API
+    TextPath as TextPath,
+    TextToPath as TextToPath,
+)
+from .transforms import (
+    Bbox,
+    BboxBase,
+    Transform,
+)
+
+from collections.abc import Callable, Iterable
+from typing import Any, Literal
+from .typing import ColorType, CoordsType
+
+class Text(Artist):
+    zorder: float
+    def __init__(
+        self,
+        x: float = ...,
+        y: float = ...,
+        text: Any = ...,
+        *,
+        color: ColorType | None = ...,
+        verticalalignment: Literal[
+            "bottom", "baseline", "center", "center_baseline", "top"
+        ] = ...,
+        horizontalalignment: Literal["left", "center", "right"] = ...,
+        multialignment: Literal["left", "center", "right"] | None = ...,
+        fontproperties: str | Path | FontProperties | None = ...,
+        rotation: float | Literal["vertical", "horizontal"] | None = ...,
+        linespacing: float | None = ...,
+        rotation_mode: Literal["default", "anchor"] | None = ...,
+        usetex: bool | None = ...,
+        wrap: bool = ...,
+        transform_rotates_text: bool = ...,
+        parse_math: bool | None = ...,
+        antialiased: bool | None = ...,
+        **kwargs
+    ) -> None: ...
+    def update(self, kwargs: dict[str, Any]) -> list[Any]: ...
+    def get_rotation(self) -> float: ...
+    def get_transform_rotates_text(self) -> bool: ...
+    def set_rotation_mode(self, m: None | Literal["default", "anchor"]) -> None: ...
+    def get_rotation_mode(self) -> Literal["default", "anchor"]: ...
+    def set_bbox(self, rectprops: dict[str, Any]) -> None: ...
+    def get_bbox_patch(self) -> None | FancyBboxPatch: ...
+    def update_bbox_position_size(self, renderer: RendererBase) -> None: ...
+    def get_wrap(self) -> bool: ...
+    def set_wrap(self, wrap: bool) -> None: ...
+    def get_color(self) -> ColorType: ...
+    def get_fontproperties(self) -> FontProperties: ...
+    def get_fontfamily(self) -> list[str]: ...
+    def get_fontname(self) -> str: ...
+    def get_fontstyle(self) -> Literal["normal", "italic", "oblique"]: ...
+    def get_fontsize(self) -> float | str: ...
+    def get_fontvariant(self) -> Literal["normal", "small-caps"]: ...
+    def get_fontweight(self) -> int | str: ...
+    def get_stretch(self) -> int | str: ...
+    def get_horizontalalignment(self) -> Literal["left", "center", "right"]: ...
+    def get_unitless_position(self) -> tuple[float, float]: ...
+    def get_position(self) -> tuple[float, float]: ...
+    def get_text(self) -> str: ...
+    def get_verticalalignment(
+        self,
+    ) -> Literal["bottom", "baseline", "center", "center_baseline", "top"]: ...
+    def get_window_extent(
+        self, renderer: RendererBase | None = ..., dpi: float | None = ...
+    ) -> Bbox: ...
+    def set_backgroundcolor(self, color: ColorType) -> None: ...
+    def set_color(self, color: ColorType) -> None: ...
+    def set_horizontalalignment(
+        self, align: Literal["left", "center", "right"]
+    ) -> None: ...
+    def set_multialignment(self, align: Literal["left", "center", "right"]) -> None: ...
+    def set_linespacing(self, spacing: float) -> None: ...
+    def set_fontfamily(self, fontname: str | Iterable[str]) -> None: ...
+    def set_fontvariant(self, variant: Literal["normal", "small-caps"]) -> None: ...
+    def set_fontstyle(
+        self, fontstyle: Literal["normal", "italic", "oblique"]
+    ) -> None: ...
+    def set_fontsize(self, fontsize: float | str) -> None: ...
+    def get_math_fontfamily(self) -> str: ...
+    def set_math_fontfamily(self, fontfamily: str) -> None: ...
+    def set_fontweight(self, weight: int | str) -> None: ...
+    def set_fontstretch(self, stretch: int | str) -> None: ...
+    def set_position(self, xy: tuple[float, float]) -> None: ...
+    def set_x(self, x: float) -> None: ...
+    def set_y(self, y: float) -> None: ...
+    def set_rotation(self, s: float) -> None: ...
+    def set_transform_rotates_text(self, t: bool) -> None: ...
+    def set_verticalalignment(
+        self, align: Literal["bottom", "baseline", "center", "center_baseline", "top"]
+    ) -> None: ...
+    def set_text(self, s: Any) -> None: ...
+    def set_fontproperties(self, fp: FontProperties | str | Path | None) -> None: ...
+    def set_usetex(self, usetex: bool | None) -> None: ...
+    def get_usetex(self) -> bool: ...
+    def set_parse_math(self, parse_math: bool) -> None: ...
+    def get_parse_math(self) -> bool: ...
+    def set_fontname(self, fontname: str | Iterable[str]) -> None: ...
+    def get_antialiased(self) -> bool: ...
+    def set_antialiased(self, antialiased: bool) -> None: ...
+
+class OffsetFrom:
+    def __init__(
+        self,
+        artist: Artist | BboxBase | Transform,
+        ref_coord: tuple[float, float],
+        unit: Literal["points", "pixels"] = ...,
+    ) -> None: ...
+    def set_unit(self, unit: Literal["points", "pixels"]) -> None: ...
+    def get_unit(self) -> Literal["points", "pixels"]: ...
+    def __call__(self, renderer: RendererBase) -> Transform: ...
+
+class _AnnotationBase:
+    xy: tuple[float, float]
+    xycoords: CoordsType
+    def __init__(
+        self,
+        xy,
+        xycoords: CoordsType = ...,
+        annotation_clip: bool | None = ...,
+    ) -> None: ...
+    def set_annotation_clip(self, b: bool | None) -> None: ...
+    def get_annotation_clip(self) -> bool | None: ...
+    def draggable(
+        self, state: bool | None = ..., use_blit: bool = ...
+    ) -> DraggableAnnotation | None: ...
+
+class Annotation(Text, _AnnotationBase):
+    arrowprops: dict[str, Any] | None
+    arrow_patch: FancyArrowPatch | None
+    def __init__(
+        self,
+        text: str,
+        xy: tuple[float, float],
+        xytext: tuple[float, float] | None = ...,
+        xycoords: CoordsType = ...,
+        textcoords: CoordsType | None = ...,
+        arrowprops: dict[str, Any] | None = ...,
+        annotation_clip: bool | None = ...,
+        **kwargs
+    ) -> None: ...
+    @property
+    def xycoords(
+        self,
+    ) -> CoordsType: ...
+    @xycoords.setter
+    def xycoords(
+        self,
+        xycoords: CoordsType,
+    ) -> None: ...
+    @property
+    def xyann(self) -> tuple[float, float]: ...
+    @xyann.setter
+    def xyann(self, xytext: tuple[float, float]) -> None: ...
+    def get_anncoords(
+        self,
+    ) -> CoordsType: ...
+    def set_anncoords(
+        self,
+        coords: CoordsType,
+    ) -> None: ...
+    @property
+    def anncoords(
+        self,
+    ) -> CoordsType: ...
+    @anncoords.setter
+    def anncoords(
+        self,
+        coords: CoordsType,
+    ) -> None: ...
+    def update_positions(self, renderer: RendererBase) -> None: ...
+    # Drops `dpi` parameter from superclass
+    def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...  # type: ignore[override]
diff --git a/lib/python3.12/site-packages/matplotlib/textpath.py b/lib/python3.12/site-packages/matplotlib/textpath.py
new file mode 100644
index 0000000000000000000000000000000000000000..83182e3f54002fbdef9c8fcae89f64ad0ff87d5f
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/textpath.py
@@ -0,0 +1,397 @@
+from collections import OrderedDict
+import logging
+import urllib.parse
+
+import numpy as np
+
+from matplotlib import _text_helpers, dviread
+from matplotlib.font_manager import (
+    FontProperties, get_font, fontManager as _fontManager
+)
+from matplotlib.ft2font import LoadFlags
+from matplotlib.mathtext import MathTextParser
+from matplotlib.path import Path
+from matplotlib.texmanager import TexManager
+from matplotlib.transforms import Affine2D
+
+_log = logging.getLogger(__name__)
+
+
+class TextToPath:
+    """A class that converts strings to paths."""
+
+    FONT_SCALE = 100.
+    DPI = 72
+
+    def __init__(self):
+        self.mathtext_parser = MathTextParser('path')
+        self._texmanager = None
+
+    def _get_font(self, prop):
+        """
+        Find the `FT2Font` matching font properties *prop*, with its size set.
+        """
+        filenames = _fontManager._find_fonts_by_props(prop)
+        font = get_font(filenames)
+        font.set_size(self.FONT_SCALE, self.DPI)
+        return font
+
+    def _get_hinting_flag(self):
+        return LoadFlags.NO_HINTING
+
+    def _get_char_id(self, font, ccode):
+        """
+        Return a unique id for the given font and character-code set.
+        """
+        return urllib.parse.quote(f"{font.postscript_name}-{ccode:x}")
+
+    def get_text_width_height_descent(self, s, prop, ismath):
+        fontsize = prop.get_size_in_points()
+
+        if ismath == "TeX":
+            return TexManager().get_text_width_height_descent(s, fontsize)
+
+        scale = fontsize / self.FONT_SCALE
+
+        if ismath:
+            prop = prop.copy()
+            prop.set_size(self.FONT_SCALE)
+            width, height, descent, *_ = \
+                self.mathtext_parser.parse(s, 72, prop)
+            return width * scale, height * scale, descent * scale
+
+        font = self._get_font(prop)
+        font.set_text(s, 0.0, flags=LoadFlags.NO_HINTING)
+        w, h = font.get_width_height()
+        w /= 64.0  # convert from subpixels
+        h /= 64.0
+        d = font.get_descent()
+        d /= 64.0
+        return w * scale, h * scale, d * scale
+
+    def get_text_path(self, prop, s, ismath=False):
+        """
+        Convert text *s* to path (a tuple of vertices and codes for
+        matplotlib.path.Path).
+
+        Parameters
+        ----------
+        prop : `~matplotlib.font_manager.FontProperties`
+            The font properties for the text.
+        s : str
+            The text to be converted.
+        ismath : {False, True, "TeX"}
+            If True, use mathtext parser.  If "TeX", use tex for rendering.
+
+        Returns
+        -------
+        verts : list
+            A list of arrays containing the (x, y) coordinates of the vertices.
+        codes : list
+            A list of path codes.
+
+        Examples
+        --------
+        Create a list of vertices and codes from a text, and create a `.Path`
+        from those::
+
+            from matplotlib.path import Path
+            from matplotlib.text import TextToPath
+            from matplotlib.font_manager import FontProperties
+
+            fp = FontProperties(family="Comic Neue", style="italic")
+            verts, codes = TextToPath().get_text_path(fp, "ABC")
+            path = Path(verts, codes, closed=False)
+
+        Also see `TextPath` for a more direct way to create a path from a text.
+        """
+        if ismath == "TeX":
+            glyph_info, glyph_map, rects = self.get_glyphs_tex(prop, s)
+        elif not ismath:
+            font = self._get_font(prop)
+            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s)
+        else:
+            glyph_info, glyph_map, rects = self.get_glyphs_mathtext(prop, s)
+
+        verts, codes = [], []
+        for glyph_id, xposition, yposition, scale in glyph_info:
+            verts1, codes1 = glyph_map[glyph_id]
+            verts.extend(verts1 * scale + [xposition, yposition])
+            codes.extend(codes1)
+        for verts1, codes1 in rects:
+            verts.extend(verts1)
+            codes.extend(codes1)
+
+        # Make sure an empty string or one with nothing to print
+        # (e.g. only spaces & newlines) will be valid/empty path
+        if not verts:
+            verts = np.empty((0, 2))
+
+        return verts, codes
+
+    def get_glyphs_with_font(self, font, s, glyph_map=None,
+                             return_new_glyphs_only=False):
+        """
+        Convert string *s* to vertices and codes using the provided ttf font.
+        """
+
+        if glyph_map is None:
+            glyph_map = OrderedDict()
+
+        if return_new_glyphs_only:
+            glyph_map_new = OrderedDict()
+        else:
+            glyph_map_new = glyph_map
+
+        xpositions = []
+        glyph_ids = []
+        for item in _text_helpers.layout(s, font):
+            char_id = self._get_char_id(item.ft_object, ord(item.char))
+            glyph_ids.append(char_id)
+            xpositions.append(item.x)
+            if char_id not in glyph_map:
+                glyph_map_new[char_id] = item.ft_object.get_path()
+
+        ypositions = [0] * len(xpositions)
+        sizes = [1.] * len(xpositions)
+
+        rects = []
+
+        return (list(zip(glyph_ids, xpositions, ypositions, sizes)),
+                glyph_map_new, rects)
+
+    def get_glyphs_mathtext(self, prop, s, glyph_map=None,
+                            return_new_glyphs_only=False):
+        """
+        Parse mathtext string *s* and convert it to a (vertices, codes) pair.
+        """
+
+        prop = prop.copy()
+        prop.set_size(self.FONT_SCALE)
+
+        width, height, descent, glyphs, rects = self.mathtext_parser.parse(
+            s, self.DPI, prop)
+
+        if not glyph_map:
+            glyph_map = OrderedDict()
+
+        if return_new_glyphs_only:
+            glyph_map_new = OrderedDict()
+        else:
+            glyph_map_new = glyph_map
+
+        xpositions = []
+        ypositions = []
+        glyph_ids = []
+        sizes = []
+
+        for font, fontsize, ccode, ox, oy in glyphs:
+            char_id = self._get_char_id(font, ccode)
+            if char_id not in glyph_map:
+                font.clear()
+                font.set_size(self.FONT_SCALE, self.DPI)
+                font.load_char(ccode, flags=LoadFlags.NO_HINTING)
+                glyph_map_new[char_id] = font.get_path()
+
+            xpositions.append(ox)
+            ypositions.append(oy)
+            glyph_ids.append(char_id)
+            size = fontsize / self.FONT_SCALE
+            sizes.append(size)
+
+        myrects = []
+        for ox, oy, w, h in rects:
+            vert1 = [(ox, oy), (ox, oy + h), (ox + w, oy + h),
+                     (ox + w, oy), (ox, oy), (0, 0)]
+            code1 = [Path.MOVETO,
+                     Path.LINETO, Path.LINETO, Path.LINETO, Path.LINETO,
+                     Path.CLOSEPOLY]
+            myrects.append((vert1, code1))
+
+        return (list(zip(glyph_ids, xpositions, ypositions, sizes)),
+                glyph_map_new, myrects)
+
+    def get_glyphs_tex(self, prop, s, glyph_map=None,
+                       return_new_glyphs_only=False):
+        """Convert the string *s* to vertices and codes using usetex mode."""
+        # Mostly borrowed from pdf backend.
+
+        dvifile = TexManager().make_dvi(s, self.FONT_SCALE)
+        with dviread.Dvi(dvifile, self.DPI) as dvi:
+            page, = dvi
+
+        if glyph_map is None:
+            glyph_map = OrderedDict()
+
+        if return_new_glyphs_only:
+            glyph_map_new = OrderedDict()
+        else:
+            glyph_map_new = glyph_map
+
+        glyph_ids, xpositions, ypositions, sizes = [], [], [], []
+
+        # Gather font information and do some setup for combining
+        # characters into strings.
+        for text in page.text:
+            font = get_font(text.font_path)
+            char_id = self._get_char_id(font, text.glyph)
+            if char_id not in glyph_map:
+                font.clear()
+                font.set_size(self.FONT_SCALE, self.DPI)
+                glyph_name_or_index = text.glyph_name_or_index
+                if isinstance(glyph_name_or_index, str):
+                    index = font.get_name_index(glyph_name_or_index)
+                    font.load_glyph(index, flags=LoadFlags.TARGET_LIGHT)
+                elif isinstance(glyph_name_or_index, int):
+                    self._select_native_charmap(font)
+                    font.load_char(
+                        glyph_name_or_index, flags=LoadFlags.TARGET_LIGHT)
+                else:  # Should not occur.
+                    raise TypeError(f"Glyph spec of unexpected type: "
+                                    f"{glyph_name_or_index!r}")
+                glyph_map_new[char_id] = font.get_path()
+
+            glyph_ids.append(char_id)
+            xpositions.append(text.x)
+            ypositions.append(text.y)
+            sizes.append(text.font_size / self.FONT_SCALE)
+
+        myrects = []
+
+        for ox, oy, h, w in page.boxes:
+            vert1 = [(ox, oy), (ox + w, oy), (ox + w, oy + h),
+                     (ox, oy + h), (ox, oy), (0, 0)]
+            code1 = [Path.MOVETO,
+                     Path.LINETO, Path.LINETO, Path.LINETO, Path.LINETO,
+                     Path.CLOSEPOLY]
+            myrects.append((vert1, code1))
+
+        return (list(zip(glyph_ids, xpositions, ypositions, sizes)),
+                glyph_map_new, myrects)
+
+    @staticmethod
+    def _select_native_charmap(font):
+        # Select the native charmap. (we can't directly identify it but it's
+        # typically an Adobe charmap).
+        for charmap_code in [
+                1094992451,  # ADOBE_CUSTOM.
+                1094995778,  # ADOBE_STANDARD.
+        ]:
+            try:
+                font.select_charmap(charmap_code)
+            except (ValueError, RuntimeError):
+                pass
+            else:
+                break
+        else:
+            _log.warning("No supported encoding in font (%s).", font.fname)
+
+
+text_to_path = TextToPath()
+
+
+class TextPath(Path):
+    """
+    Create a path from the text.
+    """
+
+    def __init__(self, xy, s, size=None, prop=None,
+                 _interpolation_steps=1, usetex=False):
+        r"""
+        Create a path from the text. Note that it simply is a path,
+        not an artist. You need to use the `.PathPatch` (or other artists)
+        to draw this path onto the canvas.
+
+        Parameters
+        ----------
+        xy : tuple or array of two float values
+            Position of the text. For no offset, use ``xy=(0, 0)``.
+
+        s : str
+            The text to convert to a path.
+
+        size : float, optional
+            Font size in points. Defaults to the size specified via the font
+            properties *prop*.
+
+        prop : `~matplotlib.font_manager.FontProperties`, optional
+            Font property. If not provided, will use a default
+            `.FontProperties` with parameters from the
+            :ref:`rcParams<customizing-with-dynamic-rc-settings>`.
+
+        _interpolation_steps : int, optional
+            (Currently ignored)
+
+        usetex : bool, default: False
+            Whether to use tex rendering.
+
+        Examples
+        --------
+        The following creates a path from the string "ABC" with Helvetica
+        font face; and another path from the latex fraction 1/2::
+
+            from matplotlib.text import TextPath
+            from matplotlib.font_manager import FontProperties
+
+            fp = FontProperties(family="Helvetica", style="italic")
+            path1 = TextPath((12, 12), "ABC", size=12, prop=fp)
+            path2 = TextPath((0, 0), r"$\frac{1}{2}$", size=12, usetex=True)
+
+        Also see :doc:`/gallery/text_labels_and_annotations/demo_text_path`.
+        """
+        # Circular import.
+        from matplotlib.text import Text
+
+        prop = FontProperties._from_any(prop)
+        if size is None:
+            size = prop.get_size_in_points()
+
+        self._xy = xy
+        self.set_size(size)
+
+        self._cached_vertices = None
+        s, ismath = Text(usetex=usetex)._preprocess_math(s)
+        super().__init__(
+            *text_to_path.get_text_path(prop, s, ismath=ismath),
+            _interpolation_steps=_interpolation_steps,
+            readonly=True)
+        self._should_simplify = False
+
+    def set_size(self, size):
+        """Set the text size."""
+        self._size = size
+        self._invalid = True
+
+    def get_size(self):
+        """Get the text size."""
+        return self._size
+
+    @property
+    def vertices(self):
+        """
+        Return the cached path after updating it if necessary.
+        """
+        self._revalidate_path()
+        return self._cached_vertices
+
+    @property
+    def codes(self):
+        """
+        Return the codes
+        """
+        return self._codes
+
+    def _revalidate_path(self):
+        """
+        Update the path if necessary.
+
+        The path for the text is initially create with the font size of
+        `.FONT_SCALE`, and this path is rescaled to other size when necessary.
+        """
+        if self._invalid or self._cached_vertices is None:
+            tr = (Affine2D()
+                  .scale(self._size / text_to_path.FONT_SCALE)
+                  .translate(*self._xy))
+            self._cached_vertices = tr.transform(self._vertices)
+            self._cached_vertices.flags.writeable = False
+            self._invalid = False
diff --git a/lib/python3.12/site-packages/matplotlib/ticker.py b/lib/python3.12/site-packages/matplotlib/ticker.py
new file mode 100644
index 0000000000000000000000000000000000000000..3d0059e5aca33923a167d8731de9285d5d24d833
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/ticker.py
@@ -0,0 +1,2990 @@
+"""
+Tick locating and formatting
+============================
+
+This module contains classes for configuring tick locating and formatting.
+Generic tick locators and formatters are provided, as well as domain specific
+custom ones.
+
+Although the locators know nothing about major or minor ticks, they are used
+by the Axis class to support major and minor tick locating and formatting.
+
+.. _tick_locating:
+.. _locators:
+
+Tick locating
+-------------
+
+The Locator class is the base class for all tick locators. The locators
+handle autoscaling of the view limits based on the data limits, and the
+choosing of tick locations. A useful semi-automatic tick locator is
+`MultipleLocator`. It is initialized with a base, e.g., 10, and it picks
+axis limits and ticks that are multiples of that base.
+
+The Locator subclasses defined here are:
+
+======================= =======================================================
+`AutoLocator`           `MaxNLocator` with simple defaults. This is the default
+                        tick locator for most plotting.
+`MaxNLocator`           Finds up to a max number of intervals with ticks at
+                        nice locations.
+`LinearLocator`         Space ticks evenly from min to max.
+`LogLocator`            Space ticks logarithmically from min to max.
+`MultipleLocator`       Ticks and range are a multiple of base; either integer
+                        or float.
+`FixedLocator`          Tick locations are fixed.
+`IndexLocator`          Locator for index plots (e.g., where
+                        ``x = range(len(y))``).
+`NullLocator`           No ticks.
+`SymmetricalLogLocator` Locator for use with the symlog norm; works like
+                        `LogLocator` for the part outside of the threshold and
+                        adds 0 if inside the limits.
+`AsinhLocator`          Locator for use with the asinh norm, attempting to
+                        space ticks approximately uniformly.
+`LogitLocator`          Locator for logit scaling.
+`AutoMinorLocator`      Locator for minor ticks when the axis is linear and the
+                        major ticks are uniformly spaced. Subdivides the major
+                        tick interval into a specified number of minor
+                        intervals, defaulting to 4 or 5 depending on the major
+                        interval.
+======================= =======================================================
+
+There are a number of locators specialized for date locations - see
+the :mod:`.dates` module.
+
+You can define your own locator by deriving from Locator. You must
+override the ``__call__`` method, which returns a sequence of locations,
+and you will probably want to override the autoscale method to set the
+view limits from the data limits.
+
+If you want to override the default locator, use one of the above or a custom
+locator and pass it to the x- or y-axis instance. The relevant methods are::
+
+  ax.xaxis.set_major_locator(xmajor_locator)
+  ax.xaxis.set_minor_locator(xminor_locator)
+  ax.yaxis.set_major_locator(ymajor_locator)
+  ax.yaxis.set_minor_locator(yminor_locator)
+
+The default minor locator is `NullLocator`, i.e., no minor ticks on by default.
+
+.. note::
+    `Locator` instances should not be used with more than one
+    `~matplotlib.axis.Axis` or `~matplotlib.axes.Axes`. So instead of::
+
+        locator = MultipleLocator(5)
+        ax.xaxis.set_major_locator(locator)
+        ax2.xaxis.set_major_locator(locator)
+
+    do the following instead::
+
+        ax.xaxis.set_major_locator(MultipleLocator(5))
+        ax2.xaxis.set_major_locator(MultipleLocator(5))
+
+.. _formatters:
+
+Tick formatting
+---------------
+
+Tick formatting is controlled by classes derived from Formatter. The formatter
+operates on a single tick value and returns a string to the axis.
+
+========================= =====================================================
+`NullFormatter`           No labels on the ticks.
+`FixedFormatter`          Set the strings manually for the labels.
+`FuncFormatter`           User defined function sets the labels.
+`StrMethodFormatter`      Use string `format` method.
+`FormatStrFormatter`      Use an old-style sprintf format string.
+`ScalarFormatter`         Default formatter for scalars: autopick the format
+                          string.
+`LogFormatter`            Formatter for log axes.
+`LogFormatterExponent`    Format values for log axis using
+                          ``exponent = log_base(value)``.
+`LogFormatterMathtext`    Format values for log axis using
+                          ``exponent = log_base(value)`` using Math text.
+`LogFormatterSciNotation` Format values for log axis using scientific notation.
+`LogitFormatter`          Probability formatter.
+`EngFormatter`            Format labels in engineering notation.
+`PercentFormatter`        Format labels as a percentage.
+========================= =====================================================
+
+You can derive your own formatter from the Formatter base class by
+simply overriding the ``__call__`` method. The formatter class has
+access to the axis view and data limits.
+
+To control the major and minor tick label formats, use one of the
+following methods::
+
+  ax.xaxis.set_major_formatter(xmajor_formatter)
+  ax.xaxis.set_minor_formatter(xminor_formatter)
+  ax.yaxis.set_major_formatter(ymajor_formatter)
+  ax.yaxis.set_minor_formatter(yminor_formatter)
+
+In addition to a `.Formatter` instance, `~.Axis.set_major_formatter` and
+`~.Axis.set_minor_formatter` also accept a ``str`` or function.  ``str`` input
+will be internally replaced with an autogenerated `.StrMethodFormatter` with
+the input ``str``. For function input, a `.FuncFormatter` with the input
+function will be generated and used.
+
+See :doc:`/gallery/ticks/major_minor_demo` for an example of setting major
+and minor ticks. See the :mod:`matplotlib.dates` module for more information
+and examples of using date locators and formatters.
+"""
+
+import itertools
+import logging
+import locale
+import math
+from numbers import Integral
+import string
+
+import numpy as np
+
+import matplotlib as mpl
+from matplotlib import _api, cbook
+from matplotlib import transforms as mtransforms
+
+_log = logging.getLogger(__name__)
+
+__all__ = ('TickHelper', 'Formatter', 'FixedFormatter',
+           'NullFormatter', 'FuncFormatter', 'FormatStrFormatter',
+           'StrMethodFormatter', 'ScalarFormatter', 'LogFormatter',
+           'LogFormatterExponent', 'LogFormatterMathtext',
+           'LogFormatterSciNotation',
+           'LogitFormatter', 'EngFormatter', 'PercentFormatter',
+           'Locator', 'IndexLocator', 'FixedLocator', 'NullLocator',
+           'LinearLocator', 'LogLocator', 'AutoLocator',
+           'MultipleLocator', 'MaxNLocator', 'AutoMinorLocator',
+           'SymmetricalLogLocator', 'AsinhLocator', 'LogitLocator')
+
+
+class _DummyAxis:
+    __name__ = "dummy"
+
+    def __init__(self, minpos=0):
+        self._data_interval = (0, 1)
+        self._view_interval = (0, 1)
+        self._minpos = minpos
+
+    def get_view_interval(self):
+        return self._view_interval
+
+    def set_view_interval(self, vmin, vmax):
+        self._view_interval = (vmin, vmax)
+
+    def get_minpos(self):
+        return self._minpos
+
+    def get_data_interval(self):
+        return self._data_interval
+
+    def set_data_interval(self, vmin, vmax):
+        self._data_interval = (vmin, vmax)
+
+    def get_tick_space(self):
+        # Just use the long-standing default of nbins==9
+        return 9
+
+
+class TickHelper:
+    axis = None
+
+    def set_axis(self, axis):
+        self.axis = axis
+
+    def create_dummy_axis(self, **kwargs):
+        if self.axis is None:
+            self.axis = _DummyAxis(**kwargs)
+
+
+class Formatter(TickHelper):
+    """
+    Create a string based on a tick value and location.
+    """
+    # some classes want to see all the locs to help format
+    # individual ones
+    locs = []
+
+    def __call__(self, x, pos=None):
+        """
+        Return the format for tick value *x* at position pos.
+        ``pos=None`` indicates an unspecified location.
+        """
+        raise NotImplementedError('Derived must override')
+
+    def format_ticks(self, values):
+        """Return the tick labels for all the ticks at once."""
+        self.set_locs(values)
+        return [self(value, i) for i, value in enumerate(values)]
+
+    def format_data(self, value):
+        """
+        Return the full string representation of the value with the
+        position unspecified.
+        """
+        return self.__call__(value)
+
+    def format_data_short(self, value):
+        """
+        Return a short string version of the tick value.
+
+        Defaults to the position-independent long value.
+        """
+        return self.format_data(value)
+
+    def get_offset(self):
+        return ''
+
+    def set_locs(self, locs):
+        """
+        Set the locations of the ticks.
+
+        This method is called before computing the tick labels because some
+        formatters need to know all tick locations to do so.
+        """
+        self.locs = locs
+
+    @staticmethod
+    def fix_minus(s):
+        """
+        Some classes may want to replace a hyphen for minus with the proper
+        Unicode symbol (U+2212) for typographical correctness.  This is a
+        helper method to perform such a replacement when it is enabled via
+        :rc:`axes.unicode_minus`.
+        """
+        return (s.replace('-', '\N{MINUS SIGN}')
+                if mpl.rcParams['axes.unicode_minus']
+                else s)
+
+    def _set_locator(self, locator):
+        """Subclasses may want to override this to set a locator."""
+        pass
+
+
+class NullFormatter(Formatter):
+    """Always return the empty string."""
+
+    def __call__(self, x, pos=None):
+        # docstring inherited
+        return ''
+
+
+class FixedFormatter(Formatter):
+    """
+    Return fixed strings for tick labels based only on position, not value.
+
+    .. note::
+        `.FixedFormatter` should only be used together with `.FixedLocator`.
+        Otherwise, the labels may end up in unexpected positions.
+    """
+
+    def __init__(self, seq):
+        """Set the sequence *seq* of strings that will be used for labels."""
+        self.seq = seq
+        self.offset_string = ''
+
+    def __call__(self, x, pos=None):
+        """
+        Return the label that matches the position, regardless of the value.
+
+        For positions ``pos < len(seq)``, return ``seq[i]`` regardless of
+        *x*. Otherwise return empty string. ``seq`` is the sequence of
+        strings that this object was initialized with.
+        """
+        if pos is None or pos >= len(self.seq):
+            return ''
+        else:
+            return self.seq[pos]
+
+    def get_offset(self):
+        return self.offset_string
+
+    def set_offset_string(self, ofs):
+        self.offset_string = ofs
+
+
+class FuncFormatter(Formatter):
+    """
+    Use a user-defined function for formatting.
+
+    The function should take in two inputs (a tick value ``x`` and a
+    position ``pos``), and return a string containing the corresponding
+    tick label.
+    """
+
+    def __init__(self, func):
+        self.func = func
+        self.offset_string = ""
+
+    def __call__(self, x, pos=None):
+        """
+        Return the value of the user defined function.
+
+        *x* and *pos* are passed through as-is.
+        """
+        return self.func(x, pos)
+
+    def get_offset(self):
+        return self.offset_string
+
+    def set_offset_string(self, ofs):
+        self.offset_string = ofs
+
+
+class FormatStrFormatter(Formatter):
+    """
+    Use an old-style ('%' operator) format string to format the tick.
+
+    The format string should have a single variable format (%) in it.
+    It will be applied to the value (not the position) of the tick.
+
+    Negative numeric values (e.g., -1) will use a dash, not a Unicode minus;
+    use mathtext to get a Unicode minus by wrapping the format specifier with $
+    (e.g. "$%g$").
+    """
+
+    def __init__(self, fmt):
+        self.fmt = fmt
+
+    def __call__(self, x, pos=None):
+        """
+        Return the formatted label string.
+
+        Only the value *x* is formatted. The position is ignored.
+        """
+        return self.fmt % x
+
+
+class _UnicodeMinusFormat(string.Formatter):
+    """
+    A specialized string formatter so that `.StrMethodFormatter` respects
+    :rc:`axes.unicode_minus`.  This implementation relies on the fact that the
+    format string is only ever called with kwargs *x* and *pos*, so it blindly
+    replaces dashes by unicode minuses without further checking.
+    """
+
+    def format_field(self, value, format_spec):
+        return Formatter.fix_minus(super().format_field(value, format_spec))
+
+
+class StrMethodFormatter(Formatter):
+    """
+    Use a new-style format string (as used by `str.format`) to format the tick.
+
+    The field used for the tick value must be labeled *x* and the field used
+    for the tick position must be labeled *pos*.
+
+    The formatter will respect :rc:`axes.unicode_minus` when formatting
+    negative numeric values.
+
+    It is typically unnecessary to explicitly construct `.StrMethodFormatter`
+    objects, as `~.Axis.set_major_formatter` directly accepts the format string
+    itself.
+    """
+
+    def __init__(self, fmt):
+        self.fmt = fmt
+
+    def __call__(self, x, pos=None):
+        """
+        Return the formatted label string.
+
+        *x* and *pos* are passed to `str.format` as keyword arguments
+        with those exact names.
+        """
+        return _UnicodeMinusFormat().format(self.fmt, x=x, pos=pos)
+
+
+class ScalarFormatter(Formatter):
+    """
+    Format tick values as a number.
+
+    Parameters
+    ----------
+    useOffset : bool or float, default: :rc:`axes.formatter.useoffset`
+        Whether to use offset notation. See `.set_useOffset`.
+    useMathText : bool, default: :rc:`axes.formatter.use_mathtext`
+        Whether to use fancy math formatting. See `.set_useMathText`.
+    useLocale : bool, default: :rc:`axes.formatter.use_locale`.
+        Whether to use locale settings for decimal sign and positive sign.
+        See `.set_useLocale`.
+    usetex : bool, default: :rc:`text.usetex`
+        To enable/disable the use of TeX's math mode for rendering the
+        numbers in the formatter.
+
+        .. versionadded:: 3.10
+
+    Notes
+    -----
+    In addition to the parameters above, the formatting of scientific vs.
+    floating point representation can be configured via `.set_scientific`
+    and `.set_powerlimits`).
+
+    **Offset notation and scientific notation**
+
+    Offset notation and scientific notation look quite similar at first sight.
+    Both split some information from the formatted tick values and display it
+    at the end of the axis.
+
+    - The scientific notation splits up the order of magnitude, i.e. a
+      multiplicative scaling factor, e.g. ``1e6``.
+
+    - The offset notation separates an additive constant, e.g. ``+1e6``. The
+      offset notation label is always prefixed with a ``+`` or ``-`` sign
+      and is thus distinguishable from the order of magnitude label.
+
+    The following plot with x limits ``1_000_000`` to ``1_000_010`` illustrates
+    the different formatting. Note the labels at the right edge of the x axis.
+
+    .. plot::
+
+        lim = (1_000_000, 1_000_010)
+
+        fig, (ax1, ax2, ax3) = plt.subplots(3, 1, gridspec_kw={'hspace': 2})
+        ax1.set(title='offset notation', xlim=lim)
+        ax2.set(title='scientific notation', xlim=lim)
+        ax2.xaxis.get_major_formatter().set_useOffset(False)
+        ax3.set(title='floating-point notation', xlim=lim)
+        ax3.xaxis.get_major_formatter().set_useOffset(False)
+        ax3.xaxis.get_major_formatter().set_scientific(False)
+
+    """
+
+    def __init__(self, useOffset=None, useMathText=None, useLocale=None, *,
+                 usetex=None):
+        if useOffset is None:
+            useOffset = mpl.rcParams['axes.formatter.useoffset']
+        self._offset_threshold = \
+            mpl.rcParams['axes.formatter.offset_threshold']
+        self.set_useOffset(useOffset)
+        self.set_usetex(usetex)
+        self.set_useMathText(useMathText)
+        self.orderOfMagnitude = 0
+        self.format = ''
+        self._scientific = True
+        self._powerlimits = mpl.rcParams['axes.formatter.limits']
+        self.set_useLocale(useLocale)
+
+    def get_usetex(self):
+        """Return whether TeX's math mode is enabled for rendering."""
+        return self._usetex
+
+    def set_usetex(self, val):
+        """Set whether to use TeX's math mode for rendering numbers in the formatter."""
+        self._usetex = mpl._val_or_rc(val, 'text.usetex')
+
+    usetex = property(fget=get_usetex, fset=set_usetex)
+
+    def get_useOffset(self):
+        """
+        Return whether automatic mode for offset notation is active.
+
+        This returns True if ``set_useOffset(True)``; it returns False if an
+        explicit offset was set, e.g. ``set_useOffset(1000)``.
+
+        See Also
+        --------
+        ScalarFormatter.set_useOffset
+        """
+        return self._useOffset
+
+    def set_useOffset(self, val):
+        """
+        Set whether to use offset notation.
+
+        When formatting a set numbers whose value is large compared to their
+        range, the formatter can separate an additive constant. This can
+        shorten the formatted numbers so that they are less likely to overlap
+        when drawn on an axis.
+
+        Parameters
+        ----------
+        val : bool or float
+            - If False, do not use offset notation.
+            - If True (=automatic mode), use offset notation if it can make
+              the residual numbers significantly shorter. The exact behavior
+              is controlled by :rc:`axes.formatter.offset_threshold`.
+            - If a number, force an offset of the given value.
+
+        Examples
+        --------
+        With active offset notation, the values
+
+        ``100_000, 100_002, 100_004, 100_006, 100_008``
+
+        will be formatted as ``0, 2, 4, 6, 8`` plus an offset ``+1e5``, which
+        is written to the edge of the axis.
+        """
+        if val in [True, False]:
+            self.offset = 0
+            self._useOffset = val
+        else:
+            self._useOffset = False
+            self.offset = val
+
+    useOffset = property(fget=get_useOffset, fset=set_useOffset)
+
+    def get_useLocale(self):
+        """
+        Return whether locale settings are used for formatting.
+
+        See Also
+        --------
+        ScalarFormatter.set_useLocale
+        """
+        return self._useLocale
+
+    def set_useLocale(self, val):
+        """
+        Set whether to use locale settings for decimal sign and positive sign.
+
+        Parameters
+        ----------
+        val : bool or None
+            *None* resets to :rc:`axes.formatter.use_locale`.
+        """
+        if val is None:
+            self._useLocale = mpl.rcParams['axes.formatter.use_locale']
+        else:
+            self._useLocale = val
+
+    useLocale = property(fget=get_useLocale, fset=set_useLocale)
+
+    def _format_maybe_minus_and_locale(self, fmt, arg):
+        """
+        Format *arg* with *fmt*, applying Unicode minus and locale if desired.
+        """
+        return self.fix_minus(
+                # Escape commas introduced by locale.format_string if using math text,
+                # but not those present from the beginning in fmt.
+                (",".join(locale.format_string(part, (arg,), True).replace(",", "{,}")
+                          for part in fmt.split(",")) if self._useMathText
+                 else locale.format_string(fmt, (arg,), True))
+                if self._useLocale
+                else fmt % arg)
+
+    def get_useMathText(self):
+        """
+        Return whether to use fancy math formatting.
+
+        See Also
+        --------
+        ScalarFormatter.set_useMathText
+        """
+        return self._useMathText
+
+    def set_useMathText(self, val):
+        r"""
+        Set whether to use fancy math formatting.
+
+        If active, scientific notation is formatted as :math:`1.2 \times 10^3`.
+
+        Parameters
+        ----------
+        val : bool or None
+            *None* resets to :rc:`axes.formatter.use_mathtext`.
+        """
+        if val is None:
+            self._useMathText = mpl.rcParams['axes.formatter.use_mathtext']
+            if self._useMathText is False:
+                try:
+                    from matplotlib import font_manager
+                    ufont = font_manager.findfont(
+                        font_manager.FontProperties(
+                            family=mpl.rcParams["font.family"]
+                        ),
+                        fallback_to_default=False,
+                    )
+                except ValueError:
+                    ufont = None
+
+                if ufont == str(cbook._get_data_path("fonts/ttf/cmr10.ttf")):
+                    _api.warn_external(
+                        "cmr10 font should ideally be used with "
+                        "mathtext, set axes.formatter.use_mathtext to True"
+                    )
+        else:
+            self._useMathText = val
+
+    useMathText = property(fget=get_useMathText, fset=set_useMathText)
+
+    def __call__(self, x, pos=None):
+        """
+        Return the format for tick value *x* at position *pos*.
+        """
+        if len(self.locs) == 0:
+            return ''
+        else:
+            xp = (x - self.offset) / (10. ** self.orderOfMagnitude)
+            if abs(xp) < 1e-8:
+                xp = 0
+            return self._format_maybe_minus_and_locale(self.format, xp)
+
+    def set_scientific(self, b):
+        """
+        Turn scientific notation on or off.
+
+        See Also
+        --------
+        ScalarFormatter.set_powerlimits
+        """
+        self._scientific = bool(b)
+
+    def set_powerlimits(self, lims):
+        r"""
+        Set size thresholds for scientific notation.
+
+        Parameters
+        ----------
+        lims : (int, int)
+            A tuple *(min_exp, max_exp)* containing the powers of 10 that
+            determine the switchover threshold. For a number representable as
+            :math:`a \times 10^\mathrm{exp}` with :math:`1 <= |a| < 10`,
+            scientific notation will be used if ``exp <= min_exp`` or
+            ``exp >= max_exp``.
+
+            The default limits are controlled by :rc:`axes.formatter.limits`.
+
+            In particular numbers with *exp* equal to the thresholds are
+            written in scientific notation.
+
+            Typically, *min_exp* will be negative and *max_exp* will be
+            positive.
+
+            For example, ``formatter.set_powerlimits((-3, 4))`` will provide
+            the following formatting:
+            :math:`1 \times 10^{-3}, 9.9 \times 10^{-3}, 0.01,`
+            :math:`9999, 1 \times 10^4`.
+
+        See Also
+        --------
+        ScalarFormatter.set_scientific
+        """
+        if len(lims) != 2:
+            raise ValueError("'lims' must be a sequence of length 2")
+        self._powerlimits = lims
+
+    def format_data_short(self, value):
+        # docstring inherited
+        if value is np.ma.masked:
+            return ""
+        if isinstance(value, Integral):
+            fmt = "%d"
+        else:
+            if getattr(self.axis, "__name__", "") in ["xaxis", "yaxis"]:
+                if self.axis.__name__ == "xaxis":
+                    axis_trf = self.axis.axes.get_xaxis_transform()
+                    axis_inv_trf = axis_trf.inverted()
+                    screen_xy = axis_trf.transform((value, 0))
+                    neighbor_values = axis_inv_trf.transform(
+                        screen_xy + [[-1, 0], [+1, 0]])[:, 0]
+                else:  # yaxis:
+                    axis_trf = self.axis.axes.get_yaxis_transform()
+                    axis_inv_trf = axis_trf.inverted()
+                    screen_xy = axis_trf.transform((0, value))
+                    neighbor_values = axis_inv_trf.transform(
+                        screen_xy + [[0, -1], [0, +1]])[:, 1]
+                delta = abs(neighbor_values - value).max()
+            else:
+                # Rough approximation: no more than 1e4 divisions.
+                a, b = self.axis.get_view_interval()
+                delta = (b - a) / 1e4
+            fmt = f"%-#.{cbook._g_sig_digits(value, delta)}g"
+        return self._format_maybe_minus_and_locale(fmt, value)
+
+    def format_data(self, value):
+        # docstring inherited
+        e = math.floor(math.log10(abs(value)))
+        s = round(value / 10**e, 10)
+        significand = self._format_maybe_minus_and_locale(
+            "%d" if s % 1 == 0 else "%1.10g", s)
+        if e == 0:
+            return significand
+        exponent = self._format_maybe_minus_and_locale("%d", e)
+        if self._useMathText or self._usetex:
+            exponent = "10^{%s}" % exponent
+            return (exponent if s == 1  # reformat 1x10^y as 10^y
+                    else rf"{significand} \times {exponent}")
+        else:
+            return f"{significand}e{exponent}"
+
+    def get_offset(self):
+        """
+        Return scientific notation, plus offset.
+        """
+        if len(self.locs) == 0:
+            return ''
+        if self.orderOfMagnitude or self.offset:
+            offsetStr = ''
+            sciNotStr = ''
+            if self.offset:
+                offsetStr = self.format_data(self.offset)
+                if self.offset > 0:
+                    offsetStr = '+' + offsetStr
+            if self.orderOfMagnitude:
+                if self._usetex or self._useMathText:
+                    sciNotStr = self.format_data(10 ** self.orderOfMagnitude)
+                else:
+                    sciNotStr = '1e%d' % self.orderOfMagnitude
+            if self._useMathText or self._usetex:
+                if sciNotStr != '':
+                    sciNotStr = r'\times\mathdefault{%s}' % sciNotStr
+                s = fr'${sciNotStr}\mathdefault{{{offsetStr}}}$'
+            else:
+                s = ''.join((sciNotStr, offsetStr))
+            return self.fix_minus(s)
+        return ''
+
+    def set_locs(self, locs):
+        # docstring inherited
+        self.locs = locs
+        if len(self.locs) > 0:
+            if self._useOffset:
+                self._compute_offset()
+            self._set_order_of_magnitude()
+            self._set_format()
+
+    def _compute_offset(self):
+        locs = self.locs
+        # Restrict to visible ticks.
+        vmin, vmax = sorted(self.axis.get_view_interval())
+        locs = np.asarray(locs)
+        locs = locs[(vmin <= locs) & (locs <= vmax)]
+        if not len(locs):
+            self.offset = 0
+            return
+        lmin, lmax = locs.min(), locs.max()
+        # Only use offset if there are at least two ticks and every tick has
+        # the same sign.
+        if lmin == lmax or lmin <= 0 <= lmax:
+            self.offset = 0
+            return
+        # min, max comparing absolute values (we want division to round towards
+        # zero so we work on absolute values).
+        abs_min, abs_max = sorted([abs(float(lmin)), abs(float(lmax))])
+        sign = math.copysign(1, lmin)
+        # What is the smallest power of ten such that abs_min and abs_max are
+        # equal up to that precision?
+        # Note: Internally using oom instead of 10 ** oom avoids some numerical
+        # accuracy issues.
+        oom_max = np.ceil(math.log10(abs_max))
+        oom = 1 + next(oom for oom in itertools.count(oom_max, -1)
+                       if abs_min // 10 ** oom != abs_max // 10 ** oom)
+        if (abs_max - abs_min) / 10 ** oom <= 1e-2:
+            # Handle the case of straddling a multiple of a large power of ten
+            # (relative to the span).
+            # What is the smallest power of ten such that abs_min and abs_max
+            # are no more than 1 apart at that precision?
+            oom = 1 + next(oom for oom in itertools.count(oom_max, -1)
+                           if abs_max // 10 ** oom - abs_min // 10 ** oom > 1)
+        # Only use offset if it saves at least _offset_threshold digits.
+        n = self._offset_threshold - 1
+        self.offset = (sign * (abs_max // 10 ** oom) * 10 ** oom
+                       if abs_max // 10 ** oom >= 10**n
+                       else 0)
+
+    def _set_order_of_magnitude(self):
+        # if scientific notation is to be used, find the appropriate exponent
+        # if using a numerical offset, find the exponent after applying the
+        # offset. When lower power limit = upper <> 0, use provided exponent.
+        if not self._scientific:
+            self.orderOfMagnitude = 0
+            return
+        if self._powerlimits[0] == self._powerlimits[1] != 0:
+            # fixed scaling when lower power limit = upper <> 0.
+            self.orderOfMagnitude = self._powerlimits[0]
+            return
+        # restrict to visible ticks
+        vmin, vmax = sorted(self.axis.get_view_interval())
+        locs = np.asarray(self.locs)
+        locs = locs[(vmin <= locs) & (locs <= vmax)]
+        locs = np.abs(locs)
+        if not len(locs):
+            self.orderOfMagnitude = 0
+            return
+        if self.offset:
+            oom = math.floor(math.log10(vmax - vmin))
+        else:
+            val = locs.max()
+            if val == 0:
+                oom = 0
+            else:
+                oom = math.floor(math.log10(val))
+        if oom <= self._powerlimits[0]:
+            self.orderOfMagnitude = oom
+        elif oom >= self._powerlimits[1]:
+            self.orderOfMagnitude = oom
+        else:
+            self.orderOfMagnitude = 0
+
+    def _set_format(self):
+        # set the format string to format all the ticklabels
+        if len(self.locs) < 2:
+            # Temporarily augment the locations with the axis end points.
+            _locs = [*self.locs, *self.axis.get_view_interval()]
+        else:
+            _locs = self.locs
+        locs = (np.asarray(_locs) - self.offset) / 10. ** self.orderOfMagnitude
+        loc_range = np.ptp(locs)
+        # Curvilinear coordinates can yield two identical points.
+        if loc_range == 0:
+            loc_range = np.max(np.abs(locs))
+        # Both points might be zero.
+        if loc_range == 0:
+            loc_range = 1
+        if len(self.locs) < 2:
+            # We needed the end points only for the loc_range calculation.
+            locs = locs[:-2]
+        loc_range_oom = int(math.floor(math.log10(loc_range)))
+        # first estimate:
+        sigfigs = max(0, 3 - loc_range_oom)
+        # refined estimate:
+        thresh = 1e-3 * 10 ** loc_range_oom
+        while sigfigs >= 0:
+            if np.abs(locs - np.round(locs, decimals=sigfigs)).max() < thresh:
+                sigfigs -= 1
+            else:
+                break
+        sigfigs += 1
+        self.format = f'%1.{sigfigs}f'
+        if self._usetex or self._useMathText:
+            self.format = r'$\mathdefault{%s}$' % self.format
+
+
+class LogFormatter(Formatter):
+    """
+    Base class for formatting ticks on a log or symlog scale.
+
+    It may be instantiated directly, or subclassed.
+
+    Parameters
+    ----------
+    base : float, default: 10.
+        Base of the logarithm used in all calculations.
+
+    labelOnlyBase : bool, default: False
+        If True, label ticks only at integer powers of base.
+        This is normally True for major ticks and False for
+        minor ticks.
+
+    minor_thresholds : (subset, all), default: (1, 0.4)
+        If labelOnlyBase is False, these two numbers control
+        the labeling of ticks that are not at integer powers of
+        base; normally these are the minor ticks. The controlling
+        parameter is the log of the axis data range.  In the typical
+        case where base is 10 it is the number of decades spanned
+        by the axis, so we can call it 'numdec'. If ``numdec <= all``,
+        all minor ticks will be labeled.  If ``all < numdec <= subset``,
+        then only a subset of minor ticks will be labeled, so as to
+        avoid crowding. If ``numdec > subset`` then no minor ticks will
+        be labeled.
+
+    linthresh : None or float, default: None
+        If a symmetric log scale is in use, its ``linthresh``
+        parameter must be supplied here.
+
+    Notes
+    -----
+    The `set_locs` method must be called to enable the subsetting
+    logic controlled by the ``minor_thresholds`` parameter.
+
+    In some cases such as the colorbar, there is no distinction between
+    major and minor ticks; the tick locations might be set manually,
+    or by a locator that puts ticks at integer powers of base and
+    at intermediate locations.  For this situation, disable the
+    minor_thresholds logic by using ``minor_thresholds=(np.inf, np.inf)``,
+    so that all ticks will be labeled.
+
+    To disable labeling of minor ticks when 'labelOnlyBase' is False,
+    use ``minor_thresholds=(0, 0)``.  This is the default for the
+    "classic" style.
+
+    Examples
+    --------
+    To label a subset of minor ticks when the view limits span up
+    to 2 decades, and all of the ticks when zoomed in to 0.5 decades
+    or less, use ``minor_thresholds=(2, 0.5)``.
+
+    To label all minor ticks when the view limits span up to 1.5
+    decades, use ``minor_thresholds=(1.5, 1.5)``.
+    """
+
+    def __init__(self, base=10.0, labelOnlyBase=False,
+                 minor_thresholds=None,
+                 linthresh=None):
+
+        self.set_base(base)
+        self.set_label_minor(labelOnlyBase)
+        if minor_thresholds is None:
+            if mpl.rcParams['_internal.classic_mode']:
+                minor_thresholds = (0, 0)
+            else:
+                minor_thresholds = (1, 0.4)
+        self.minor_thresholds = minor_thresholds
+        self._sublabels = None
+        self._linthresh = linthresh
+
+    def set_base(self, base):
+        """
+        Change the *base* for labeling.
+
+        .. warning::
+           Should always match the base used for :class:`LogLocator`
+        """
+        self._base = float(base)
+
+    def set_label_minor(self, labelOnlyBase):
+        """
+        Switch minor tick labeling on or off.
+
+        Parameters
+        ----------
+        labelOnlyBase : bool
+            If True, label ticks only at integer powers of base.
+        """
+        self.labelOnlyBase = labelOnlyBase
+
+    def set_locs(self, locs=None):
+        """
+        Use axis view limits to control which ticks are labeled.
+
+        The *locs* parameter is ignored in the present algorithm.
+        """
+        if np.isinf(self.minor_thresholds[0]):
+            self._sublabels = None
+            return
+
+        # Handle symlog case:
+        linthresh = self._linthresh
+        if linthresh is None:
+            try:
+                linthresh = self.axis.get_transform().linthresh
+            except AttributeError:
+                pass
+
+        vmin, vmax = self.axis.get_view_interval()
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+
+        if linthresh is None and vmin <= 0:
+            # It's probably a colorbar with
+            # a format kwarg setting a LogFormatter in the manner
+            # that worked with 1.5.x, but that doesn't work now.
+            self._sublabels = {1}  # label powers of base
+            return
+
+        b = self._base
+        if linthresh is not None:  # symlog
+            # Only compute the number of decades in the logarithmic part of the
+            # axis
+            numdec = 0
+            if vmin < -linthresh:
+                rhs = min(vmax, -linthresh)
+                numdec += math.log(vmin / rhs) / math.log(b)
+            if vmax > linthresh:
+                lhs = max(vmin, linthresh)
+                numdec += math.log(vmax / lhs) / math.log(b)
+        else:
+            vmin = math.log(vmin) / math.log(b)
+            vmax = math.log(vmax) / math.log(b)
+            numdec = abs(vmax - vmin)
+
+        if numdec > self.minor_thresholds[0]:
+            # Label only bases
+            self._sublabels = {1}
+        elif numdec > self.minor_thresholds[1]:
+            # Add labels between bases at log-spaced coefficients;
+            # include base powers in case the locations include
+            # "major" and "minor" points, as in colorbar.
+            c = np.geomspace(1, b, int(b)//2 + 1)
+            self._sublabels = set(np.round(c))
+            # For base 10, this yields (1, 2, 3, 4, 6, 10).
+        else:
+            # Label all integer multiples of base**n.
+            self._sublabels = set(np.arange(1, b + 1))
+
+    def _num_to_string(self, x, vmin, vmax):
+        return self._pprint_val(x, vmax - vmin) if 1 <= x <= 10000 else f"{x:1.0e}"
+
+    def __call__(self, x, pos=None):
+        # docstring inherited
+        if x == 0.0:  # Symlog
+            return '0'
+
+        x = abs(x)
+        b = self._base
+        # only label the decades
+        fx = math.log(x) / math.log(b)
+        is_x_decade = _is_close_to_int(fx)
+        exponent = round(fx) if is_x_decade else np.floor(fx)
+        coeff = round(b ** (fx - exponent))
+
+        if self.labelOnlyBase and not is_x_decade:
+            return ''
+        if self._sublabels is not None and coeff not in self._sublabels:
+            return ''
+
+        vmin, vmax = self.axis.get_view_interval()
+        vmin, vmax = mtransforms.nonsingular(vmin, vmax, expander=0.05)
+        s = self._num_to_string(x, vmin, vmax)
+        return self.fix_minus(s)
+
+    def format_data(self, value):
+        with cbook._setattr_cm(self, labelOnlyBase=False):
+            return cbook.strip_math(self.__call__(value))
+
+    def format_data_short(self, value):
+        # docstring inherited
+        return ('%-12g' % value).rstrip()
+
+    def _pprint_val(self, x, d):
+        # If the number is not too big and it's an int, format it as an int.
+        if abs(x) < 1e4 and x == int(x):
+            return '%d' % x
+        fmt = ('%1.3e' if d < 1e-2 else
+               '%1.3f' if d <= 1 else
+               '%1.2f' if d <= 10 else
+               '%1.1f' if d <= 1e5 else
+               '%1.1e')
+        s = fmt % x
+        tup = s.split('e')
+        if len(tup) == 2:
+            mantissa = tup[0].rstrip('0').rstrip('.')
+            exponent = int(tup[1])
+            if exponent:
+                s = '%se%d' % (mantissa, exponent)
+            else:
+                s = mantissa
+        else:
+            s = s.rstrip('0').rstrip('.')
+        return s
+
+
+class LogFormatterExponent(LogFormatter):
+    """
+    Format values for log axis using ``exponent = log_base(value)``.
+    """
+
+    def _num_to_string(self, x, vmin, vmax):
+        fx = math.log(x) / math.log(self._base)
+        if 1 <= abs(fx) <= 10000:
+            fd = math.log(vmax - vmin) / math.log(self._base)
+            s = self._pprint_val(fx, fd)
+        else:
+            s = f"{fx:1.0g}"
+        return s
+
+
+class LogFormatterMathtext(LogFormatter):
+    """
+    Format values for log axis using ``exponent = log_base(value)``.
+    """
+
+    def _non_decade_format(self, sign_string, base, fx, usetex):
+        """Return string for non-decade locations."""
+        return r'$\mathdefault{%s%s^{%.2f}}$' % (sign_string, base, fx)
+
+    def __call__(self, x, pos=None):
+        # docstring inherited
+        if x == 0:  # Symlog
+            return r'$\mathdefault{0}$'
+
+        sign_string = '-' if x < 0 else ''
+        x = abs(x)
+        b = self._base
+
+        # only label the decades
+        fx = math.log(x) / math.log(b)
+        is_x_decade = _is_close_to_int(fx)
+        exponent = round(fx) if is_x_decade else np.floor(fx)
+        coeff = round(b ** (fx - exponent))
+
+        if self.labelOnlyBase and not is_x_decade:
+            return ''
+        if self._sublabels is not None and coeff not in self._sublabels:
+            return ''
+
+        if is_x_decade:
+            fx = round(fx)
+
+        # use string formatting of the base if it is not an integer
+        if b % 1 == 0.0:
+            base = '%d' % b
+        else:
+            base = '%s' % b
+
+        if abs(fx) < mpl.rcParams['axes.formatter.min_exponent']:
+            return r'$\mathdefault{%s%g}$' % (sign_string, x)
+        elif not is_x_decade:
+            usetex = mpl.rcParams['text.usetex']
+            return self._non_decade_format(sign_string, base, fx, usetex)
+        else:
+            return r'$\mathdefault{%s%s^{%d}}$' % (sign_string, base, fx)
+
+
+class LogFormatterSciNotation(LogFormatterMathtext):
+    """
+    Format values following scientific notation in a logarithmic axis.
+    """
+
+    def _non_decade_format(self, sign_string, base, fx, usetex):
+        """Return string for non-decade locations."""
+        b = float(base)
+        exponent = math.floor(fx)
+        coeff = b ** (fx - exponent)
+        if _is_close_to_int(coeff):
+            coeff = round(coeff)
+        return r'$\mathdefault{%s%g\times%s^{%d}}$' \
+            % (sign_string, coeff, base, exponent)
+
+
+class LogitFormatter(Formatter):
+    """
+    Probability formatter (using Math text).
+    """
+
+    def __init__(
+        self,
+        *,
+        use_overline=False,
+        one_half=r"\frac{1}{2}",
+        minor=False,
+        minor_threshold=25,
+        minor_number=6,
+    ):
+        r"""
+        Parameters
+        ----------
+        use_overline : bool, default: False
+            If x > 1/2, with x = 1 - v, indicate if x should be displayed as
+            $\overline{v}$. The default is to display $1 - v$.
+
+        one_half : str, default: r"\\frac{1}{2}"
+            The string used to represent 1/2.
+
+        minor : bool, default: False
+            Indicate if the formatter is formatting minor ticks or not.
+            Basically minor ticks are not labelled, except when only few ticks
+            are provided, ticks with most space with neighbor ticks are
+            labelled. See other parameters to change the default behavior.
+
+        minor_threshold : int, default: 25
+            Maximum number of locs for labelling some minor ticks. This
+            parameter have no effect if minor is False.
+
+        minor_number : int, default: 6
+            Number of ticks which are labelled when the number of ticks is
+            below the threshold.
+        """
+        self._use_overline = use_overline
+        self._one_half = one_half
+        self._minor = minor
+        self._labelled = set()
+        self._minor_threshold = minor_threshold
+        self._minor_number = minor_number
+
+    def use_overline(self, use_overline):
+        r"""
+        Switch display mode with overline for labelling p>1/2.
+
+        Parameters
+        ----------
+        use_overline : bool
+            If x > 1/2, with x = 1 - v, indicate if x should be displayed as
+            $\overline{v}$. The default is to display $1 - v$.
+        """
+        self._use_overline = use_overline
+
+    def set_one_half(self, one_half):
+        r"""
+        Set the way one half is displayed.
+
+        one_half : str
+            The string used to represent 1/2.
+        """
+        self._one_half = one_half
+
+    def set_minor_threshold(self, minor_threshold):
+        """
+        Set the threshold for labelling minors ticks.
+
+        Parameters
+        ----------
+        minor_threshold : int
+            Maximum number of locations for labelling some minor ticks. This
+            parameter have no effect if minor is False.
+        """
+        self._minor_threshold = minor_threshold
+
+    def set_minor_number(self, minor_number):
+        """
+        Set the number of minor ticks to label when some minor ticks are
+        labelled.
+
+        Parameters
+        ----------
+        minor_number : int
+            Number of ticks which are labelled when the number of ticks is
+            below the threshold.
+        """
+        self._minor_number = minor_number
+
+    def set_locs(self, locs):
+        self.locs = np.array(locs)
+        self._labelled.clear()
+
+        if not self._minor:
+            return None
+        if all(
+            _is_decade(x, rtol=1e-7)
+            or _is_decade(1 - x, rtol=1e-7)
+            or (_is_close_to_int(2 * x) and
+                int(np.round(2 * x)) == 1)
+            for x in locs
+        ):
+            # minor ticks are subsample from ideal, so no label
+            return None
+        if len(locs) < self._minor_threshold:
+            if len(locs) < self._minor_number:
+                self._labelled.update(locs)
+            else:
+                # we do not have a lot of minor ticks, so only few decades are
+                # displayed, then we choose some (spaced) minor ticks to label.
+                # Only minor ticks are known, we assume it is sufficient to
+                # choice which ticks are displayed.
+                # For each ticks we compute the distance between the ticks and
+                # the previous, and between the ticks and the next one. Ticks
+                # with smallest minimum are chosen. As tiebreak, the ticks
+                # with smallest sum is chosen.
+                diff = np.diff(-np.log(1 / self.locs - 1))
+                space_pessimistic = np.minimum(
+                    np.concatenate(((np.inf,), diff)),
+                    np.concatenate((diff, (np.inf,))),
+                )
+                space_sum = (
+                    np.concatenate(((0,), diff))
+                    + np.concatenate((diff, (0,)))
+                )
+                good_minor = sorted(
+                    range(len(self.locs)),
+                    key=lambda i: (space_pessimistic[i], space_sum[i]),
+                )[-self._minor_number:]
+                self._labelled.update(locs[i] for i in good_minor)
+
+    def _format_value(self, x, locs, sci_notation=True):
+        if sci_notation:
+            exponent = math.floor(np.log10(x))
+            min_precision = 0
+        else:
+            exponent = 0
+            min_precision = 1
+        value = x * 10 ** (-exponent)
+        if len(locs) < 2:
+            precision = min_precision
+        else:
+            diff = np.sort(np.abs(locs - x))[1]
+            precision = -np.log10(diff) + exponent
+            precision = (
+                int(np.round(precision))
+                if _is_close_to_int(precision)
+                else math.ceil(precision)
+            )
+            if precision < min_precision:
+                precision = min_precision
+        mantissa = r"%.*f" % (precision, value)
+        if not sci_notation:
+            return mantissa
+        s = r"%s\cdot10^{%d}" % (mantissa, exponent)
+        return s
+
+    def _one_minus(self, s):
+        if self._use_overline:
+            return r"\overline{%s}" % s
+        else:
+            return f"1-{s}"
+
+    def __call__(self, x, pos=None):
+        if self._minor and x not in self._labelled:
+            return ""
+        if x <= 0 or x >= 1:
+            return ""
+        if _is_close_to_int(2 * x) and round(2 * x) == 1:
+            s = self._one_half
+        elif x < 0.5 and _is_decade(x, rtol=1e-7):
+            exponent = round(math.log10(x))
+            s = "10^{%d}" % exponent
+        elif x > 0.5 and _is_decade(1 - x, rtol=1e-7):
+            exponent = round(math.log10(1 - x))
+            s = self._one_minus("10^{%d}" % exponent)
+        elif x < 0.1:
+            s = self._format_value(x, self.locs)
+        elif x > 0.9:
+            s = self._one_minus(self._format_value(1-x, 1-self.locs))
+        else:
+            s = self._format_value(x, self.locs, sci_notation=False)
+        return r"$\mathdefault{%s}$" % s
+
+    def format_data_short(self, value):
+        # docstring inherited
+        # Thresholds chosen to use scientific notation iff exponent <= -2.
+        if value < 0.1:
+            return f"{value:e}"
+        if value < 0.9:
+            return f"{value:f}"
+        return f"1-{1 - value:e}"
+
+
+class EngFormatter(ScalarFormatter):
+    """
+    Format axis values using engineering prefixes to represent powers
+    of 1000, plus a specified unit, e.g., 10 MHz instead of 1e7.
+    """
+
+    # The SI engineering prefixes
+    ENG_PREFIXES = {
+        -30: "q",
+        -27: "r",
+        -24: "y",
+        -21: "z",
+        -18: "a",
+        -15: "f",
+        -12: "p",
+         -9: "n",
+         -6: "\N{MICRO SIGN}",
+         -3: "m",
+          0: "",
+          3: "k",
+          6: "M",
+          9: "G",
+         12: "T",
+         15: "P",
+         18: "E",
+         21: "Z",
+         24: "Y",
+         27: "R",
+         30: "Q"
+    }
+
+    def __init__(self, unit="", places=None, sep=" ", *, usetex=None,
+                 useMathText=None, useOffset=False):
+        r"""
+        Parameters
+        ----------
+        unit : str, default: ""
+            Unit symbol to use, suitable for use with single-letter
+            representations of powers of 1000. For example, 'Hz' or 'm'.
+
+        places : int, default: None
+            Precision with which to display the number, specified in
+            digits after the decimal point (there will be between one
+            and three digits before the decimal point). If it is None,
+            the formatting falls back to the floating point format '%g',
+            which displays up to 6 *significant* digits, i.e. the equivalent
+            value for *places* varies between 0 and 5 (inclusive).
+
+        sep : str, default: " "
+            Separator used between the value and the prefix/unit. For
+            example, one get '3.14 mV' if ``sep`` is " " (default) and
+            '3.14mV' if ``sep`` is "". Besides the default behavior, some
+            other useful options may be:
+
+            * ``sep=""`` to append directly the prefix/unit to the value;
+            * ``sep="\N{THIN SPACE}"`` (``U+2009``);
+            * ``sep="\N{NARROW NO-BREAK SPACE}"`` (``U+202F``);
+            * ``sep="\N{NO-BREAK SPACE}"`` (``U+00A0``).
+
+        usetex : bool, default: :rc:`text.usetex`
+            To enable/disable the use of TeX's math mode for rendering the
+            numbers in the formatter.
+
+        useMathText : bool, default: :rc:`axes.formatter.use_mathtext`
+            To enable/disable the use mathtext for rendering the numbers in
+            the formatter.
+        useOffset : bool or float, default: False
+            Whether to use offset notation with :math:`10^{3*N}` based prefixes.
+            This features allows showing an offset with standard SI order of
+            magnitude prefix near the axis. Offset is computed similarly to
+            how `ScalarFormatter` computes it internally, but here you are
+            guaranteed to get an offset which will make the tick labels exceed
+            3 digits. See also `.set_useOffset`.
+
+            .. versionadded:: 3.10
+        """
+        self.unit = unit
+        self.places = places
+        self.sep = sep
+        super().__init__(
+            useOffset=useOffset,
+            useMathText=useMathText,
+            useLocale=False,
+            usetex=usetex,
+        )
+
+    def __call__(self, x, pos=None):
+        """
+        Return the format for tick value *x* at position *pos*.
+
+        If there is no currently offset in the data, it returns the best
+        engineering formatting that fits the given argument, independently.
+        """
+        if len(self.locs) == 0 or self.offset == 0:
+            return self.fix_minus(self.format_data(x))
+        else:
+            xp = (x - self.offset) / (10. ** self.orderOfMagnitude)
+            if abs(xp) < 1e-8:
+                xp = 0
+            return self._format_maybe_minus_and_locale(self.format, xp)
+
+    def set_locs(self, locs):
+        # docstring inherited
+        self.locs = locs
+        if len(self.locs) > 0:
+            vmin, vmax = sorted(self.axis.get_view_interval())
+            if self._useOffset:
+                self._compute_offset()
+                if self.offset != 0:
+                    # We don't want to use the offset computed by
+                    # self._compute_offset because it rounds the offset unaware
+                    # of our engineering prefixes preference, and this can
+                    # cause ticks with 4+ digits to appear. These ticks are
+                    # slightly less readable, so if offset is justified
+                    # (decided by self._compute_offset) we set it to better
+                    # value:
+                    self.offset = round((vmin + vmax)/2, 3)
+            # Use log1000 to use engineers' oom standards
+            self.orderOfMagnitude = math.floor(math.log(vmax - vmin, 1000))*3
+            self._set_format()
+
+    # Simplify a bit ScalarFormatter.get_offset: We always want to use
+    # self.format_data. Also we want to return a non-empty string only if there
+    # is an offset, no matter what is self.orderOfMagnitude. If there _is_ an
+    # offset, self.orderOfMagnitude is consulted. This behavior is verified
+    # in `test_ticker.py`.
+    def get_offset(self):
+        # docstring inherited
+        if len(self.locs) == 0:
+            return ''
+        if self.offset:
+            offsetStr = ''
+            if self.offset:
+                offsetStr = self.format_data(self.offset)
+                if self.offset > 0:
+                    offsetStr = '+' + offsetStr
+            sciNotStr = self.format_data(10 ** self.orderOfMagnitude)
+            if self._useMathText or self._usetex:
+                if sciNotStr != '':
+                    sciNotStr = r'\times%s' % sciNotStr
+                s = f'${sciNotStr}{offsetStr}$'
+            else:
+                s = sciNotStr + offsetStr
+            return self.fix_minus(s)
+        return ''
+
+    def format_eng(self, num):
+        """Alias to EngFormatter.format_data"""
+        return self.format_data(num)
+
+    def format_data(self, value):
+        """
+        Format a number in engineering notation, appending a letter
+        representing the power of 1000 of the original number.
+        Some examples:
+
+        >>> format_data(0)        # for self.places = 0
+        '0'
+
+        >>> format_data(1000000)  # for self.places = 1
+        '1.0 M'
+
+        >>> format_data(-1e-6)  # for self.places = 2
+        '-1.00 \N{MICRO SIGN}'
+        """
+        sign = 1
+        fmt = "g" if self.places is None else f".{self.places:d}f"
+
+        if value < 0:
+            sign = -1
+            value = -value
+
+        if value != 0:
+            pow10 = int(math.floor(math.log10(value) / 3) * 3)
+        else:
+            pow10 = 0
+            # Force value to zero, to avoid inconsistencies like
+            # format_eng(-0) = "0" and format_eng(0.0) = "0"
+            # but format_eng(-0.0) = "-0.0"
+            value = 0.0
+
+        pow10 = np.clip(pow10, min(self.ENG_PREFIXES), max(self.ENG_PREFIXES))
+
+        mant = sign * value / (10.0 ** pow10)
+        # Taking care of the cases like 999.9..., which may be rounded to 1000
+        # instead of 1 k.  Beware of the corner case of values that are beyond
+        # the range of SI prefixes (i.e. > 'Y').
+        if (abs(float(format(mant, fmt))) >= 1000
+                and pow10 < max(self.ENG_PREFIXES)):
+            mant /= 1000
+            pow10 += 3
+
+        unit_prefix = self.ENG_PREFIXES[int(pow10)]
+        if self.unit or unit_prefix:
+            suffix = f"{self.sep}{unit_prefix}{self.unit}"
+        else:
+            suffix = ""
+        if self._usetex or self._useMathText:
+            return f"${mant:{fmt}}${suffix}"
+        else:
+            return f"{mant:{fmt}}{suffix}"
+
+
+class PercentFormatter(Formatter):
+    """
+    Format numbers as a percentage.
+
+    Parameters
+    ----------
+    xmax : float
+        Determines how the number is converted into a percentage.
+        *xmax* is the data value that corresponds to 100%.
+        Percentages are computed as ``x / xmax * 100``. So if the data is
+        already scaled to be percentages, *xmax* will be 100. Another common
+        situation is where *xmax* is 1.0.
+
+    decimals : None or int
+        The number of decimal places to place after the point.
+        If *None* (the default), the number will be computed automatically.
+
+    symbol : str or None
+        A string that will be appended to the label. It may be
+        *None* or empty to indicate that no symbol should be used. LaTeX
+        special characters are escaped in *symbol* whenever latex mode is
+        enabled, unless *is_latex* is *True*.
+
+    is_latex : bool
+        If *False*, reserved LaTeX characters in *symbol* will be escaped.
+    """
+    def __init__(self, xmax=100, decimals=None, symbol='%', is_latex=False):
+        self.xmax = xmax + 0.0
+        self.decimals = decimals
+        self._symbol = symbol
+        self._is_latex = is_latex
+
+    def __call__(self, x, pos=None):
+        """Format the tick as a percentage with the appropriate scaling."""
+        ax_min, ax_max = self.axis.get_view_interval()
+        display_range = abs(ax_max - ax_min)
+        return self.fix_minus(self.format_pct(x, display_range))
+
+    def format_pct(self, x, display_range):
+        """
+        Format the number as a percentage number with the correct
+        number of decimals and adds the percent symbol, if any.
+
+        If ``self.decimals`` is `None`, the number of digits after the
+        decimal point is set based on the *display_range* of the axis
+        as follows:
+
+        ============= ======== =======================
+        display_range decimals sample
+        ============= ======== =======================
+        >50           0        ``x = 34.5`` => 35%
+        >5            1        ``x = 34.5`` => 34.5%
+        >0.5          2        ``x = 34.5`` => 34.50%
+        ...           ...      ...
+        ============= ======== =======================
+
+        This method will not be very good for tiny axis ranges or
+        extremely large ones. It assumes that the values on the chart
+        are percentages displayed on a reasonable scale.
+        """
+        x = self.convert_to_pct(x)
+        if self.decimals is None:
+            # conversion works because display_range is a difference
+            scaled_range = self.convert_to_pct(display_range)
+            if scaled_range <= 0:
+                decimals = 0
+            else:
+                # Luckily Python's built-in ceil rounds to +inf, not away from
+                # zero. This is very important since the equation for decimals
+                # starts out as `scaled_range > 0.5 * 10**(2 - decimals)`
+                # and ends up with `decimals > 2 - log10(2 * scaled_range)`.
+                decimals = math.ceil(2.0 - math.log10(2.0 * scaled_range))
+                if decimals > 5:
+                    decimals = 5
+                elif decimals < 0:
+                    decimals = 0
+        else:
+            decimals = self.decimals
+        s = f'{x:0.{int(decimals)}f}'
+
+        return s + self.symbol
+
+    def convert_to_pct(self, x):
+        return 100.0 * (x / self.xmax)
+
+    @property
+    def symbol(self):
+        r"""
+        The configured percent symbol as a string.
+
+        If LaTeX is enabled via :rc:`text.usetex`, the special characters
+        ``{'#', '$', '%', '&', '~', '_', '^', '\', '{', '}'}`` are
+        automatically escaped in the string.
+        """
+        symbol = self._symbol
+        if not symbol:
+            symbol = ''
+        elif not self._is_latex and mpl.rcParams['text.usetex']:
+            # Source: http://www.personal.ceu.hu/tex/specchar.htm
+            # Backslash must be first for this to work correctly since
+            # it keeps getting added in
+            for spec in r'\#$%&~_^{}':
+                symbol = symbol.replace(spec, '\\' + spec)
+        return symbol
+
+    @symbol.setter
+    def symbol(self, symbol):
+        self._symbol = symbol
+
+
+class Locator(TickHelper):
+    """
+    Determine tick locations.
+
+    Note that the same locator should not be used across multiple
+    `~matplotlib.axis.Axis` because the locator stores references to the Axis
+    data and view limits.
+    """
+
+    # Some automatic tick locators can generate so many ticks they
+    # kill the machine when you try and render them.
+    # This parameter is set to cause locators to raise an error if too
+    # many ticks are generated.
+    MAXTICKS = 1000
+
+    def tick_values(self, vmin, vmax):
+        """
+        Return the values of the located ticks given **vmin** and **vmax**.
+
+        .. note::
+            To get tick locations with the vmin and vmax values defined
+            automatically for the associated ``axis`` simply call
+            the Locator instance::
+
+                >>> print(type(loc))
+                <type 'Locator'>
+                >>> print(loc())
+                [1, 2, 3, 4]
+
+        """
+        raise NotImplementedError('Derived must override')
+
+    def set_params(self, **kwargs):
+        """
+        Do nothing, and raise a warning. Any locator class not supporting the
+        set_params() function will call this.
+        """
+        _api.warn_external(
+            "'set_params()' not defined for locator of type " +
+            str(type(self)))
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        # note: some locators return data limits, other return view limits,
+        # hence there is no *one* interface to call self.tick_values.
+        raise NotImplementedError('Derived must override')
+
+    def raise_if_exceeds(self, locs):
+        """
+        Log at WARNING level if *locs* is longer than `Locator.MAXTICKS`.
+
+        This is intended to be called immediately before returning *locs* from
+        ``__call__`` to inform users in case their Locator returns a huge
+        number of ticks, causing Matplotlib to run out of memory.
+
+        The "strange" name of this method dates back to when it would raise an
+        exception instead of emitting a log.
+        """
+        if len(locs) >= self.MAXTICKS:
+            _log.warning(
+                "Locator attempting to generate %s ticks ([%s, ..., %s]), "
+                "which exceeds Locator.MAXTICKS (%s).",
+                len(locs), locs[0], locs[-1], self.MAXTICKS)
+        return locs
+
+    def nonsingular(self, v0, v1):
+        """
+        Adjust a range as needed to avoid singularities.
+
+        This method gets called during autoscaling, with ``(v0, v1)`` set to
+        the data limits on the Axes if the Axes contains any data, or
+        ``(-inf, +inf)`` if not.
+
+        - If ``v0 == v1`` (possibly up to some floating point slop), this
+          method returns an expanded interval around this value.
+        - If ``(v0, v1) == (-inf, +inf)``, this method returns appropriate
+          default view limits.
+        - Otherwise, ``(v0, v1)`` is returned without modification.
+        """
+        return mtransforms.nonsingular(v0, v1, expander=.05)
+
+    def view_limits(self, vmin, vmax):
+        """
+        Select a scale for the range from vmin to vmax.
+
+        Subclasses should override this method to change locator behaviour.
+        """
+        return mtransforms.nonsingular(vmin, vmax)
+
+
+class IndexLocator(Locator):
+    """
+    Place ticks at every nth point plotted.
+
+    IndexLocator assumes index plotting; i.e., that the ticks are placed at integer
+    values in the range between 0 and len(data) inclusive.
+    """
+    def __init__(self, base, offset):
+        """Place ticks every *base* data point, starting at *offset*."""
+        self._base = base
+        self.offset = offset
+
+    def set_params(self, base=None, offset=None):
+        """Set parameters within this locator"""
+        if base is not None:
+            self._base = base
+        if offset is not None:
+            self.offset = offset
+
+    def __call__(self):
+        """Return the locations of the ticks"""
+        dmin, dmax = self.axis.get_data_interval()
+        return self.tick_values(dmin, dmax)
+
+    def tick_values(self, vmin, vmax):
+        return self.raise_if_exceeds(
+            np.arange(vmin + self.offset, vmax + 1, self._base))
+
+
+class FixedLocator(Locator):
+    r"""
+    Place ticks at a set of fixed values.
+
+    If *nbins* is None ticks are placed at all values. Otherwise, the *locs* array of
+    possible positions will be subsampled to keep the number of ticks
+    :math:`\leq nbins + 1`. The subsampling will be done to include the smallest
+    absolute value; for example, if zero is included in the array of possibilities, then
+    it will be included in the chosen ticks.
+    """
+
+    def __init__(self, locs, nbins=None):
+        self.locs = np.asarray(locs)
+        _api.check_shape((None,), locs=self.locs)
+        self.nbins = max(nbins, 2) if nbins is not None else None
+
+    def set_params(self, nbins=None):
+        """Set parameters within this locator."""
+        if nbins is not None:
+            self.nbins = nbins
+
+    def __call__(self):
+        return self.tick_values(None, None)
+
+    def tick_values(self, vmin, vmax):
+        """
+        Return the locations of the ticks.
+
+        .. note::
+
+            Because the values are fixed, vmin and vmax are not used in this
+            method.
+
+        """
+        if self.nbins is None:
+            return self.locs
+        step = max(int(np.ceil(len(self.locs) / self.nbins)), 1)
+        ticks = self.locs[::step]
+        for i in range(1, step):
+            ticks1 = self.locs[i::step]
+            if np.abs(ticks1).min() < np.abs(ticks).min():
+                ticks = ticks1
+        return self.raise_if_exceeds(ticks)
+
+
+class NullLocator(Locator):
+    """
+    No ticks
+    """
+
+    def __call__(self):
+        return self.tick_values(None, None)
+
+    def tick_values(self, vmin, vmax):
+        """
+        Return the locations of the ticks.
+
+        .. note::
+
+            Because the values are Null, vmin and vmax are not used in this
+            method.
+        """
+        return []
+
+
+class LinearLocator(Locator):
+    """
+    Place ticks at evenly spaced values.
+
+    The first time this function is called it will try to set the
+    number of ticks to make a nice tick partitioning.  Thereafter, the
+    number of ticks will be fixed so that interactive navigation will
+    be nice
+
+    """
+    def __init__(self, numticks=None, presets=None):
+        """
+        Parameters
+        ----------
+        numticks : int or None, default None
+            Number of ticks. If None, *numticks* = 11.
+        presets : dict or None, default: None
+            Dictionary mapping ``(vmin, vmax)`` to an array of locations.
+            Overrides *numticks* if there is an entry for the current
+            ``(vmin, vmax)``.
+        """
+        self.numticks = numticks
+        if presets is None:
+            self.presets = {}
+        else:
+            self.presets = presets
+
+    @property
+    def numticks(self):
+        # Old hard-coded default.
+        return self._numticks if self._numticks is not None else 11
+
+    @numticks.setter
+    def numticks(self, numticks):
+        self._numticks = numticks
+
+    def set_params(self, numticks=None, presets=None):
+        """Set parameters within this locator."""
+        if presets is not None:
+            self.presets = presets
+        if numticks is not None:
+            self.numticks = numticks
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        vmin, vmax = mtransforms.nonsingular(vmin, vmax, expander=0.05)
+
+        if (vmin, vmax) in self.presets:
+            return self.presets[(vmin, vmax)]
+
+        if self.numticks == 0:
+            return []
+        ticklocs = np.linspace(vmin, vmax, self.numticks)
+
+        return self.raise_if_exceeds(ticklocs)
+
+    def view_limits(self, vmin, vmax):
+        """Try to choose the view limits intelligently."""
+
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+
+        if vmin == vmax:
+            vmin -= 1
+            vmax += 1
+
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            exponent, remainder = divmod(
+                math.log10(vmax - vmin), math.log10(max(self.numticks - 1, 1)))
+            exponent -= (remainder < .5)
+            scale = max(self.numticks - 1, 1) ** (-exponent)
+            vmin = math.floor(scale * vmin) / scale
+            vmax = math.ceil(scale * vmax) / scale
+
+        return mtransforms.nonsingular(vmin, vmax)
+
+
+class MultipleLocator(Locator):
+    """
+    Place ticks at every integer multiple of a base plus an offset.
+    """
+
+    def __init__(self, base=1.0, offset=0.0):
+        """
+        Parameters
+        ----------
+        base : float > 0, default: 1.0
+            Interval between ticks.
+        offset : float, default: 0.0
+            Value added to each multiple of *base*.
+
+            .. versionadded:: 3.8
+        """
+        self._edge = _Edge_integer(base, 0)
+        self._offset = offset
+
+    def set_params(self, base=None, offset=None):
+        """
+        Set parameters within this locator.
+
+        Parameters
+        ----------
+        base : float > 0, optional
+            Interval between ticks.
+        offset : float, optional
+            Value added to each multiple of *base*.
+
+            .. versionadded:: 3.8
+        """
+        if base is not None:
+            self._edge = _Edge_integer(base, 0)
+        if offset is not None:
+            self._offset = offset
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        step = self._edge.step
+        vmin -= self._offset
+        vmax -= self._offset
+        vmin = self._edge.ge(vmin) * step
+        n = (vmax - vmin + 0.001 * step) // step
+        locs = vmin - step + np.arange(n + 3) * step + self._offset
+        return self.raise_if_exceeds(locs)
+
+    def view_limits(self, dmin, dmax):
+        """
+        Set the view limits to the nearest tick values that contain the data.
+        """
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            vmin = self._edge.le(dmin - self._offset) * self._edge.step + self._offset
+            vmax = self._edge.ge(dmax - self._offset) * self._edge.step + self._offset
+            if vmin == vmax:
+                vmin -= 1
+                vmax += 1
+        else:
+            vmin = dmin
+            vmax = dmax
+
+        return mtransforms.nonsingular(vmin, vmax)
+
+
+def scale_range(vmin, vmax, n=1, threshold=100):
+    dv = abs(vmax - vmin)  # > 0 as nonsingular is called before.
+    meanv = (vmax + vmin) / 2
+    if abs(meanv) / dv < threshold:
+        offset = 0
+    else:
+        offset = math.copysign(10 ** (math.log10(abs(meanv)) // 1), meanv)
+    scale = 10 ** (math.log10(dv / n) // 1)
+    return scale, offset
+
+
+class _Edge_integer:
+    """
+    Helper for `.MaxNLocator`, `.MultipleLocator`, etc.
+
+    Take floating-point precision limitations into account when calculating
+    tick locations as integer multiples of a step.
+    """
+    def __init__(self, step, offset):
+        """
+        Parameters
+        ----------
+        step : float > 0
+            Interval between ticks.
+        offset : float
+            Offset subtracted from the data limits prior to calculating tick
+            locations.
+        """
+        if step <= 0:
+            raise ValueError("'step' must be positive")
+        self.step = step
+        self._offset = abs(offset)
+
+    def closeto(self, ms, edge):
+        # Allow more slop when the offset is large compared to the step.
+        if self._offset > 0:
+            digits = np.log10(self._offset / self.step)
+            tol = max(1e-10, 10 ** (digits - 12))
+            tol = min(0.4999, tol)
+        else:
+            tol = 1e-10
+        return abs(ms - edge) < tol
+
+    def le(self, x):
+        """Return the largest n: n*step <= x."""
+        d, m = divmod(x, self.step)
+        if self.closeto(m / self.step, 1):
+            return d + 1
+        return d
+
+    def ge(self, x):
+        """Return the smallest n: n*step >= x."""
+        d, m = divmod(x, self.step)
+        if self.closeto(m / self.step, 0):
+            return d
+        return d + 1
+
+
+class MaxNLocator(Locator):
+    """
+    Place evenly spaced ticks, with a cap on the total number of ticks.
+
+    Finds nice tick locations with no more than :math:`nbins + 1` ticks being within the
+    view limits. Locations beyond the limits are added to support autoscaling.
+    """
+    default_params = dict(nbins=10,
+                          steps=None,
+                          integer=False,
+                          symmetric=False,
+                          prune=None,
+                          min_n_ticks=2)
+
+    def __init__(self, nbins=None, **kwargs):
+        """
+        Parameters
+        ----------
+        nbins : int or 'auto', default: 10
+            Maximum number of intervals; one less than max number of
+            ticks.  If the string 'auto', the number of bins will be
+            automatically determined based on the length of the axis.
+
+        steps : array-like, optional
+            Sequence of acceptable tick multiples, starting with 1 and
+            ending with 10. For example, if ``steps=[1, 2, 4, 5, 10]``,
+            ``20, 40, 60`` or ``0.4, 0.6, 0.8`` would be possible
+            sets of ticks because they are multiples of 2.
+            ``30, 60, 90`` would not be generated because 3 does not
+            appear in this example list of steps.
+
+        integer : bool, default: False
+            If True, ticks will take only integer values, provided at least
+            *min_n_ticks* integers are found within the view limits.
+
+        symmetric : bool, default: False
+            If True, autoscaling will result in a range symmetric about zero.
+
+        prune : {'lower', 'upper', 'both', None}, default: None
+            Remove the 'lower' tick, the 'upper' tick, or ticks on 'both' sides
+            *if they fall exactly on an axis' edge* (this typically occurs when
+            :rc:`axes.autolimit_mode` is 'round_numbers').  Removing such ticks
+            is mostly useful for stacked or ganged plots, where the upper tick
+            of an Axes overlaps with the lower tick of the axes above it.
+
+        min_n_ticks : int, default: 2
+            Relax *nbins* and *integer* constraints if necessary to obtain
+            this minimum number of ticks.
+        """
+        if nbins is not None:
+            kwargs['nbins'] = nbins
+        self.set_params(**{**self.default_params, **kwargs})
+
+    @staticmethod
+    def _validate_steps(steps):
+        if not np.iterable(steps):
+            raise ValueError('steps argument must be an increasing sequence '
+                             'of numbers between 1 and 10 inclusive')
+        steps = np.asarray(steps)
+        if np.any(np.diff(steps) <= 0) or steps[-1] > 10 or steps[0] < 1:
+            raise ValueError('steps argument must be an increasing sequence '
+                             'of numbers between 1 and 10 inclusive')
+        if steps[0] != 1:
+            steps = np.concatenate([[1], steps])
+        if steps[-1] != 10:
+            steps = np.concatenate([steps, [10]])
+        return steps
+
+    @staticmethod
+    def _staircase(steps):
+        # Make an extended staircase within which the needed step will be
+        # found.  This is probably much larger than necessary.
+        return np.concatenate([0.1 * steps[:-1], steps, [10 * steps[1]]])
+
+    def set_params(self, **kwargs):
+        """
+        Set parameters for this locator.
+
+        Parameters
+        ----------
+        nbins : int or 'auto', optional
+            see `.MaxNLocator`
+        steps : array-like, optional
+            see `.MaxNLocator`
+        integer : bool, optional
+            see `.MaxNLocator`
+        symmetric : bool, optional
+            see `.MaxNLocator`
+        prune : {'lower', 'upper', 'both', None}, optional
+            see `.MaxNLocator`
+        min_n_ticks : int, optional
+            see `.MaxNLocator`
+        """
+        if 'nbins' in kwargs:
+            self._nbins = kwargs.pop('nbins')
+            if self._nbins != 'auto':
+                self._nbins = int(self._nbins)
+        if 'symmetric' in kwargs:
+            self._symmetric = kwargs.pop('symmetric')
+        if 'prune' in kwargs:
+            prune = kwargs.pop('prune')
+            _api.check_in_list(['upper', 'lower', 'both', None], prune=prune)
+            self._prune = prune
+        if 'min_n_ticks' in kwargs:
+            self._min_n_ticks = max(1, kwargs.pop('min_n_ticks'))
+        if 'steps' in kwargs:
+            steps = kwargs.pop('steps')
+            if steps is None:
+                self._steps = np.array([1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10])
+            else:
+                self._steps = self._validate_steps(steps)
+            self._extended_steps = self._staircase(self._steps)
+        if 'integer' in kwargs:
+            self._integer = kwargs.pop('integer')
+        if kwargs:
+            raise _api.kwarg_error("set_params", kwargs)
+
+    def _raw_ticks(self, vmin, vmax):
+        """
+        Generate a list of tick locations including the range *vmin* to
+        *vmax*.  In some applications, one or both of the end locations
+        will not be needed, in which case they are trimmed off
+        elsewhere.
+        """
+        if self._nbins == 'auto':
+            if self.axis is not None:
+                nbins = np.clip(self.axis.get_tick_space(),
+                                max(1, self._min_n_ticks - 1), 9)
+            else:
+                nbins = 9
+        else:
+            nbins = self._nbins
+
+        scale, offset = scale_range(vmin, vmax, nbins)
+        _vmin = vmin - offset
+        _vmax = vmax - offset
+        steps = self._extended_steps * scale
+        if self._integer:
+            # For steps > 1, keep only integer values.
+            igood = (steps < 1) | (np.abs(steps - np.round(steps)) < 0.001)
+            steps = steps[igood]
+
+        raw_step = ((_vmax - _vmin) / nbins)
+        if hasattr(self.axis, "axes") and self.axis.axes.name == '3d':
+            # Due to the change in automargin behavior in mpl3.9, we need to
+            # adjust the raw step to match the mpl3.8 appearance. The zoom
+            # factor of 2/48, gives us the 23/24 modifier.
+            raw_step = raw_step * 23/24
+        large_steps = steps >= raw_step
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            # Classic round_numbers mode may require a larger step.
+            # Get first multiple of steps that are <= _vmin
+            floored_vmins = (_vmin // steps) * steps
+            floored_vmaxs = floored_vmins + steps * nbins
+            large_steps = large_steps & (floored_vmaxs >= _vmax)
+
+        # Find index of smallest large step
+        if any(large_steps):
+            istep = np.nonzero(large_steps)[0][0]
+        else:
+            istep = len(steps) - 1
+
+        # Start at smallest of the steps greater than the raw step, and check
+        # if it provides enough ticks. If not, work backwards through
+        # smaller steps until one is found that provides enough ticks.
+        for step in steps[:istep+1][::-1]:
+
+            if (self._integer and
+                    np.floor(_vmax) - np.ceil(_vmin) >= self._min_n_ticks - 1):
+                step = max(1, step)
+            best_vmin = (_vmin // step) * step
+
+            # Find tick locations spanning the vmin-vmax range, taking into
+            # account degradation of precision when there is a large offset.
+            # The edge ticks beyond vmin and/or vmax are needed for the
+            # "round_numbers" autolimit mode.
+            edge = _Edge_integer(step, offset)
+            low = edge.le(_vmin - best_vmin)
+            high = edge.ge(_vmax - best_vmin)
+            ticks = np.arange(low, high + 1) * step + best_vmin
+            # Count only the ticks that will be displayed.
+            nticks = ((ticks <= _vmax) & (ticks >= _vmin)).sum()
+            if nticks >= self._min_n_ticks:
+                break
+        return ticks + offset
+
+    def __call__(self):
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        if self._symmetric:
+            vmax = max(abs(vmin), abs(vmax))
+            vmin = -vmax
+        vmin, vmax = mtransforms.nonsingular(
+            vmin, vmax, expander=1e-13, tiny=1e-14)
+        locs = self._raw_ticks(vmin, vmax)
+
+        prune = self._prune
+        if prune == 'lower':
+            locs = locs[1:]
+        elif prune == 'upper':
+            locs = locs[:-1]
+        elif prune == 'both':
+            locs = locs[1:-1]
+        return self.raise_if_exceeds(locs)
+
+    def view_limits(self, dmin, dmax):
+        if self._symmetric:
+            dmax = max(abs(dmin), abs(dmax))
+            dmin = -dmax
+
+        dmin, dmax = mtransforms.nonsingular(
+            dmin, dmax, expander=1e-12, tiny=1e-13)
+
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            return self._raw_ticks(dmin, dmax)[[0, -1]]
+        else:
+            return dmin, dmax
+
+
+def _is_decade(x, *, base=10, rtol=None):
+    """Return True if *x* is an integer power of *base*."""
+    if not np.isfinite(x):
+        return False
+    if x == 0.0:
+        return True
+    lx = np.log(abs(x)) / np.log(base)
+    if rtol is None:
+        return np.isclose(lx, np.round(lx))
+    else:
+        return np.isclose(lx, np.round(lx), rtol=rtol)
+
+
+def _decade_less_equal(x, base):
+    """
+    Return the largest integer power of *base* that's less or equal to *x*.
+
+    If *x* is negative, the exponent will be *greater*.
+    """
+    return (x if x == 0 else
+            -_decade_greater_equal(-x, base) if x < 0 else
+            base ** np.floor(np.log(x) / np.log(base)))
+
+
+def _decade_greater_equal(x, base):
+    """
+    Return the smallest integer power of *base* that's greater or equal to *x*.
+
+    If *x* is negative, the exponent will be *smaller*.
+    """
+    return (x if x == 0 else
+            -_decade_less_equal(-x, base) if x < 0 else
+            base ** np.ceil(np.log(x) / np.log(base)))
+
+
+def _decade_less(x, base):
+    """
+    Return the largest integer power of *base* that's less than *x*.
+
+    If *x* is negative, the exponent will be *greater*.
+    """
+    if x < 0:
+        return -_decade_greater(-x, base)
+    less = _decade_less_equal(x, base)
+    if less == x:
+        less /= base
+    return less
+
+
+def _decade_greater(x, base):
+    """
+    Return the smallest integer power of *base* that's greater than *x*.
+
+    If *x* is negative, the exponent will be *smaller*.
+    """
+    if x < 0:
+        return -_decade_less(-x, base)
+    greater = _decade_greater_equal(x, base)
+    if greater == x:
+        greater *= base
+    return greater
+
+
+def _is_close_to_int(x):
+    return math.isclose(x, round(x))
+
+
+class LogLocator(Locator):
+    """
+    Place logarithmically spaced ticks.
+
+    Places ticks at the values ``subs[j] * base**i``.
+    """
+
+    def __init__(self, base=10.0, subs=(1.0,), *, numticks=None):
+        """
+        Parameters
+        ----------
+        base : float, default: 10.0
+            The base of the log used, so major ticks are placed at ``base**n``, where
+            ``n`` is an integer.
+        subs : None or {'auto', 'all'} or sequence of float, default: (1.0,)
+            Gives the multiples of integer powers of the base at which to place ticks.
+            The default of ``(1.0, )`` places ticks only at integer powers of the base.
+            Permitted string values are ``'auto'`` and ``'all'``. Both of these use an
+            algorithm based on the axis view limits to determine whether and how to put
+            ticks between integer powers of the base:
+            - ``'auto'``: Ticks are placed only between integer powers.
+            - ``'all'``: Ticks are placed between *and* at integer powers.
+            - ``None``: Equivalent to ``'auto'``.
+        numticks : None or int, default: None
+            The maximum number of ticks to allow on a given axis. The default of
+            ``None`` will try to choose intelligently as long as this Locator has
+            already been assigned to an axis using `~.axis.Axis.get_tick_space`, but
+            otherwise falls back to 9.
+        """
+        if numticks is None:
+            if mpl.rcParams['_internal.classic_mode']:
+                numticks = 15
+            else:
+                numticks = 'auto'
+        self._base = float(base)
+        self._set_subs(subs)
+        self.numticks = numticks
+
+    def set_params(self, base=None, subs=None, *, numticks=None):
+        """Set parameters within this locator."""
+        if base is not None:
+            self._base = float(base)
+        if subs is not None:
+            self._set_subs(subs)
+        if numticks is not None:
+            self.numticks = numticks
+
+    def _set_subs(self, subs):
+        """
+        Set the minor ticks for the log scaling every ``base**i*subs[j]``.
+        """
+        if subs is None:  # consistency with previous bad API
+            self._subs = 'auto'
+        elif isinstance(subs, str):
+            _api.check_in_list(('all', 'auto'), subs=subs)
+            self._subs = subs
+        else:
+            try:
+                self._subs = np.asarray(subs, dtype=float)
+            except ValueError as e:
+                raise ValueError("subs must be None, 'all', 'auto' or "
+                                 "a sequence of floats, not "
+                                 f"{subs}.") from e
+            if self._subs.ndim != 1:
+                raise ValueError("A sequence passed to subs must be "
+                                 "1-dimensional, not "
+                                 f"{self._subs.ndim}-dimensional.")
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        if self.numticks == 'auto':
+            if self.axis is not None:
+                numticks = np.clip(self.axis.get_tick_space(), 2, 9)
+            else:
+                numticks = 9
+        else:
+            numticks = self.numticks
+
+        b = self._base
+        if vmin <= 0.0:
+            if self.axis is not None:
+                vmin = self.axis.get_minpos()
+
+            if vmin <= 0.0 or not np.isfinite(vmin):
+                raise ValueError(
+                    "Data has no positive values, and therefore cannot be log-scaled.")
+
+        _log.debug('vmin %s vmax %s', vmin, vmax)
+
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        log_vmin = math.log(vmin) / math.log(b)
+        log_vmax = math.log(vmax) / math.log(b)
+
+        numdec = math.floor(log_vmax) - math.ceil(log_vmin)
+
+        if isinstance(self._subs, str):
+            if numdec > 10 or b < 3:
+                if self._subs == 'auto':
+                    return np.array([])  # no minor or major ticks
+                else:
+                    subs = np.array([1.0])  # major ticks
+            else:
+                _first = 2.0 if self._subs == 'auto' else 1.0
+                subs = np.arange(_first, b)
+        else:
+            subs = self._subs
+
+        # Get decades between major ticks.
+        stride = (max(math.ceil(numdec / (numticks - 1)), 1)
+                  if mpl.rcParams['_internal.classic_mode'] else
+                  numdec // numticks + 1)
+
+        # if we have decided that the stride is as big or bigger than
+        # the range, clip the stride back to the available range - 1
+        # with a floor of 1.  This prevents getting axis with only 1 tick
+        # visible.
+        if stride >= numdec:
+            stride = max(1, numdec - 1)
+
+        # Does subs include anything other than 1?  Essentially a hack to know
+        # whether we're a major or a minor locator.
+        have_subs = len(subs) > 1 or (len(subs) == 1 and subs[0] != 1.0)
+
+        decades = np.arange(math.floor(log_vmin) - stride,
+                            math.ceil(log_vmax) + 2 * stride, stride)
+
+        if have_subs:
+            if stride == 1:
+                ticklocs = np.concatenate(
+                    [subs * decade_start for decade_start in b ** decades])
+            else:
+                ticklocs = np.array([])
+        else:
+            ticklocs = b ** decades
+
+        _log.debug('ticklocs %r', ticklocs)
+        if (len(subs) > 1
+                and stride == 1
+                and ((vmin <= ticklocs) & (ticklocs <= vmax)).sum() <= 1):
+            # If we're a minor locator *that expects at least two ticks per
+            # decade* and the major locator stride is 1 and there's no more
+            # than one minor tick, switch to AutoLocator.
+            return AutoLocator().tick_values(vmin, vmax)
+        else:
+            return self.raise_if_exceeds(ticklocs)
+
+    def view_limits(self, vmin, vmax):
+        """Try to choose the view limits intelligently."""
+        b = self._base
+
+        vmin, vmax = self.nonsingular(vmin, vmax)
+
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            vmin = _decade_less_equal(vmin, b)
+            vmax = _decade_greater_equal(vmax, b)
+
+        return vmin, vmax
+
+    def nonsingular(self, vmin, vmax):
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+        if not np.isfinite(vmin) or not np.isfinite(vmax):
+            vmin, vmax = 1, 10  # Initial range, no data plotted yet.
+        elif vmax <= 0:
+            _api.warn_external(
+                "Data has no positive values, and therefore cannot be "
+                "log-scaled.")
+            vmin, vmax = 1, 10
+        else:
+            # Consider shared axises
+            minpos = min(axis.get_minpos() for axis in self.axis._get_shared_axis())
+            if not np.isfinite(minpos):
+                minpos = 1e-300  # This should never take effect.
+            if vmin <= 0:
+                vmin = minpos
+            if vmin == vmax:
+                vmin = _decade_less(vmin, self._base)
+                vmax = _decade_greater(vmax, self._base)
+        return vmin, vmax
+
+
+class SymmetricalLogLocator(Locator):
+    """
+    Place ticks spaced linearly near zero and spaced logarithmically beyond a threshold.
+    """
+
+    def __init__(self, transform=None, subs=None, linthresh=None, base=None):
+        """
+        Parameters
+        ----------
+        transform : `~.scale.SymmetricalLogTransform`, optional
+            If set, defines the *base* and *linthresh* of the symlog transform.
+        base, linthresh : float, optional
+            The *base* and *linthresh* of the symlog transform, as documented
+            for `.SymmetricalLogScale`.  These parameters are only used if
+            *transform* is not set.
+        subs : sequence of float, default: [1]
+            The multiples of integer powers of the base where ticks are placed,
+            i.e., ticks are placed at
+            ``[sub * base**i for i in ... for sub in subs]``.
+
+        Notes
+        -----
+        Either *transform*, or both *base* and *linthresh*, must be given.
+        """
+        if transform is not None:
+            self._base = transform.base
+            self._linthresh = transform.linthresh
+        elif linthresh is not None and base is not None:
+            self._base = base
+            self._linthresh = linthresh
+        else:
+            raise ValueError("Either transform, or both linthresh "
+                             "and base, must be provided.")
+        if subs is None:
+            self._subs = [1.0]
+        else:
+            self._subs = subs
+        self.numticks = 15
+
+    def set_params(self, subs=None, numticks=None):
+        """Set parameters within this locator."""
+        if numticks is not None:
+            self.numticks = numticks
+        if subs is not None:
+            self._subs = subs
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        # Note, these are untransformed coordinates
+        vmin, vmax = self.axis.get_view_interval()
+        return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        linthresh = self._linthresh
+
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+
+        # The domain is divided into three sections, only some of
+        # which may actually be present.
+        #
+        # <======== -t ==0== t ========>
+        # aaaaaaaaa    bbbbb   ccccccccc
+        #
+        # a) and c) will have ticks at integral log positions.  The
+        # number of ticks needs to be reduced if there are more
+        # than self.numticks of them.
+        #
+        # b) has a tick at 0 and only 0 (we assume t is a small
+        # number, and the linear segment is just an implementation
+        # detail and not interesting.)
+        #
+        # We could also add ticks at t, but that seems to usually be
+        # uninteresting.
+        #
+        # "simple" mode is when the range falls entirely within [-t, t]
+        #  -- it should just display (vmin, 0, vmax)
+        if -linthresh <= vmin < vmax <= linthresh:
+            # only the linear range is present
+            return sorted({vmin, 0, vmax})
+
+        # Lower log range is present
+        has_a = (vmin < -linthresh)
+        # Upper log range is present
+        has_c = (vmax > linthresh)
+
+        # Check if linear range is present
+        has_b = (has_a and vmax > -linthresh) or (has_c and vmin < linthresh)
+
+        base = self._base
+
+        def get_log_range(lo, hi):
+            lo = np.floor(np.log(lo) / np.log(base))
+            hi = np.ceil(np.log(hi) / np.log(base))
+            return lo, hi
+
+        # Calculate all the ranges, so we can determine striding
+        a_lo, a_hi = (0, 0)
+        if has_a:
+            a_upper_lim = min(-linthresh, vmax)
+            a_lo, a_hi = get_log_range(abs(a_upper_lim), abs(vmin) + 1)
+
+        c_lo, c_hi = (0, 0)
+        if has_c:
+            c_lower_lim = max(linthresh, vmin)
+            c_lo, c_hi = get_log_range(c_lower_lim, vmax + 1)
+
+        # Calculate the total number of integer exponents in a and c ranges
+        total_ticks = (a_hi - a_lo) + (c_hi - c_lo)
+        if has_b:
+            total_ticks += 1
+        stride = max(total_ticks // (self.numticks - 1), 1)
+
+        decades = []
+        if has_a:
+            decades.extend(-1 * (base ** (np.arange(a_lo, a_hi,
+                                                    stride)[::-1])))
+
+        if has_b:
+            decades.append(0.0)
+
+        if has_c:
+            decades.extend(base ** (np.arange(c_lo, c_hi, stride)))
+
+        subs = np.asarray(self._subs)
+
+        if len(subs) > 1 or subs[0] != 1.0:
+            ticklocs = []
+            for decade in decades:
+                if decade == 0:
+                    ticklocs.append(decade)
+                else:
+                    ticklocs.extend(subs * decade)
+        else:
+            ticklocs = decades
+
+        return self.raise_if_exceeds(np.array(ticklocs))
+
+    def view_limits(self, vmin, vmax):
+        """Try to choose the view limits intelligently."""
+        b = self._base
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+
+        if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
+            vmin = _decade_less_equal(vmin, b)
+            vmax = _decade_greater_equal(vmax, b)
+            if vmin == vmax:
+                vmin = _decade_less(vmin, b)
+                vmax = _decade_greater(vmax, b)
+
+        return mtransforms.nonsingular(vmin, vmax)
+
+
+class AsinhLocator(Locator):
+    """
+    Place ticks spaced evenly on an inverse-sinh scale.
+
+    Generally used with the `~.scale.AsinhScale` class.
+
+    .. note::
+
+       This API is provisional and may be revised in the future
+       based on early user feedback.
+    """
+    def __init__(self, linear_width, numticks=11, symthresh=0.2,
+                 base=10, subs=None):
+        """
+        Parameters
+        ----------
+        linear_width : float
+            The scale parameter defining the extent
+            of the quasi-linear region.
+        numticks : int, default: 11
+            The approximate number of major ticks that will fit
+            along the entire axis
+        symthresh : float, default: 0.2
+            The fractional threshold beneath which data which covers
+            a range that is approximately symmetric about zero
+            will have ticks that are exactly symmetric.
+        base : int, default: 10
+            The number base used for rounding tick locations
+            on a logarithmic scale. If this is less than one,
+            then rounding is to the nearest integer multiple
+            of powers of ten.
+        subs : tuple, default: None
+            Multiples of the number base, typically used
+            for the minor ticks, e.g. (2, 5) when base=10.
+        """
+        super().__init__()
+        self.linear_width = linear_width
+        self.numticks = numticks
+        self.symthresh = symthresh
+        self.base = base
+        self.subs = subs
+
+    def set_params(self, numticks=None, symthresh=None,
+                   base=None, subs=None):
+        """Set parameters within this locator."""
+        if numticks is not None:
+            self.numticks = numticks
+        if symthresh is not None:
+            self.symthresh = symthresh
+        if base is not None:
+            self.base = base
+        if subs is not None:
+            self.subs = subs if len(subs) > 0 else None
+
+    def __call__(self):
+        vmin, vmax = self.axis.get_view_interval()
+        if (vmin * vmax) < 0 and abs(1 + vmax / vmin) < self.symthresh:
+            # Data-range appears to be almost symmetric, so round up:
+            bound = max(abs(vmin), abs(vmax))
+            return self.tick_values(-bound, bound)
+        else:
+            return self.tick_values(vmin, vmax)
+
+    def tick_values(self, vmin, vmax):
+        # Construct a set of uniformly-spaced "on-screen" locations.
+        ymin, ymax = self.linear_width * np.arcsinh(np.array([vmin, vmax])
+                                                    / self.linear_width)
+        ys = np.linspace(ymin, ymax, self.numticks)
+        zero_dev = abs(ys / (ymax - ymin))
+        if ymin * ymax < 0:
+            # Ensure that the zero tick-mark is included, if the axis straddles zero.
+            ys = np.hstack([ys[(zero_dev > 0.5 / self.numticks)], 0.0])
+
+        # Transform the "on-screen" grid to the data space:
+        xs = self.linear_width * np.sinh(ys / self.linear_width)
+        zero_xs = (ys == 0)
+
+        # Round the data-space values to be intuitive base-n numbers, keeping track of
+        # positive and negative values separately and carefully treating the zero value.
+        with np.errstate(divide="ignore"):  # base ** log(0) = base ** -inf = 0.
+            if self.base > 1:
+                pows = (np.sign(xs)
+                        * self.base ** np.floor(np.log(abs(xs)) / math.log(self.base)))
+                qs = np.outer(pows, self.subs).flatten() if self.subs else pows
+            else:  # No need to adjust sign(pows), as it cancels out when computing qs.
+                pows = np.where(zero_xs, 1, 10**np.floor(np.log10(abs(xs))))
+                qs = pows * np.round(xs / pows)
+        ticks = np.array(sorted(set(qs)))
+
+        return ticks if len(ticks) >= 2 else np.linspace(vmin, vmax, self.numticks)
+
+
+class LogitLocator(MaxNLocator):
+    """
+    Place ticks spaced evenly on a logit scale.
+    """
+
+    def __init__(self, minor=False, *, nbins="auto"):
+        """
+        Parameters
+        ----------
+        nbins : int or 'auto', optional
+            Number of ticks. Only used if minor is False.
+        minor : bool, default: False
+            Indicate if this locator is for minor ticks or not.
+        """
+
+        self._minor = minor
+        super().__init__(nbins=nbins, steps=[1, 2, 5, 10])
+
+    def set_params(self, minor=None, **kwargs):
+        """Set parameters within this locator."""
+        if minor is not None:
+            self._minor = minor
+        super().set_params(**kwargs)
+
+    @property
+    def minor(self):
+        return self._minor
+
+    @minor.setter
+    def minor(self, value):
+        self.set_params(minor=value)
+
+    def tick_values(self, vmin, vmax):
+        # dummy axis has no axes attribute
+        if hasattr(self.axis, "axes") and self.axis.axes.name == "polar":
+            raise NotImplementedError("Polar axis cannot be logit scaled yet")
+
+        if self._nbins == "auto":
+            if self.axis is not None:
+                nbins = self.axis.get_tick_space()
+                if nbins < 2:
+                    nbins = 2
+            else:
+                nbins = 9
+        else:
+            nbins = self._nbins
+
+        # We define ideal ticks with their index:
+        # linscale: ... 1e-3 1e-2 1e-1 1/2 1-1e-1 1-1e-2 1-1e-3 ...
+        # b-scale : ... -3   -2   -1   0   1      2      3      ...
+        def ideal_ticks(x):
+            return 10 ** x if x < 0 else 1 - (10 ** (-x)) if x > 0 else 0.5
+
+        vmin, vmax = self.nonsingular(vmin, vmax)
+        binf = int(
+            np.floor(np.log10(vmin))
+            if vmin < 0.5
+            else 0
+            if vmin < 0.9
+            else -np.ceil(np.log10(1 - vmin))
+        )
+        bsup = int(
+            np.ceil(np.log10(vmax))
+            if vmax <= 0.5
+            else 1
+            if vmax <= 0.9
+            else -np.floor(np.log10(1 - vmax))
+        )
+        numideal = bsup - binf - 1
+        if numideal >= 2:
+            # have 2 or more wanted ideal ticks, so use them as major ticks
+            if numideal > nbins:
+                # to many ideal ticks, subsampling ideals for major ticks, and
+                # take others for minor ticks
+                subsampling_factor = math.ceil(numideal / nbins)
+                if self._minor:
+                    ticklocs = [
+                        ideal_ticks(b)
+                        for b in range(binf, bsup + 1)
+                        if (b % subsampling_factor) != 0
+                    ]
+                else:
+                    ticklocs = [
+                        ideal_ticks(b)
+                        for b in range(binf, bsup + 1)
+                        if (b % subsampling_factor) == 0
+                    ]
+                return self.raise_if_exceeds(np.array(ticklocs))
+            if self._minor:
+                ticklocs = []
+                for b in range(binf, bsup):
+                    if b < -1:
+                        ticklocs.extend(np.arange(2, 10) * 10 ** b)
+                    elif b == -1:
+                        ticklocs.extend(np.arange(2, 5) / 10)
+                    elif b == 0:
+                        ticklocs.extend(np.arange(6, 9) / 10)
+                    else:
+                        ticklocs.extend(
+                            1 - np.arange(2, 10)[::-1] * 10 ** (-b - 1)
+                        )
+                return self.raise_if_exceeds(np.array(ticklocs))
+            ticklocs = [ideal_ticks(b) for b in range(binf, bsup + 1)]
+            return self.raise_if_exceeds(np.array(ticklocs))
+        # the scale is zoomed so same ticks as linear scale can be used
+        if self._minor:
+            return []
+        return super().tick_values(vmin, vmax)
+
+    def nonsingular(self, vmin, vmax):
+        standard_minpos = 1e-7
+        initial_range = (standard_minpos, 1 - standard_minpos)
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+        if not np.isfinite(vmin) or not np.isfinite(vmax):
+            vmin, vmax = initial_range  # Initial range, no data plotted yet.
+        elif vmax <= 0 or vmin >= 1:
+            # vmax <= 0 occurs when all values are negative
+            # vmin >= 1 occurs when all values are greater than one
+            _api.warn_external(
+                "Data has no values between 0 and 1, and therefore cannot be "
+                "logit-scaled."
+            )
+            vmin, vmax = initial_range
+        else:
+            minpos = (
+                self.axis.get_minpos()
+                if self.axis is not None
+                else standard_minpos
+            )
+            if not np.isfinite(minpos):
+                minpos = standard_minpos  # This should never take effect.
+            if vmin <= 0:
+                vmin = minpos
+            # NOTE: for vmax, we should query a property similar to get_minpos,
+            # but related to the maximal, less-than-one data point.
+            # Unfortunately, Bbox._minpos is defined very deep in the BBox and
+            # updated with data, so for now we use 1 - minpos as a substitute.
+            if vmax >= 1:
+                vmax = 1 - minpos
+            if vmin == vmax:
+                vmin, vmax = 0.1 * vmin, 1 - 0.1 * vmin
+
+        return vmin, vmax
+
+
+class AutoLocator(MaxNLocator):
+    """
+    Place evenly spaced ticks, with the step size and maximum number of ticks chosen
+    automatically.
+
+    This is a subclass of `~matplotlib.ticker.MaxNLocator`, with parameters
+    *nbins = 'auto'* and *steps = [1, 2, 2.5, 5, 10]*.
+    """
+    def __init__(self):
+        """
+        To know the values of the non-public parameters, please have a
+        look to the defaults of `~matplotlib.ticker.MaxNLocator`.
+        """
+        if mpl.rcParams['_internal.classic_mode']:
+            nbins = 9
+            steps = [1, 2, 5, 10]
+        else:
+            nbins = 'auto'
+            steps = [1, 2, 2.5, 5, 10]
+        super().__init__(nbins=nbins, steps=steps)
+
+
+class AutoMinorLocator(Locator):
+    """
+    Place evenly spaced minor ticks, with the step size and maximum number of ticks
+    chosen automatically.
+
+    The Axis must use a linear scale and have evenly spaced major ticks.
+    """
+
+    def __init__(self, n=None):
+        """
+        Parameters
+        ----------
+        n : int or 'auto', default: :rc:`xtick.minor.ndivs` or :rc:`ytick.minor.ndivs`
+            The number of subdivisions of the interval between major ticks;
+            e.g., n=2 will place a single minor tick midway between major ticks.
+
+            If *n* is 'auto', it will be set to 4 or 5: if the distance
+            between the major ticks equals 1, 2.5, 5 or 10 it can be perfectly
+            divided in 5 equidistant sub-intervals with a length multiple of
+            0.05; otherwise, it is divided in 4 sub-intervals.
+        """
+        self.ndivs = n
+
+    def __call__(self):
+        # docstring inherited
+        if self.axis.get_scale() == 'log':
+            _api.warn_external('AutoMinorLocator does not work on logarithmic scales')
+            return []
+
+        majorlocs = np.unique(self.axis.get_majorticklocs())
+        if len(majorlocs) < 2:
+            # Need at least two major ticks to find minor tick locations.
+            # TODO: Figure out a way to still be able to display minor ticks with less
+            # than two major ticks visible. For now, just display no ticks at all.
+            return []
+        majorstep = majorlocs[1] - majorlocs[0]
+
+        if self.ndivs is None:
+            self.ndivs = mpl.rcParams[
+                'ytick.minor.ndivs' if self.axis.axis_name == 'y'
+                else 'xtick.minor.ndivs']  # for x and z axis
+
+        if self.ndivs == 'auto':
+            majorstep_mantissa = 10 ** (np.log10(majorstep) % 1)
+            ndivs = 5 if np.isclose(majorstep_mantissa, [1, 2.5, 5, 10]).any() else 4
+        else:
+            ndivs = self.ndivs
+
+        minorstep = majorstep / ndivs
+
+        vmin, vmax = sorted(self.axis.get_view_interval())
+        t0 = majorlocs[0]
+        tmin = round((vmin - t0) / minorstep)
+        tmax = round((vmax - t0) / minorstep) + 1
+        locs = (np.arange(tmin, tmax) * minorstep) + t0
+
+        return self.raise_if_exceeds(locs)
+
+    def tick_values(self, vmin, vmax):
+        raise NotImplementedError(
+            f"Cannot get tick locations for a {type(self).__name__}")
diff --git a/lib/python3.12/site-packages/matplotlib/ticker.pyi b/lib/python3.12/site-packages/matplotlib/ticker.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bed288658909860008a3b9055ad63cfc4614dd5d
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/ticker.pyi
@@ -0,0 +1,308 @@
+from collections.abc import Callable, Sequence
+from typing import Any, Literal
+
+from matplotlib.axis import Axis
+from matplotlib.transforms import Transform
+from matplotlib.projections.polar import _AxisWrapper
+
+import numpy as np
+
+class _DummyAxis:
+    __name__: str
+    def __init__(self, minpos: float = ...) -> None: ...
+    def get_view_interval(self) -> tuple[float, float]: ...
+    def set_view_interval(self, vmin: float, vmax: float) -> None: ...
+    def get_minpos(self) -> float: ...
+    def get_data_interval(self) -> tuple[float, float]: ...
+    def set_data_interval(self, vmin: float, vmax: float) -> None: ...
+    def get_tick_space(self) -> int: ...
+
+class TickHelper:
+    axis: None | Axis | _DummyAxis | _AxisWrapper
+    def set_axis(self, axis: Axis | _DummyAxis | _AxisWrapper | None) -> None: ...
+    def create_dummy_axis(self, **kwargs) -> None: ...
+
+class Formatter(TickHelper):
+    locs: list[float]
+    def __call__(self, x: float, pos: int | None = ...) -> str: ...
+    def format_ticks(self, values: list[float]) -> list[str]: ...
+    def format_data(self, value: float) -> str: ...
+    def format_data_short(self, value: float) -> str: ...
+    def get_offset(self) -> str: ...
+    def set_locs(self, locs: list[float]) -> None: ...
+    @staticmethod
+    def fix_minus(s: str) -> str: ...
+
+class NullFormatter(Formatter): ...
+
+class FixedFormatter(Formatter):
+    seq: Sequence[str]
+    offset_string: str
+    def __init__(self, seq: Sequence[str]) -> None: ...
+    def set_offset_string(self, ofs: str) -> None: ...
+
+class FuncFormatter(Formatter):
+    func: Callable[[float, int | None], str]
+    offset_string: str
+    # Callable[[float, int | None], str] | Callable[[float], str]
+    def __init__(self, func: Callable[..., str]) -> None: ...
+    def set_offset_string(self, ofs: str) -> None: ...
+
+class FormatStrFormatter(Formatter):
+    fmt: str
+    def __init__(self, fmt: str) -> None: ...
+
+class StrMethodFormatter(Formatter):
+    fmt: str
+    def __init__(self, fmt: str) -> None: ...
+
+class ScalarFormatter(Formatter):
+    orderOfMagnitude: int
+    format: str
+    def __init__(
+        self,
+        useOffset: bool | float | None = ...,
+        useMathText: bool | None = ...,
+        useLocale: bool | None = ...,
+        *,
+        usetex: bool | None = ...,
+    ) -> None: ...
+    offset: float
+    def get_usetex(self) -> bool: ...
+    def set_usetex(self, val: bool) -> None: ...
+    @property
+    def usetex(self) -> bool: ...
+    @usetex.setter
+    def usetex(self, val: bool) -> None: ...
+    def get_useOffset(self) -> bool: ...
+    def set_useOffset(self, val: bool | float) -> None: ...
+    @property
+    def useOffset(self) -> bool: ...
+    @useOffset.setter
+    def useOffset(self, val: bool | float) -> None: ...
+    def get_useLocale(self) -> bool: ...
+    def set_useLocale(self, val: bool | None) -> None: ...
+    @property
+    def useLocale(self) -> bool: ...
+    @useLocale.setter
+    def useLocale(self, val: bool | None) -> None: ...
+    def get_useMathText(self) -> bool: ...
+    def set_useMathText(self, val: bool | None) -> None: ...
+    @property
+    def useMathText(self) -> bool: ...
+    @useMathText.setter
+    def useMathText(self, val: bool | None) -> None: ...
+    def set_scientific(self, b: bool) -> None: ...
+    def set_powerlimits(self, lims: tuple[int, int]) -> None: ...
+    def format_data_short(self, value: float | np.ma.MaskedArray) -> str: ...
+    def format_data(self, value: float) -> str: ...
+
+class LogFormatter(Formatter):
+    minor_thresholds: tuple[float, float]
+    def __init__(
+        self,
+        base: float = ...,
+        labelOnlyBase: bool = ...,
+        minor_thresholds: tuple[float, float] | None = ...,
+        linthresh: float | None = ...,
+    ) -> None: ...
+    def set_base(self, base: float) -> None: ...
+    labelOnlyBase: bool
+    def set_label_minor(self, labelOnlyBase: bool) -> None: ...
+    def set_locs(self, locs: Any | None = ...) -> None: ...
+    def format_data(self, value: float) -> str: ...
+    def format_data_short(self, value: float) -> str: ...
+
+class LogFormatterExponent(LogFormatter): ...
+class LogFormatterMathtext(LogFormatter): ...
+class LogFormatterSciNotation(LogFormatterMathtext): ...
+
+class LogitFormatter(Formatter):
+    def __init__(
+        self,
+        *,
+        use_overline: bool = ...,
+        one_half: str = ...,
+        minor: bool = ...,
+        minor_threshold: int = ...,
+        minor_number: int = ...
+    ) -> None: ...
+    def use_overline(self, use_overline: bool) -> None: ...
+    def set_one_half(self, one_half: str) -> None: ...
+    def set_minor_threshold(self, minor_threshold: int) -> None: ...
+    def set_minor_number(self, minor_number: int) -> None: ...
+    def format_data_short(self, value: float) -> str: ...
+
+class EngFormatter(ScalarFormatter):
+    ENG_PREFIXES: dict[int, str]
+    unit: str
+    places: int | None
+    sep: str
+    def __init__(
+        self,
+        unit: str = ...,
+        places: int | None = ...,
+        sep: str = ...,
+        *,
+        usetex: bool | None = ...,
+        useMathText: bool | None = ...,
+        useOffset: bool | float | None = ...,
+    ) -> None: ...
+    def format_eng(self, num: float) -> str: ...
+
+class PercentFormatter(Formatter):
+    xmax: float
+    decimals: int | None
+    def __init__(
+        self,
+        xmax: float = ...,
+        decimals: int | None = ...,
+        symbol: str | None = ...,
+        is_latex: bool = ...,
+    ) -> None: ...
+    def format_pct(self, x: float, display_range: float) -> str: ...
+    def convert_to_pct(self, x: float) -> float: ...
+    @property
+    def symbol(self) -> str: ...
+    @symbol.setter
+    def symbol(self, symbol: str) -> None: ...
+
+class Locator(TickHelper):
+    MAXTICKS: int
+    def tick_values(self, vmin: float, vmax: float) -> Sequence[float]: ...
+    # Implementation accepts **kwargs, but is a no-op other than a warning
+    # Typing as **kwargs would require each subclass to accept **kwargs for mypy
+    def set_params(self) -> None: ...
+    def __call__(self) -> Sequence[float]: ...
+    def raise_if_exceeds(self, locs: Sequence[float]) -> Sequence[float]: ...
+    def nonsingular(self, v0: float, v1: float) -> tuple[float, float]: ...
+    def view_limits(self, vmin: float, vmax: float) -> tuple[float, float]: ...
+
+class IndexLocator(Locator):
+    offset: float
+    def __init__(self, base: float, offset: float) -> None: ...
+    def set_params(
+        self, base: float | None = ..., offset: float | None = ...
+    ) -> None: ...
+
+class FixedLocator(Locator):
+    nbins: int | None
+    def __init__(self, locs: Sequence[float], nbins: int | None = ...) -> None: ...
+    def set_params(self, nbins: int | None = ...) -> None: ...
+
+class NullLocator(Locator): ...
+
+class LinearLocator(Locator):
+    presets: dict[tuple[float, float], Sequence[float]]
+    def __init__(
+        self,
+        numticks: int | None = ...,
+        presets: dict[tuple[float, float], Sequence[float]] | None = ...,
+    ) -> None: ...
+    @property
+    def numticks(self) -> int: ...
+    @numticks.setter
+    def numticks(self, numticks: int | None) -> None: ...
+    def set_params(
+        self,
+        numticks: int | None = ...,
+        presets: dict[tuple[float, float], Sequence[float]] | None = ...,
+    ) -> None: ...
+
+class MultipleLocator(Locator):
+    def __init__(self, base: float = ..., offset: float = ...) -> None: ...
+    def set_params(self, base: float | None = ..., offset: float | None = ...) -> None: ...
+    def view_limits(self, dmin: float, dmax: float) -> tuple[float, float]: ...
+
+class _Edge_integer:
+    step: float
+    def __init__(self, step: float, offset: float) -> None: ...
+    def closeto(self, ms: float, edge: float) -> bool: ...
+    def le(self, x: float) -> float: ...
+    def ge(self, x: float) -> float: ...
+
+class MaxNLocator(Locator):
+    default_params: dict[str, Any]
+    def __init__(self, nbins: int | Literal["auto"] | None = ..., **kwargs) -> None: ...
+    def set_params(self, **kwargs) -> None: ...
+    def view_limits(self, dmin: float, dmax: float) -> tuple[float, float]: ...
+
+class LogLocator(Locator):
+    numticks: int | None
+    def __init__(
+        self,
+        base: float = ...,
+        subs: None | Literal["auto", "all"] | Sequence[float] = ...,
+        *,
+        numticks: int | None = ...,
+    ) -> None: ...
+    def set_params(
+        self,
+        base: float | None = ...,
+        subs: Literal["auto", "all"] | Sequence[float] | None = ...,
+        *,
+        numticks: int | None = ...,
+    ) -> None: ...
+
+class SymmetricalLogLocator(Locator):
+    numticks: int
+    def __init__(
+        self,
+        transform: Transform | None = ...,
+        subs: Sequence[float] | None = ...,
+        linthresh: float | None = ...,
+        base: float | None = ...,
+    ) -> None: ...
+    def set_params(
+        self, subs: Sequence[float] | None = ..., numticks: int | None = ...
+    ) -> None: ...
+
+class AsinhLocator(Locator):
+    linear_width: float
+    numticks: int
+    symthresh: float
+    base: int
+    subs: Sequence[float] | None
+    def __init__(
+        self,
+        linear_width: float,
+        numticks: int = ...,
+        symthresh: float = ...,
+        base: int = ...,
+        subs: Sequence[float] | None = ...,
+    ) -> None: ...
+    def set_params(
+        self,
+        numticks: int | None = ...,
+        symthresh: float | None = ...,
+        base: int | None = ...,
+        subs: Sequence[float] | None = ...,
+    ) -> None: ...
+
+class LogitLocator(MaxNLocator):
+    def __init__(
+        self, minor: bool = ..., *, nbins: Literal["auto"] | int = ...
+    ) -> None: ...
+    def set_params(self, minor: bool | None = ..., **kwargs) -> None: ...
+    @property
+    def minor(self) -> bool: ...
+    @minor.setter
+    def minor(self, value: bool) -> None: ...
+
+class AutoLocator(MaxNLocator):
+    def __init__(self) -> None: ...
+
+class AutoMinorLocator(Locator):
+    ndivs: int
+    def __init__(self, n: int | None = ...) -> None: ...
+
+__all__ = ('TickHelper', 'Formatter', 'FixedFormatter',
+           'NullFormatter', 'FuncFormatter', 'FormatStrFormatter',
+           'StrMethodFormatter', 'ScalarFormatter', 'LogFormatter',
+           'LogFormatterExponent', 'LogFormatterMathtext',
+           'LogFormatterSciNotation',
+           'LogitFormatter', 'EngFormatter', 'PercentFormatter',
+           'Locator', 'IndexLocator', 'FixedLocator', 'NullLocator',
+           'LinearLocator', 'LogLocator', 'AutoLocator',
+           'MultipleLocator', 'MaxNLocator', 'AutoMinorLocator',
+           'SymmetricalLogLocator', 'AsinhLocator', 'LogitLocator')
diff --git a/lib/python3.12/site-packages/matplotlib/typing.py b/lib/python3.12/site-packages/matplotlib/typing.py
new file mode 100644
index 0000000000000000000000000000000000000000..20e1022fa0a5a0487aa771da822ff481685f236f
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/typing.py
@@ -0,0 +1,78 @@
+"""
+Typing support for Matplotlib
+
+This module contains Type aliases which are useful for Matplotlib and potentially
+downstream libraries.
+
+.. admonition:: Provisional status of typing
+
+    The ``typing`` module and type stub files are considered provisional and may change
+    at any time without a deprecation period.
+"""
+from collections.abc import Hashable, Sequence
+import pathlib
+from typing import Any, Callable, Literal, TypeAlias, TypeVar, Union
+
+from . import path
+from ._enums import JoinStyle, CapStyle
+from .artist import Artist
+from .backend_bases import RendererBase
+from .markers import MarkerStyle
+from .transforms import Bbox, Transform
+
+RGBColorType: TypeAlias = tuple[float, float, float] | str
+RGBAColorType: TypeAlias = (
+    str |  # "none" or "#RRGGBBAA"/"#RGBA" hex strings
+    tuple[float, float, float, float] |
+    # 2 tuple (color, alpha) representations, not infinitely recursive
+    # RGBColorType includes the (str, float) tuple, even for RGBA strings
+    tuple[RGBColorType, float] |
+    # (4-tuple, float) is odd, but accepted as the outer float overriding A of 4-tuple
+    tuple[tuple[float, float, float, float], float]
+)
+
+ColorType: TypeAlias = RGBColorType | RGBAColorType
+
+RGBColourType: TypeAlias = RGBColorType
+RGBAColourType: TypeAlias = RGBAColorType
+ColourType: TypeAlias = ColorType
+
+LineStyleType: TypeAlias = str | tuple[float, Sequence[float]]
+DrawStyleType: TypeAlias = Literal["default", "steps", "steps-pre", "steps-mid",
+                                   "steps-post"]
+MarkEveryType: TypeAlias = (
+    None |
+    int | tuple[int, int] | slice | list[int] |
+    float | tuple[float, float] |
+    list[bool]
+)
+
+MarkerType: TypeAlias = str | path.Path | MarkerStyle
+FillStyleType: TypeAlias = Literal["full", "left", "right", "bottom", "top", "none"]
+JoinStyleType: TypeAlias = JoinStyle | Literal["miter", "round", "bevel"]
+CapStyleType: TypeAlias = CapStyle | Literal["butt", "projecting", "round"]
+
+CoordsBaseType = Union[
+    str,
+    Artist,
+    Transform,
+    Callable[
+        [RendererBase],
+        Union[Bbox, Transform]
+    ]
+]
+CoordsType = Union[
+    CoordsBaseType,
+    tuple[CoordsBaseType, CoordsBaseType]
+]
+
+RcStyleType: TypeAlias = (
+    str |
+    dict[str, Any] |
+    pathlib.Path |
+    Sequence[str | pathlib.Path | dict[str, Any]]
+)
+
+_HT = TypeVar("_HT", bound=Hashable)
+HashableList: TypeAlias = list[_HT | "HashableList[_HT]"]
+"""A nested list of Hashable values."""
diff --git a/lib/python3.12/site-packages/matplotlib/widgets.py b/lib/python3.12/site-packages/matplotlib/widgets.py
new file mode 100644
index 0000000000000000000000000000000000000000..9c676574310c3ccbed5daefca32278084750a3d8
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/widgets.py
@@ -0,0 +1,4175 @@
+"""
+GUI neutral widgets
+===================
+
+Widgets that are designed to work for any of the GUI backends.
+All of these widgets require you to predefine an `~.axes.Axes`
+instance and pass that as the first parameter.  Matplotlib doesn't try to
+be too smart with respect to layout -- you will have to figure out how
+wide and tall you want your Axes to be to accommodate your widget.
+"""
+
+from contextlib import ExitStack
+import copy
+import itertools
+from numbers import Integral, Number
+
+from cycler import cycler
+import numpy as np
+
+import matplotlib as mpl
+from . import (_api, _docstring, backend_tools, cbook, collections, colors,
+               text as mtext, ticker, transforms)
+from .lines import Line2D
+from .patches import Rectangle, Ellipse, Polygon
+from .transforms import TransformedPatchPath, Affine2D
+
+
+class LockDraw:
+    """
+    Some widgets, like the cursor, draw onto the canvas, and this is not
+    desirable under all circumstances, like when the toolbar is in zoom-to-rect
+    mode and drawing a rectangle.  To avoid this, a widget can acquire a
+    canvas' lock with ``canvas.widgetlock(widget)`` before drawing on the
+    canvas; this will prevent other widgets from doing so at the same time (if
+    they also try to acquire the lock first).
+    """
+
+    def __init__(self):
+        self._owner = None
+
+    def __call__(self, o):
+        """Reserve the lock for *o*."""
+        if not self.available(o):
+            raise ValueError('already locked')
+        self._owner = o
+
+    def release(self, o):
+        """Release the lock from *o*."""
+        if not self.available(o):
+            raise ValueError('you do not own this lock')
+        self._owner = None
+
+    def available(self, o):
+        """Return whether drawing is available to *o*."""
+        return not self.locked() or self.isowner(o)
+
+    def isowner(self, o):
+        """Return whether *o* owns this lock."""
+        return self._owner is o
+
+    def locked(self):
+        """Return whether the lock is currently held by an owner."""
+        return self._owner is not None
+
+
+class Widget:
+    """
+    Abstract base class for GUI neutral widgets.
+    """
+    drawon = True
+    eventson = True
+    _active = True
+
+    def set_active(self, active):
+        """Set whether the widget is active."""
+        self._active = active
+
+    def get_active(self):
+        """Get whether the widget is active."""
+        return self._active
+
+    # set_active is overridden by SelectorWidgets.
+    active = property(get_active, set_active, doc="Is the widget active?")
+
+    def ignore(self, event):
+        """
+        Return whether *event* should be ignored.
+
+        This method should be called at the beginning of any event callback.
+        """
+        return not self.active
+
+
+class AxesWidget(Widget):
+    """
+    Widget connected to a single `~matplotlib.axes.Axes`.
+
+    To guarantee that the widget remains responsive and not garbage-collected,
+    a reference to the object should be maintained by the user.
+
+    This is necessary because the callback registry
+    maintains only weak-refs to the functions, which are member
+    functions of the widget.  If there are no references to the widget
+    object it may be garbage collected which will disconnect the callbacks.
+
+    Attributes
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    canvas : `~matplotlib.backend_bases.FigureCanvasBase`
+        The parent figure canvas for the widget.
+    active : bool
+        If False, the widget does not respond to events.
+    """
+
+    def __init__(self, ax):
+        self.ax = ax
+        self._cids = []
+
+    canvas = property(lambda self: self.ax.get_figure(root=True).canvas)
+
+    def connect_event(self, event, callback):
+        """
+        Connect a callback function with an event.
+
+        This should be used in lieu of ``figure.canvas.mpl_connect`` since this
+        function stores callback ids for later clean up.
+        """
+        cid = self.canvas.mpl_connect(event, callback)
+        self._cids.append(cid)
+
+    def disconnect_events(self):
+        """Disconnect all events created by this widget."""
+        for c in self._cids:
+            self.canvas.mpl_disconnect(c)
+
+    def _get_data_coords(self, event):
+        """Return *event*'s data coordinates in this widget's Axes."""
+        # This method handles the possibility that event.inaxes != self.ax (which may
+        # occur if multiple Axes are overlaid), in which case event.xdata/.ydata will
+        # be wrong.  Note that we still special-case the common case where
+        # event.inaxes == self.ax and avoid re-running the inverse data transform,
+        # because that can introduce floating point errors for synthetic events.
+        return ((event.xdata, event.ydata) if event.inaxes is self.ax
+                else self.ax.transData.inverted().transform((event.x, event.y)))
+
+
+class Button(AxesWidget):
+    """
+    A GUI neutral button.
+
+    For the button to remain responsive you must keep a reference to it.
+    Call `.on_clicked` to connect to the button.
+
+    Attributes
+    ----------
+    ax
+        The `~.axes.Axes` the button renders into.
+    label
+        A `.Text` instance.
+    color
+        The color of the button when not hovering.
+    hovercolor
+        The color of the button when hovering.
+    """
+
+    def __init__(self, ax, label, image=None,
+                 color='0.85', hovercolor='0.95', *, useblit=True):
+        """
+        Parameters
+        ----------
+        ax : `~matplotlib.axes.Axes`
+            The `~.axes.Axes` instance the button will be placed into.
+        label : str
+            The button text.
+        image : array-like or PIL Image
+            The image to place in the button, if not *None*.  The parameter is
+            directly forwarded to `~.axes.Axes.imshow`.
+        color : :mpltype:`color`
+            The color of the button when not activated.
+        hovercolor : :mpltype:`color`
+            The color of the button when the mouse is over it.
+        useblit : bool, default: True
+            Use blitting for faster drawing if supported by the backend.
+            See the tutorial :ref:`blitting` for details.
+
+            .. versionadded:: 3.7
+        """
+        super().__init__(ax)
+
+        if image is not None:
+            ax.imshow(image)
+        self.label = ax.text(0.5, 0.5, label,
+                             verticalalignment='center',
+                             horizontalalignment='center',
+                             transform=ax.transAxes)
+
+        self._useblit = useblit and self.canvas.supports_blit
+
+        self._observers = cbook.CallbackRegistry(signals=["clicked"])
+
+        self.connect_event('button_press_event', self._click)
+        self.connect_event('button_release_event', self._release)
+        self.connect_event('motion_notify_event', self._motion)
+        ax.set_navigate(False)
+        ax.set_facecolor(color)
+        ax.set_xticks([])
+        ax.set_yticks([])
+        self.color = color
+        self.hovercolor = hovercolor
+
+    def _click(self, event):
+        if not self.eventson or self.ignore(event) or not self.ax.contains(event)[0]:
+            return
+        if event.canvas.mouse_grabber != self.ax:
+            event.canvas.grab_mouse(self.ax)
+
+    def _release(self, event):
+        if self.ignore(event) or event.canvas.mouse_grabber != self.ax:
+            return
+        event.canvas.release_mouse(self.ax)
+        if self.eventson and self.ax.contains(event)[0]:
+            self._observers.process('clicked', event)
+
+    def _motion(self, event):
+        if self.ignore(event):
+            return
+        c = self.hovercolor if self.ax.contains(event)[0] else self.color
+        if not colors.same_color(c, self.ax.get_facecolor()):
+            self.ax.set_facecolor(c)
+            if self.drawon:
+                if self._useblit:
+                    self.ax.draw_artist(self.ax)
+                    self.canvas.blit(self.ax.bbox)
+                else:
+                    self.canvas.draw()
+
+    def on_clicked(self, func):
+        """
+        Connect the callback function *func* to button click events.
+
+        Returns a connection id, which can be used to disconnect the callback.
+        """
+        return self._observers.connect('clicked', lambda event: func(event))
+
+    def disconnect(self, cid):
+        """Remove the callback function with connection id *cid*."""
+        self._observers.disconnect(cid)
+
+
+class SliderBase(AxesWidget):
+    """
+    The base class for constructing Slider widgets. Not intended for direct
+    usage.
+
+    For the slider to remain responsive you must maintain a reference to it.
+    """
+    def __init__(self, ax, orientation, closedmin, closedmax,
+                 valmin, valmax, valfmt, dragging, valstep):
+        if ax.name == '3d':
+            raise ValueError('Sliders cannot be added to 3D Axes')
+
+        super().__init__(ax)
+        _api.check_in_list(['horizontal', 'vertical'], orientation=orientation)
+
+        self.orientation = orientation
+        self.closedmin = closedmin
+        self.closedmax = closedmax
+        self.valmin = valmin
+        self.valmax = valmax
+        self.valstep = valstep
+        self.drag_active = False
+        self.valfmt = valfmt
+
+        if orientation == "vertical":
+            ax.set_ylim((valmin, valmax))
+            axis = ax.yaxis
+        else:
+            ax.set_xlim((valmin, valmax))
+            axis = ax.xaxis
+
+        self._fmt = axis.get_major_formatter()
+        if not isinstance(self._fmt, ticker.ScalarFormatter):
+            self._fmt = ticker.ScalarFormatter()
+            self._fmt.set_axis(axis)
+        self._fmt.set_useOffset(False)  # No additive offset.
+        self._fmt.set_useMathText(True)  # x sign before multiplicative offset.
+
+        ax.set_axis_off()
+        ax.set_navigate(False)
+
+        self.connect_event("button_press_event", self._update)
+        self.connect_event("button_release_event", self._update)
+        if dragging:
+            self.connect_event("motion_notify_event", self._update)
+        self._observers = cbook.CallbackRegistry(signals=["changed"])
+
+    def _stepped_value(self, val):
+        """Return *val* coerced to closest number in the ``valstep`` grid."""
+        if isinstance(self.valstep, Number):
+            val = (self.valmin
+                   + round((val - self.valmin) / self.valstep) * self.valstep)
+        elif self.valstep is not None:
+            valstep = np.asanyarray(self.valstep)
+            if valstep.ndim != 1:
+                raise ValueError(
+                    f"valstep must have 1 dimension but has {valstep.ndim}"
+                )
+            val = valstep[np.argmin(np.abs(valstep - val))]
+        return val
+
+    def disconnect(self, cid):
+        """
+        Remove the observer with connection id *cid*.
+
+        Parameters
+        ----------
+        cid : int
+            Connection id of the observer to be removed.
+        """
+        self._observers.disconnect(cid)
+
+    def reset(self):
+        """Reset the slider to the initial value."""
+        if np.any(self.val != self.valinit):
+            self.set_val(self.valinit)
+
+
+class Slider(SliderBase):
+    """
+    A slider representing a floating point range.
+
+    Create a slider from *valmin* to *valmax* in Axes *ax*. For the slider to
+    remain responsive you must maintain a reference to it. Call
+    :meth:`on_changed` to connect to the slider event.
+
+    Attributes
+    ----------
+    val : float
+        Slider value.
+    """
+
+    def __init__(self, ax, label, valmin, valmax, *, valinit=0.5, valfmt=None,
+                 closedmin=True, closedmax=True, slidermin=None,
+                 slidermax=None, dragging=True, valstep=None,
+                 orientation='horizontal', initcolor='r',
+                 track_color='lightgrey', handle_style=None, **kwargs):
+        """
+        Parameters
+        ----------
+        ax : Axes
+            The Axes to put the slider in.
+
+        label : str
+            Slider label.
+
+        valmin : float
+            The minimum value of the slider.
+
+        valmax : float
+            The maximum value of the slider.
+
+        valinit : float, default: 0.5
+            The slider initial position.
+
+        valfmt : str, default: None
+            %-format string used to format the slider value.  If None, a
+            `.ScalarFormatter` is used instead.
+
+        closedmin : bool, default: True
+            Whether the slider interval is closed on the bottom.
+
+        closedmax : bool, default: True
+            Whether the slider interval is closed on the top.
+
+        slidermin : Slider, default: None
+            Do not allow the current slider to have a value less than
+            the value of the Slider *slidermin*.
+
+        slidermax : Slider, default: None
+            Do not allow the current slider to have a value greater than
+            the value of the Slider *slidermax*.
+
+        dragging : bool, default: True
+            If True the slider can be dragged by the mouse.
+
+        valstep : float or array-like, default: None
+            If a float, the slider will snap to multiples of *valstep*.
+            If an array the slider will snap to the values in the array.
+
+        orientation : {'horizontal', 'vertical'}, default: 'horizontal'
+            The orientation of the slider.
+
+        initcolor : :mpltype:`color`, default: 'r'
+            The color of the line at the *valinit* position. Set to ``'none'``
+            for no line.
+
+        track_color : :mpltype:`color`, default: 'lightgrey'
+            The color of the background track. The track is accessible for
+            further styling via the *track* attribute.
+
+        handle_style : dict
+            Properties of the slider handle. Default values are
+
+            ========= ===== ======= ========================================
+            Key       Value Default Description
+            ========= ===== ======= ========================================
+            facecolor color 'white' The facecolor of the slider handle.
+            edgecolor color '.75'   The edgecolor of the slider handle.
+            size      int   10      The size of the slider handle in points.
+            ========= ===== ======= ========================================
+
+            Other values will be transformed as marker{foo} and passed to the
+            `~.Line2D` constructor. e.g. ``handle_style = {'style'='x'}`` will
+            result in ``markerstyle = 'x'``.
+
+        Notes
+        -----
+        Additional kwargs are passed on to ``self.poly`` which is the
+        `~matplotlib.patches.Rectangle` that draws the slider knob.  See the
+        `.Rectangle` documentation for valid property names (``facecolor``,
+        ``edgecolor``, ``alpha``, etc.).
+        """
+        super().__init__(ax, orientation, closedmin, closedmax,
+                         valmin, valmax, valfmt, dragging, valstep)
+
+        if slidermin is not None and not hasattr(slidermin, 'val'):
+            raise ValueError(
+                f"Argument slidermin ({type(slidermin)}) has no 'val'")
+        if slidermax is not None and not hasattr(slidermax, 'val'):
+            raise ValueError(
+                f"Argument slidermax ({type(slidermax)}) has no 'val'")
+        self.slidermin = slidermin
+        self.slidermax = slidermax
+        valinit = self._value_in_bounds(valinit)
+        if valinit is None:
+            valinit = valmin
+        self.val = valinit
+        self.valinit = valinit
+
+        defaults = {'facecolor': 'white', 'edgecolor': '.75', 'size': 10}
+        handle_style = {} if handle_style is None else handle_style
+        marker_props = {
+            f'marker{k}': v for k, v in {**defaults, **handle_style}.items()
+        }
+
+        if orientation == 'vertical':
+            self.track = Rectangle(
+                (.25, 0), .5, 1,
+                transform=ax.transAxes,
+                facecolor=track_color
+            )
+            ax.add_patch(self.track)
+            self.poly = ax.axhspan(valmin, valinit, .25, .75, **kwargs)
+            # Drawing a longer line and clipping it to the track avoids
+            # pixelation-related asymmetries.
+            self.hline = ax.axhline(valinit, 0, 1, color=initcolor, lw=1,
+                                    clip_path=TransformedPatchPath(self.track))
+            handleXY = [[0.5], [valinit]]
+        else:
+            self.track = Rectangle(
+                (0, .25), 1, .5,
+                transform=ax.transAxes,
+                facecolor=track_color
+            )
+            ax.add_patch(self.track)
+            self.poly = ax.axvspan(valmin, valinit, .25, .75, **kwargs)
+            self.vline = ax.axvline(valinit, 0, 1, color=initcolor, lw=1,
+                                    clip_path=TransformedPatchPath(self.track))
+            handleXY = [[valinit], [0.5]]
+        self._handle, = ax.plot(
+            *handleXY,
+            "o",
+            **marker_props,
+            clip_on=False
+        )
+
+        if orientation == 'vertical':
+            self.label = ax.text(0.5, 1.02, label, transform=ax.transAxes,
+                                 verticalalignment='bottom',
+                                 horizontalalignment='center')
+
+            self.valtext = ax.text(0.5, -0.02, self._format(valinit),
+                                   transform=ax.transAxes,
+                                   verticalalignment='top',
+                                   horizontalalignment='center')
+        else:
+            self.label = ax.text(-0.02, 0.5, label, transform=ax.transAxes,
+                                 verticalalignment='center',
+                                 horizontalalignment='right')
+
+            self.valtext = ax.text(1.02, 0.5, self._format(valinit),
+                                   transform=ax.transAxes,
+                                   verticalalignment='center',
+                                   horizontalalignment='left')
+
+        self.set_val(valinit)
+
+    def _value_in_bounds(self, val):
+        """Makes sure *val* is with given bounds."""
+        val = self._stepped_value(val)
+
+        if val <= self.valmin:
+            if not self.closedmin:
+                return
+            val = self.valmin
+        elif val >= self.valmax:
+            if not self.closedmax:
+                return
+            val = self.valmax
+
+        if self.slidermin is not None and val <= self.slidermin.val:
+            if not self.closedmin:
+                return
+            val = self.slidermin.val
+
+        if self.slidermax is not None and val >= self.slidermax.val:
+            if not self.closedmax:
+                return
+            val = self.slidermax.val
+        return val
+
+    def _update(self, event):
+        """Update the slider position."""
+        if self.ignore(event) or event.button != 1:
+            return
+
+        if event.name == 'button_press_event' and self.ax.contains(event)[0]:
+            self.drag_active = True
+            event.canvas.grab_mouse(self.ax)
+
+        if not self.drag_active:
+            return
+
+        if (event.name == 'button_release_event'
+              or event.name == 'button_press_event' and not self.ax.contains(event)[0]):
+            self.drag_active = False
+            event.canvas.release_mouse(self.ax)
+            return
+
+        xdata, ydata = self._get_data_coords(event)
+        val = self._value_in_bounds(
+            xdata if self.orientation == 'horizontal' else ydata)
+        if val not in [None, self.val]:
+            self.set_val(val)
+
+    def _format(self, val):
+        """Pretty-print *val*."""
+        if self.valfmt is not None:
+            return self.valfmt % val
+        else:
+            _, s, _ = self._fmt.format_ticks([self.valmin, val, self.valmax])
+            # fmt.get_offset is actually the multiplicative factor, if any.
+            return s + self._fmt.get_offset()
+
+    def set_val(self, val):
+        """
+        Set slider value to *val*.
+
+        Parameters
+        ----------
+        val : float
+        """
+        if self.orientation == 'vertical':
+            self.poly.set_height(val - self.poly.get_y())
+            self._handle.set_ydata([val])
+        else:
+            self.poly.set_width(val - self.poly.get_x())
+            self._handle.set_xdata([val])
+        self.valtext.set_text(self._format(val))
+        if self.drawon:
+            self.ax.get_figure(root=True).canvas.draw_idle()
+        self.val = val
+        if self.eventson:
+            self._observers.process('changed', val)
+
+    def on_changed(self, func):
+        """
+        Connect *func* as callback function to changes of the slider value.
+
+        Parameters
+        ----------
+        func : callable
+            Function to call when slider is changed.
+            The function must accept a single float as its arguments.
+
+        Returns
+        -------
+        int
+            Connection id (which can be used to disconnect *func*).
+        """
+        return self._observers.connect('changed', lambda val: func(val))
+
+
+class RangeSlider(SliderBase):
+    """
+    A slider representing a range of floating point values. Defines the min and
+    max of the range via the *val* attribute as a tuple of (min, max).
+
+    Create a slider that defines a range contained within [*valmin*, *valmax*]
+    in Axes *ax*. For the slider to remain responsive you must maintain a
+    reference to it. Call :meth:`on_changed` to connect to the slider event.
+
+    Attributes
+    ----------
+    val : tuple of float
+        Slider value.
+    """
+
+    def __init__(
+        self,
+        ax,
+        label,
+        valmin,
+        valmax,
+        *,
+        valinit=None,
+        valfmt=None,
+        closedmin=True,
+        closedmax=True,
+        dragging=True,
+        valstep=None,
+        orientation="horizontal",
+        track_color='lightgrey',
+        handle_style=None,
+        **kwargs,
+    ):
+        """
+        Parameters
+        ----------
+        ax : Axes
+            The Axes to put the slider in.
+
+        label : str
+            Slider label.
+
+        valmin : float
+            The minimum value of the slider.
+
+        valmax : float
+            The maximum value of the slider.
+
+        valinit : tuple of float or None, default: None
+            The initial positions of the slider. If None the initial positions
+            will be at the 25th and 75th percentiles of the range.
+
+        valfmt : str, default: None
+            %-format string used to format the slider values.  If None, a
+            `.ScalarFormatter` is used instead.
+
+        closedmin : bool, default: True
+            Whether the slider interval is closed on the bottom.
+
+        closedmax : bool, default: True
+            Whether the slider interval is closed on the top.
+
+        dragging : bool, default: True
+            If True the slider can be dragged by the mouse.
+
+        valstep : float, default: None
+            If given, the slider will snap to multiples of *valstep*.
+
+        orientation : {'horizontal', 'vertical'}, default: 'horizontal'
+            The orientation of the slider.
+
+        track_color : :mpltype:`color`, default: 'lightgrey'
+            The color of the background track. The track is accessible for
+            further styling via the *track* attribute.
+
+        handle_style : dict
+            Properties of the slider handles. Default values are
+
+            ========= ===== ======= =========================================
+            Key       Value Default Description
+            ========= ===== ======= =========================================
+            facecolor color 'white' The facecolor of the slider handles.
+            edgecolor color '.75'   The edgecolor of the slider handles.
+            size      int   10      The size of the slider handles in points.
+            ========= ===== ======= =========================================
+
+            Other values will be transformed as marker{foo} and passed to the
+            `~.Line2D` constructor. e.g. ``handle_style = {'style'='x'}`` will
+            result in ``markerstyle = 'x'``.
+
+        Notes
+        -----
+        Additional kwargs are passed on to ``self.poly`` which is the
+        `~matplotlib.patches.Polygon` that draws the slider knob.  See the
+        `.Polygon` documentation for valid property names (``facecolor``,
+        ``edgecolor``, ``alpha``, etc.).
+        """
+        super().__init__(ax, orientation, closedmin, closedmax,
+                         valmin, valmax, valfmt, dragging, valstep)
+
+        # Set a value to allow _value_in_bounds() to work.
+        self.val = (valmin, valmax)
+        if valinit is None:
+            # Place at the 25th and 75th percentiles
+            extent = valmax - valmin
+            valinit = np.array([valmin + extent * 0.25,
+                                valmin + extent * 0.75])
+        else:
+            valinit = self._value_in_bounds(valinit)
+        self.val = valinit
+        self.valinit = valinit
+
+        defaults = {'facecolor': 'white', 'edgecolor': '.75', 'size': 10}
+        handle_style = {} if handle_style is None else handle_style
+        marker_props = {
+            f'marker{k}': v for k, v in {**defaults, **handle_style}.items()
+        }
+
+        if orientation == "vertical":
+            self.track = Rectangle(
+                (.25, 0), .5, 2,
+                transform=ax.transAxes,
+                facecolor=track_color
+            )
+            ax.add_patch(self.track)
+            poly_transform = self.ax.get_yaxis_transform(which="grid")
+            handleXY_1 = [.5, valinit[0]]
+            handleXY_2 = [.5, valinit[1]]
+        else:
+            self.track = Rectangle(
+                (0, .25), 1, .5,
+                transform=ax.transAxes,
+                facecolor=track_color
+            )
+            ax.add_patch(self.track)
+            poly_transform = self.ax.get_xaxis_transform(which="grid")
+            handleXY_1 = [valinit[0], .5]
+            handleXY_2 = [valinit[1], .5]
+        self.poly = Polygon(np.zeros([5, 2]), **kwargs)
+        self._update_selection_poly(*valinit)
+        self.poly.set_transform(poly_transform)
+        self.poly.get_path()._interpolation_steps = 100
+        self.ax.add_patch(self.poly)
+        self.ax._request_autoscale_view()
+        self._handles = [
+            ax.plot(
+                *handleXY_1,
+                "o",
+                **marker_props,
+                clip_on=False
+            )[0],
+            ax.plot(
+                *handleXY_2,
+                "o",
+                **marker_props,
+                clip_on=False
+            )[0]
+        ]
+
+        if orientation == "vertical":
+            self.label = ax.text(
+                0.5,
+                1.02,
+                label,
+                transform=ax.transAxes,
+                verticalalignment="bottom",
+                horizontalalignment="center",
+            )
+
+            self.valtext = ax.text(
+                0.5,
+                -0.02,
+                self._format(valinit),
+                transform=ax.transAxes,
+                verticalalignment="top",
+                horizontalalignment="center",
+            )
+        else:
+            self.label = ax.text(
+                -0.02,
+                0.5,
+                label,
+                transform=ax.transAxes,
+                verticalalignment="center",
+                horizontalalignment="right",
+            )
+
+            self.valtext = ax.text(
+                1.02,
+                0.5,
+                self._format(valinit),
+                transform=ax.transAxes,
+                verticalalignment="center",
+                horizontalalignment="left",
+            )
+
+        self._active_handle = None
+        self.set_val(valinit)
+
+    def _update_selection_poly(self, vmin, vmax):
+        """
+        Update the vertices of the *self.poly* slider in-place
+        to cover the data range *vmin*, *vmax*.
+        """
+        # The vertices are positioned
+        #  1 ------ 2
+        #  |        |
+        # 0, 4 ---- 3
+        verts = self.poly.xy
+        if self.orientation == "vertical":
+            verts[0] = verts[4] = .25, vmin
+            verts[1] = .25, vmax
+            verts[2] = .75, vmax
+            verts[3] = .75, vmin
+        else:
+            verts[0] = verts[4] = vmin, .25
+            verts[1] = vmin, .75
+            verts[2] = vmax, .75
+            verts[3] = vmax, .25
+
+    def _min_in_bounds(self, min):
+        """Ensure the new min value is between valmin and self.val[1]."""
+        if min <= self.valmin:
+            if not self.closedmin:
+                return self.val[0]
+            min = self.valmin
+
+        if min > self.val[1]:
+            min = self.val[1]
+        return self._stepped_value(min)
+
+    def _max_in_bounds(self, max):
+        """Ensure the new max value is between valmax and self.val[0]."""
+        if max >= self.valmax:
+            if not self.closedmax:
+                return self.val[1]
+            max = self.valmax
+
+        if max <= self.val[0]:
+            max = self.val[0]
+        return self._stepped_value(max)
+
+    def _value_in_bounds(self, vals):
+        """Clip min, max values to the bounds."""
+        return (self._min_in_bounds(vals[0]), self._max_in_bounds(vals[1]))
+
+    def _update_val_from_pos(self, pos):
+        """Update the slider value based on a given position."""
+        idx = np.argmin(np.abs(self.val - pos))
+        if idx == 0:
+            val = self._min_in_bounds(pos)
+            self.set_min(val)
+        else:
+            val = self._max_in_bounds(pos)
+            self.set_max(val)
+        if self._active_handle:
+            if self.orientation == "vertical":
+                self._active_handle.set_ydata([val])
+            else:
+                self._active_handle.set_xdata([val])
+
+    def _update(self, event):
+        """Update the slider position."""
+        if self.ignore(event) or event.button != 1:
+            return
+
+        if event.name == "button_press_event" and self.ax.contains(event)[0]:
+            self.drag_active = True
+            event.canvas.grab_mouse(self.ax)
+
+        if not self.drag_active:
+            return
+
+        if (event.name == "button_release_event"
+              or event.name == "button_press_event" and not self.ax.contains(event)[0]):
+            self.drag_active = False
+            event.canvas.release_mouse(self.ax)
+            self._active_handle = None
+            return
+
+        # determine which handle was grabbed
+        xdata, ydata = self._get_data_coords(event)
+        handle_index = np.argmin(np.abs(
+            [h.get_xdata()[0] - xdata for h in self._handles]
+            if self.orientation == "horizontal" else
+            [h.get_ydata()[0] - ydata for h in self._handles]))
+        handle = self._handles[handle_index]
+
+        # these checks ensure smooth behavior if the handles swap which one
+        # has a higher value. i.e. if one is dragged over and past the other.
+        if handle is not self._active_handle:
+            self._active_handle = handle
+
+        self._update_val_from_pos(xdata if self.orientation == "horizontal" else ydata)
+
+    def _format(self, val):
+        """Pretty-print *val*."""
+        if self.valfmt is not None:
+            return f"({self.valfmt % val[0]}, {self.valfmt % val[1]})"
+        else:
+            _, s1, s2, _ = self._fmt.format_ticks(
+                [self.valmin, *val, self.valmax]
+            )
+            # fmt.get_offset is actually the multiplicative factor, if any.
+            s1 += self._fmt.get_offset()
+            s2 += self._fmt.get_offset()
+            # Use f string to avoid issues with backslashes when cast to a str
+            return f"({s1}, {s2})"
+
+    def set_min(self, min):
+        """
+        Set the lower value of the slider to *min*.
+
+        Parameters
+        ----------
+        min : float
+        """
+        self.set_val((min, self.val[1]))
+
+    def set_max(self, max):
+        """
+        Set the lower value of the slider to *max*.
+
+        Parameters
+        ----------
+        max : float
+        """
+        self.set_val((self.val[0], max))
+
+    def set_val(self, val):
+        """
+        Set slider value to *val*.
+
+        Parameters
+        ----------
+        val : tuple or array-like of float
+        """
+        val = np.sort(val)
+        _api.check_shape((2,), val=val)
+        # Reset value to allow _value_in_bounds() to work.
+        self.val = (self.valmin, self.valmax)
+        vmin, vmax = self._value_in_bounds(val)
+        self._update_selection_poly(vmin, vmax)
+        if self.orientation == "vertical":
+            self._handles[0].set_ydata([vmin])
+            self._handles[1].set_ydata([vmax])
+        else:
+            self._handles[0].set_xdata([vmin])
+            self._handles[1].set_xdata([vmax])
+
+        self.valtext.set_text(self._format((vmin, vmax)))
+
+        if self.drawon:
+            self.ax.get_figure(root=True).canvas.draw_idle()
+        self.val = (vmin, vmax)
+        if self.eventson:
+            self._observers.process("changed", (vmin, vmax))
+
+    def on_changed(self, func):
+        """
+        Connect *func* as callback function to changes of the slider value.
+
+        Parameters
+        ----------
+        func : callable
+            Function to call when slider is changed. The function
+            must accept a 2-tuple of floats as its argument.
+
+        Returns
+        -------
+        int
+            Connection id (which can be used to disconnect *func*).
+        """
+        return self._observers.connect('changed', lambda val: func(val))
+
+
+def _expand_text_props(props):
+    props = cbook.normalize_kwargs(props, mtext.Text)
+    return cycler(**props)() if props else itertools.repeat({})
+
+
+class CheckButtons(AxesWidget):
+    r"""
+    A GUI neutral set of check buttons.
+
+    For the check buttons to remain responsive you must keep a
+    reference to this object.
+
+    Connect to the CheckButtons with the `.on_clicked` method.
+
+    Attributes
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    labels : list of `~matplotlib.text.Text`
+        The text label objects of the check buttons.
+    """
+
+    def __init__(self, ax, labels, actives=None, *, useblit=True,
+                 label_props=None, frame_props=None, check_props=None):
+        """
+        Add check buttons to `~.axes.Axes` instance *ax*.
+
+        Parameters
+        ----------
+        ax : `~matplotlib.axes.Axes`
+            The parent Axes for the widget.
+        labels : list of str
+            The labels of the check buttons.
+        actives : list of bool, optional
+            The initial check states of the buttons. The list must have the
+            same length as *labels*. If not given, all buttons are unchecked.
+        useblit : bool, default: True
+            Use blitting for faster drawing if supported by the backend.
+            See the tutorial :ref:`blitting` for details.
+
+            .. versionadded:: 3.7
+
+        label_props : dict, optional
+            Dictionary of `.Text` properties to be used for the labels.
+
+            .. versionadded:: 3.7
+        frame_props : dict, optional
+            Dictionary of scatter `.Collection` properties to be used for the
+            check button frame. Defaults (label font size / 2)**2 size, black
+            edgecolor, no facecolor, and 1.0 linewidth.
+
+            .. versionadded:: 3.7
+        check_props : dict, optional
+            Dictionary of scatter `.Collection` properties to be used for the
+            check button check. Defaults to (label font size / 2)**2 size,
+            black color, and 1.0 linewidth.
+
+            .. versionadded:: 3.7
+        """
+        super().__init__(ax)
+
+        _api.check_isinstance((dict, None), label_props=label_props,
+                              frame_props=frame_props, check_props=check_props)
+
+        ax.set_xticks([])
+        ax.set_yticks([])
+        ax.set_navigate(False)
+
+        if actives is None:
+            actives = [False] * len(labels)
+
+        self._useblit = useblit and self.canvas.supports_blit
+        self._background = None
+
+        ys = np.linspace(1, 0, len(labels)+2)[1:-1]
+
+        label_props = _expand_text_props(label_props)
+        self.labels = [
+            ax.text(0.25, y, label, transform=ax.transAxes,
+                    horizontalalignment="left", verticalalignment="center",
+                    **props)
+            for y, label, props in zip(ys, labels, label_props)]
+        text_size = np.array([text.get_fontsize() for text in self.labels]) / 2
+
+        frame_props = {
+            's': text_size**2,
+            'linewidth': 1,
+            **cbook.normalize_kwargs(frame_props, collections.PathCollection),
+            'marker': 's',
+            'transform': ax.transAxes,
+        }
+        frame_props.setdefault('facecolor', frame_props.get('color', 'none'))
+        frame_props.setdefault('edgecolor', frame_props.pop('color', 'black'))
+        self._frames = ax.scatter([0.15] * len(ys), ys, **frame_props)
+        check_props = {
+            'linewidth': 1,
+            's': text_size**2,
+            **cbook.normalize_kwargs(check_props, collections.PathCollection),
+            'marker': 'x',
+            'transform': ax.transAxes,
+            'animated': self._useblit,
+        }
+        check_props.setdefault('facecolor', check_props.pop('color', 'black'))
+        self._checks = ax.scatter([0.15] * len(ys), ys, **check_props)
+        # The user may have passed custom colours in check_props, so we need to
+        # create the checks (above), and modify the visibility after getting
+        # whatever the user set.
+        self._init_status(actives)
+
+        self.connect_event('button_press_event', self._clicked)
+        if self._useblit:
+            self.connect_event('draw_event', self._clear)
+
+        self._observers = cbook.CallbackRegistry(signals=["clicked"])
+
+    def _clear(self, event):
+        """Internal event handler to clear the buttons."""
+        if self.ignore(event) or self.canvas.is_saving():
+            return
+        self._background = self.canvas.copy_from_bbox(self.ax.bbox)
+        self.ax.draw_artist(self._checks)
+
+    def _clicked(self, event):
+        if self.ignore(event) or event.button != 1 or not self.ax.contains(event)[0]:
+            return
+        idxs = [  # Indices of frames and of texts that contain the event.
+            *self._frames.contains(event)[1]["ind"],
+            *[i for i, text in enumerate(self.labels) if text.contains(event)[0]]]
+        if idxs:
+            coords = self._frames.get_offset_transform().transform(
+                self._frames.get_offsets())
+            self.set_active(  # Closest index, only looking in idxs.
+                idxs[(((event.x, event.y) - coords[idxs]) ** 2).sum(-1).argmin()])
+
+    def set_label_props(self, props):
+        """
+        Set properties of the `.Text` labels.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        props : dict
+            Dictionary of `.Text` properties to be used for the labels.
+        """
+        _api.check_isinstance(dict, props=props)
+        props = _expand_text_props(props)
+        for text, prop in zip(self.labels, props):
+            text.update(prop)
+
+    def set_frame_props(self, props):
+        """
+        Set properties of the check button frames.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        props : dict
+            Dictionary of `.Collection` properties to be used for the check
+            button frames.
+        """
+        _api.check_isinstance(dict, props=props)
+        if 's' in props:  # Keep API consistent with constructor.
+            props['sizes'] = np.broadcast_to(props.pop('s'), len(self.labels))
+        self._frames.update(props)
+
+    def set_check_props(self, props):
+        """
+        Set properties of the check button checks.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        props : dict
+            Dictionary of `.Collection` properties to be used for the check
+            button check.
+        """
+        _api.check_isinstance(dict, props=props)
+        if 's' in props:  # Keep API consistent with constructor.
+            props['sizes'] = np.broadcast_to(props.pop('s'), len(self.labels))
+        actives = self.get_status()
+        self._checks.update(props)
+        # If new colours are supplied, then we must re-apply the status.
+        self._init_status(actives)
+
+    def set_active(self, index, state=None):
+        """
+        Modify the state of a check button by index.
+
+        Callbacks will be triggered if :attr:`eventson` is True.
+
+        Parameters
+        ----------
+        index : int
+            Index of the check button to toggle.
+
+        state : bool, optional
+            If a boolean value, set the state explicitly. If no value is
+            provided, the state is toggled.
+
+        Raises
+        ------
+        ValueError
+            If *index* is invalid.
+        TypeError
+            If *state* is not boolean.
+        """
+        if index not in range(len(self.labels)):
+            raise ValueError(f'Invalid CheckButton index: {index}')
+        _api.check_isinstance((bool, None), state=state)
+
+        invisible = colors.to_rgba('none')
+
+        facecolors = self._checks.get_facecolor()
+        if state is None:
+            state = colors.same_color(facecolors[index], invisible)
+        facecolors[index] = self._active_check_colors[index] if state else invisible
+        self._checks.set_facecolor(facecolors)
+
+        if self.drawon:
+            if self._useblit:
+                if self._background is not None:
+                    self.canvas.restore_region(self._background)
+                self.ax.draw_artist(self._checks)
+                self.canvas.blit(self.ax.bbox)
+            else:
+                self.canvas.draw()
+
+        if self.eventson:
+            self._observers.process('clicked', self.labels[index].get_text())
+
+    def _init_status(self, actives):
+        """
+        Initialize properties to match active status.
+
+        The user may have passed custom colours in *check_props* to the
+        constructor, or to `.set_check_props`, so we need to modify the
+        visibility after getting whatever the user set.
+        """
+        self._active_check_colors = self._checks.get_facecolor()
+        if len(self._active_check_colors) == 1:
+            self._active_check_colors = np.repeat(self._active_check_colors,
+                                                  len(actives), axis=0)
+        self._checks.set_facecolor(
+            [ec if active else "none"
+             for ec, active in zip(self._active_check_colors, actives)])
+
+    def clear(self):
+        """Uncheck all checkboxes."""
+
+        self._checks.set_facecolor(['none'] * len(self._active_check_colors))
+
+        if hasattr(self, '_lines'):
+            for l1, l2 in self._lines:
+                l1.set_visible(False)
+                l2.set_visible(False)
+
+        if self.drawon:
+            self.canvas.draw()
+
+        if self.eventson:
+            # Call with no label, as all checkboxes are being cleared.
+            self._observers.process('clicked', None)
+
+    def get_status(self):
+        """
+        Return a list of the status (True/False) of all of the check buttons.
+        """
+        return [not colors.same_color(color, colors.to_rgba("none"))
+                for color in self._checks.get_facecolors()]
+
+    def get_checked_labels(self):
+        """Return a list of labels currently checked by user."""
+
+        return [l.get_text() for l, box_checked in
+                zip(self.labels, self.get_status())
+                if box_checked]
+
+    def on_clicked(self, func):
+        """
+        Connect the callback function *func* to button click events.
+
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
+        """
+        return self._observers.connect('clicked', lambda text: func(text))
+
+    def disconnect(self, cid):
+        """Remove the observer with connection id *cid*."""
+        self._observers.disconnect(cid)
+
+
+class TextBox(AxesWidget):
+    """
+    A GUI neutral text input box.
+
+    For the text box to remain responsive you must keep a reference to it.
+
+    Call `.on_text_change` to be updated whenever the text changes.
+
+    Call `.on_submit` to be updated whenever the user hits enter or
+    leaves the text entry field.
+
+    Attributes
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    label : `~matplotlib.text.Text`
+
+    color : :mpltype:`color`
+        The color of the text box when not hovering.
+    hovercolor : :mpltype:`color`
+        The color of the text box when hovering.
+    """
+
+    def __init__(self, ax, label, initial='', *,
+                 color='.95', hovercolor='1', label_pad=.01,
+                 textalignment="left"):
+        """
+        Parameters
+        ----------
+        ax : `~matplotlib.axes.Axes`
+            The `~.axes.Axes` instance the button will be placed into.
+        label : str
+            Label for this text box.
+        initial : str
+            Initial value in the text box.
+        color : :mpltype:`color`
+            The color of the box.
+        hovercolor : :mpltype:`color`
+            The color of the box when the mouse is over it.
+        label_pad : float
+            The distance between the label and the right side of the textbox.
+        textalignment : {'left', 'center', 'right'}
+            The horizontal location of the text.
+        """
+        super().__init__(ax)
+
+        self._text_position = _api.check_getitem(
+            {"left": 0.05, "center": 0.5, "right": 0.95},
+            textalignment=textalignment)
+
+        self.label = ax.text(
+            -label_pad, 0.5, label, transform=ax.transAxes,
+            verticalalignment='center', horizontalalignment='right')
+
+        # TextBox's text object should not parse mathtext at all.
+        self.text_disp = self.ax.text(
+            self._text_position, 0.5, initial, transform=self.ax.transAxes,
+            verticalalignment='center', horizontalalignment=textalignment,
+            parse_math=False)
+
+        self._observers = cbook.CallbackRegistry(signals=["change", "submit"])
+
+        ax.set(
+            xlim=(0, 1), ylim=(0, 1),  # s.t. cursor appears from first click.
+            navigate=False, facecolor=color,
+            xticks=[], yticks=[])
+
+        self.cursor_index = 0
+
+        self.cursor = ax.vlines(0, 0, 0, visible=False, color="k", lw=1,
+                                transform=mpl.transforms.IdentityTransform())
+
+        self.connect_event('button_press_event', self._click)
+        self.connect_event('button_release_event', self._release)
+        self.connect_event('motion_notify_event', self._motion)
+        self.connect_event('key_press_event', self._keypress)
+        self.connect_event('resize_event', self._resize)
+
+        self.color = color
+        self.hovercolor = hovercolor
+
+        self.capturekeystrokes = False
+
+    @property
+    def text(self):
+        return self.text_disp.get_text()
+
+    def _rendercursor(self):
+        # this is a hack to figure out where the cursor should go.
+        # we draw the text up to where the cursor should go, measure
+        # and save its dimensions, draw the real text, then put the cursor
+        # at the saved dimensions
+
+        # This causes a single extra draw if the figure has never been rendered
+        # yet, which should be fine as we're going to repeatedly re-render the
+        # figure later anyways.
+        fig = self.ax.get_figure(root=True)
+        if fig._get_renderer() is None:
+            fig.canvas.draw()
+
+        text = self.text_disp.get_text()  # Save value before overwriting it.
+        widthtext = text[:self.cursor_index]
+
+        bb_text = self.text_disp.get_window_extent()
+        self.text_disp.set_text(widthtext or ",")
+        bb_widthtext = self.text_disp.get_window_extent()
+
+        if bb_text.y0 == bb_text.y1:  # Restoring the height if no text.
+            bb_text.y0 -= bb_widthtext.height / 2
+            bb_text.y1 += bb_widthtext.height / 2
+        elif not widthtext:  # Keep width to 0.
+            bb_text.x1 = bb_text.x0
+        else:  # Move the cursor using width of bb_widthtext.
+            bb_text.x1 = bb_text.x0 + bb_widthtext.width
+
+        self.cursor.set(
+            segments=[[(bb_text.x1, bb_text.y0), (bb_text.x1, bb_text.y1)]],
+            visible=True)
+        self.text_disp.set_text(text)
+
+        fig.canvas.draw()
+
+    def _release(self, event):
+        if self.ignore(event):
+            return
+        if event.canvas.mouse_grabber != self.ax:
+            return
+        event.canvas.release_mouse(self.ax)
+
+    def _keypress(self, event):
+        if self.ignore(event):
+            return
+        if self.capturekeystrokes:
+            key = event.key
+            text = self.text
+            if len(key) == 1:
+                text = (text[:self.cursor_index] + key +
+                        text[self.cursor_index:])
+                self.cursor_index += 1
+            elif key == "right":
+                if self.cursor_index != len(text):
+                    self.cursor_index += 1
+            elif key == "left":
+                if self.cursor_index != 0:
+                    self.cursor_index -= 1
+            elif key == "home":
+                self.cursor_index = 0
+            elif key == "end":
+                self.cursor_index = len(text)
+            elif key == "backspace":
+                if self.cursor_index != 0:
+                    text = (text[:self.cursor_index - 1] +
+                            text[self.cursor_index:])
+                    self.cursor_index -= 1
+            elif key == "delete":
+                if self.cursor_index != len(self.text):
+                    text = (text[:self.cursor_index] +
+                            text[self.cursor_index + 1:])
+            self.text_disp.set_text(text)
+            self._rendercursor()
+            if self.eventson:
+                self._observers.process('change', self.text)
+                if key in ["enter", "return"]:
+                    self._observers.process('submit', self.text)
+
+    def set_val(self, val):
+        newval = str(val)
+        if self.text == newval:
+            return
+        self.text_disp.set_text(newval)
+        self._rendercursor()
+        if self.eventson:
+            self._observers.process('change', self.text)
+            self._observers.process('submit', self.text)
+
+    def begin_typing(self):
+        self.capturekeystrokes = True
+        # Disable keypress shortcuts, which may otherwise cause the figure to
+        # be saved, closed, etc., until the user stops typing.  The way to
+        # achieve this depends on whether toolmanager is in use.
+        stack = ExitStack()  # Register cleanup actions when user stops typing.
+        self._on_stop_typing = stack.close
+        toolmanager = getattr(
+            self.ax.get_figure(root=True).canvas.manager, "toolmanager", None)
+        if toolmanager is not None:
+            # If using toolmanager, lock keypresses, and plan to release the
+            # lock when typing stops.
+            toolmanager.keypresslock(self)
+            stack.callback(toolmanager.keypresslock.release, self)
+        else:
+            # If not using toolmanager, disable all keypress-related rcParams.
+            # Avoid spurious warnings if keymaps are getting deprecated.
+            with _api.suppress_matplotlib_deprecation_warning():
+                stack.enter_context(mpl.rc_context(
+                    {k: [] for k in mpl.rcParams if k.startswith("keymap.")}))
+
+    def stop_typing(self):
+        if self.capturekeystrokes:
+            self._on_stop_typing()
+            self._on_stop_typing = None
+            notifysubmit = True
+        else:
+            notifysubmit = False
+        self.capturekeystrokes = False
+        self.cursor.set_visible(False)
+        self.ax.get_figure(root=True).canvas.draw()
+        if notifysubmit and self.eventson:
+            # Because process() might throw an error in the user's code, only
+            # call it once we've already done our cleanup.
+            self._observers.process('submit', self.text)
+
+    def _click(self, event):
+        if self.ignore(event):
+            return
+        if not self.ax.contains(event)[0]:
+            self.stop_typing()
+            return
+        if not self.eventson:
+            return
+        if event.canvas.mouse_grabber != self.ax:
+            event.canvas.grab_mouse(self.ax)
+        if not self.capturekeystrokes:
+            self.begin_typing()
+        self.cursor_index = self.text_disp._char_index_at(event.x)
+        self._rendercursor()
+
+    def _resize(self, event):
+        self.stop_typing()
+
+    def _motion(self, event):
+        if self.ignore(event):
+            return
+        c = self.hovercolor if self.ax.contains(event)[0] else self.color
+        if not colors.same_color(c, self.ax.get_facecolor()):
+            self.ax.set_facecolor(c)
+            if self.drawon:
+                self.ax.get_figure(root=True).canvas.draw()
+
+    def on_text_change(self, func):
+        """
+        When the text changes, call this *func* with event.
+
+        A connection id is returned which can be used to disconnect.
+        """
+        return self._observers.connect('change', lambda text: func(text))
+
+    def on_submit(self, func):
+        """
+        When the user hits enter or leaves the submission box, call this
+        *func* with event.
+
+        A connection id is returned which can be used to disconnect.
+        """
+        return self._observers.connect('submit', lambda text: func(text))
+
+    def disconnect(self, cid):
+        """Remove the observer with connection id *cid*."""
+        self._observers.disconnect(cid)
+
+
+class RadioButtons(AxesWidget):
+    """
+    A GUI neutral radio button.
+
+    For the buttons to remain responsive you must keep a reference to this
+    object.
+
+    Connect to the RadioButtons with the `.on_clicked` method.
+
+    Attributes
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    activecolor : :mpltype:`color`
+        The color of the selected button.
+    labels : list of `.Text`
+        The button labels.
+    value_selected : str
+        The label text of the currently selected button.
+    index_selected : int
+        The index of the selected button.
+    """
+
+    def __init__(self, ax, labels, active=0, activecolor=None, *,
+                 useblit=True, label_props=None, radio_props=None):
+        """
+        Add radio buttons to an `~.axes.Axes`.
+
+        Parameters
+        ----------
+        ax : `~matplotlib.axes.Axes`
+            The Axes to add the buttons to.
+        labels : list of str
+            The button labels.
+        active : int
+            The index of the initially selected button.
+        activecolor : :mpltype:`color`
+            The color of the selected button. The default is ``'blue'`` if not
+            specified here or in *radio_props*.
+        useblit : bool, default: True
+            Use blitting for faster drawing if supported by the backend.
+            See the tutorial :ref:`blitting` for details.
+
+            .. versionadded:: 3.7
+
+        label_props : dict or list of dict, optional
+            Dictionary of `.Text` properties to be used for the labels.
+
+            .. versionadded:: 3.7
+        radio_props : dict, optional
+            Dictionary of scatter `.Collection` properties to be used for the
+            radio buttons. Defaults to (label font size / 2)**2 size, black
+            edgecolor, and *activecolor* facecolor (when active).
+
+            .. note::
+                If a facecolor is supplied in *radio_props*, it will override
+                *activecolor*. This may be used to provide an active color per
+                button.
+
+            .. versionadded:: 3.7
+        """
+        super().__init__(ax)
+
+        _api.check_isinstance((dict, None), label_props=label_props,
+                              radio_props=radio_props)
+
+        radio_props = cbook.normalize_kwargs(radio_props,
+                                             collections.PathCollection)
+        if activecolor is not None:
+            if 'facecolor' in radio_props:
+                _api.warn_external(
+                    'Both the *activecolor* parameter and the *facecolor* '
+                    'key in the *radio_props* parameter has been specified. '
+                    '*activecolor* will be ignored.')
+        else:
+            activecolor = 'blue'  # Default.
+
+        self._activecolor = activecolor
+        self._initial_active = active
+        self.value_selected = labels[active]
+        self.index_selected = active
+
+        ax.set_xticks([])
+        ax.set_yticks([])
+        ax.set_navigate(False)
+
+        ys = np.linspace(1, 0, len(labels) + 2)[1:-1]
+
+        self._useblit = useblit and self.canvas.supports_blit
+        self._background = None
+
+        label_props = _expand_text_props(label_props)
+        self.labels = [
+            ax.text(0.25, y, label, transform=ax.transAxes,
+                    horizontalalignment="left", verticalalignment="center",
+                    **props)
+            for y, label, props in zip(ys, labels, label_props)]
+        text_size = np.array([text.get_fontsize() for text in self.labels]) / 2
+
+        radio_props = {
+            's': text_size**2,
+            **radio_props,
+            'marker': 'o',
+            'transform': ax.transAxes,
+            'animated': self._useblit,
+        }
+        radio_props.setdefault('edgecolor', radio_props.get('color', 'black'))
+        radio_props.setdefault('facecolor',
+                               radio_props.pop('color', activecolor))
+        self._buttons = ax.scatter([.15] * len(ys), ys, **radio_props)
+        # The user may have passed custom colours in radio_props, so we need to
+        # create the radios, and modify the visibility after getting whatever
+        # the user set.
+        self._active_colors = self._buttons.get_facecolor()
+        if len(self._active_colors) == 1:
+            self._active_colors = np.repeat(self._active_colors, len(labels),
+                                            axis=0)
+        self._buttons.set_facecolor(
+            [activecolor if i == active else "none"
+             for i, activecolor in enumerate(self._active_colors)])
+
+        self.connect_event('button_press_event', self._clicked)
+        if self._useblit:
+            self.connect_event('draw_event', self._clear)
+
+        self._observers = cbook.CallbackRegistry(signals=["clicked"])
+
+    def _clear(self, event):
+        """Internal event handler to clear the buttons."""
+        if self.ignore(event) or self.canvas.is_saving():
+            return
+        self._background = self.canvas.copy_from_bbox(self.ax.bbox)
+        self.ax.draw_artist(self._buttons)
+
+    def _clicked(self, event):
+        if self.ignore(event) or event.button != 1 or not self.ax.contains(event)[0]:
+            return
+        idxs = [  # Indices of buttons and of texts that contain the event.
+            *self._buttons.contains(event)[1]["ind"],
+            *[i for i, text in enumerate(self.labels) if text.contains(event)[0]]]
+        if idxs:
+            coords = self._buttons.get_offset_transform().transform(
+                self._buttons.get_offsets())
+            self.set_active(  # Closest index, only looking in idxs.
+                idxs[(((event.x, event.y) - coords[idxs]) ** 2).sum(-1).argmin()])
+
+    def set_label_props(self, props):
+        """
+        Set properties of the `.Text` labels.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        props : dict
+            Dictionary of `.Text` properties to be used for the labels.
+        """
+        _api.check_isinstance(dict, props=props)
+        props = _expand_text_props(props)
+        for text, prop in zip(self.labels, props):
+            text.update(prop)
+
+    def set_radio_props(self, props):
+        """
+        Set properties of the `.Text` labels.
+
+        .. versionadded:: 3.7
+
+        Parameters
+        ----------
+        props : dict
+            Dictionary of `.Collection` properties to be used for the radio
+            buttons.
+        """
+        _api.check_isinstance(dict, props=props)
+        if 's' in props:  # Keep API consistent with constructor.
+            props['sizes'] = np.broadcast_to(props.pop('s'), len(self.labels))
+        self._buttons.update(props)
+        self._active_colors = self._buttons.get_facecolor()
+        if len(self._active_colors) == 1:
+            self._active_colors = np.repeat(self._active_colors,
+                                            len(self.labels), axis=0)
+        self._buttons.set_facecolor(
+            [activecolor if text.get_text() == self.value_selected else "none"
+             for text, activecolor in zip(self.labels, self._active_colors)])
+
+    @property
+    def activecolor(self):
+        return self._activecolor
+
+    @activecolor.setter
+    def activecolor(self, activecolor):
+        colors._check_color_like(activecolor=activecolor)
+        self._activecolor = activecolor
+        self.set_radio_props({'facecolor': activecolor})
+
+    def set_active(self, index):
+        """
+        Select button with number *index*.
+
+        Callbacks will be triggered if :attr:`eventson` is True.
+
+        Parameters
+        ----------
+        index : int
+            The index of the button to activate.
+
+        Raises
+        ------
+        ValueError
+            If the index is invalid.
+        """
+        if index not in range(len(self.labels)):
+            raise ValueError(f'Invalid RadioButton index: {index}')
+        self.value_selected = self.labels[index].get_text()
+        self.index_selected = index
+        button_facecolors = self._buttons.get_facecolor()
+        button_facecolors[:] = colors.to_rgba("none")
+        button_facecolors[index] = colors.to_rgba(self._active_colors[index])
+        self._buttons.set_facecolor(button_facecolors)
+
+        if self.drawon:
+            if self._useblit:
+                if self._background is not None:
+                    self.canvas.restore_region(self._background)
+                self.ax.draw_artist(self._buttons)
+                self.canvas.blit(self.ax.bbox)
+            else:
+                self.canvas.draw()
+
+        if self.eventson:
+            self._observers.process('clicked', self.labels[index].get_text())
+
+    def clear(self):
+        """Reset the active button to the initially active one."""
+        self.set_active(self._initial_active)
+
+    def on_clicked(self, func):
+        """
+        Connect the callback function *func* to button click events.
+
+        Parameters
+        ----------
+        func : callable
+            When the button is clicked, call *func* with button label.
+            When all buttons are cleared, call *func* with None.
+            The callback func must have the signature::
+
+                def func(label: str | None) -> Any
+
+            Return values may exist, but are ignored.
+
+        Returns
+        -------
+        A connection id, which can be used to disconnect the callback.
+        """
+        return self._observers.connect('clicked', func)
+
+    def disconnect(self, cid):
+        """Remove the observer with connection id *cid*."""
+        self._observers.disconnect(cid)
+
+
+class SubplotTool(Widget):
+    """
+    A tool to adjust the subplot params of a `.Figure`.
+    """
+
+    def __init__(self, targetfig, toolfig):
+        """
+        Parameters
+        ----------
+        targetfig : `~matplotlib.figure.Figure`
+            The figure instance to adjust.
+        toolfig : `~matplotlib.figure.Figure`
+            The figure instance to embed the subplot tool into.
+        """
+
+        self.figure = toolfig
+        self.targetfig = targetfig
+        toolfig.subplots_adjust(left=0.2, right=0.9)
+        toolfig.suptitle("Click on slider to adjust subplot param")
+
+        self._sliders = []
+        names = ["left", "bottom", "right", "top", "wspace", "hspace"]
+        # The last subplot, removed below, keeps space for the "Reset" button.
+        for name, ax in zip(names, toolfig.subplots(len(names) + 1)):
+            ax.set_navigate(False)
+            slider = Slider(ax, name, 0, 1,
+                            valinit=getattr(targetfig.subplotpars, name))
+            slider.on_changed(self._on_slider_changed)
+            self._sliders.append(slider)
+        toolfig.axes[-1].remove()
+        (self.sliderleft, self.sliderbottom, self.sliderright, self.slidertop,
+         self.sliderwspace, self.sliderhspace) = self._sliders
+        for slider in [self.sliderleft, self.sliderbottom,
+                       self.sliderwspace, self.sliderhspace]:
+            slider.closedmax = False
+        for slider in [self.sliderright, self.slidertop]:
+            slider.closedmin = False
+
+        # constraints
+        self.sliderleft.slidermax = self.sliderright
+        self.sliderright.slidermin = self.sliderleft
+        self.sliderbottom.slidermax = self.slidertop
+        self.slidertop.slidermin = self.sliderbottom
+
+        bax = toolfig.add_axes([0.8, 0.05, 0.15, 0.075])
+        self.buttonreset = Button(bax, 'Reset')
+        self.buttonreset.on_clicked(self._on_reset)
+
+    def _on_slider_changed(self, _):
+        self.targetfig.subplots_adjust(
+            **{slider.label.get_text(): slider.val
+               for slider in self._sliders})
+        if self.drawon:
+            self.targetfig.canvas.draw()
+
+    def _on_reset(self, event):
+        with ExitStack() as stack:
+            # Temporarily disable drawing on self and self's sliders, and
+            # disconnect slider events (as the subplotparams can be temporarily
+            # invalid, depending on the order in which they are restored).
+            stack.enter_context(cbook._setattr_cm(self, drawon=False))
+            for slider in self._sliders:
+                stack.enter_context(
+                    cbook._setattr_cm(slider, drawon=False, eventson=False))
+            # Reset the slider to the initial position.
+            for slider in self._sliders:
+                slider.reset()
+        if self.drawon:
+            event.canvas.draw()  # Redraw the subplottool canvas.
+        self._on_slider_changed(None)  # Apply changes to the target window.
+
+
+class Cursor(AxesWidget):
+    """
+    A crosshair cursor that spans the Axes and moves with mouse cursor.
+
+    For the cursor to remain responsive you must keep a reference to it.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The `~.axes.Axes` to attach the cursor to.
+    horizOn : bool, default: True
+        Whether to draw the horizontal line.
+    vertOn : bool, default: True
+        Whether to draw the vertical line.
+    useblit : bool, default: False
+        Use blitting for faster drawing if supported by the backend.
+        See the tutorial :ref:`blitting` for details.
+
+    Other Parameters
+    ----------------
+    **lineprops
+        `.Line2D` properties that control the appearance of the lines.
+        See also `~.Axes.axhline`.
+
+    Examples
+    --------
+    See :doc:`/gallery/widgets/cursor`.
+    """
+    def __init__(self, ax, *, horizOn=True, vertOn=True, useblit=False,
+                 **lineprops):
+        super().__init__(ax)
+
+        self.connect_event('motion_notify_event', self.onmove)
+        self.connect_event('draw_event', self.clear)
+
+        self.visible = True
+        self.horizOn = horizOn
+        self.vertOn = vertOn
+        self.useblit = useblit and self.canvas.supports_blit
+
+        if self.useblit:
+            lineprops['animated'] = True
+        self.lineh = ax.axhline(ax.get_ybound()[0], visible=False, **lineprops)
+        self.linev = ax.axvline(ax.get_xbound()[0], visible=False, **lineprops)
+
+        self.background = None
+        self.needclear = False
+
+    def clear(self, event):
+        """Internal event handler to clear the cursor."""
+        if self.ignore(event) or self.canvas.is_saving():
+            return
+        if self.useblit:
+            self.background = self.canvas.copy_from_bbox(self.ax.bbox)
+
+    def onmove(self, event):
+        """Internal event handler to draw the cursor when the mouse moves."""
+        if self.ignore(event):
+            return
+        if not self.canvas.widgetlock.available(self):
+            return
+        if not self.ax.contains(event)[0]:
+            self.linev.set_visible(False)
+            self.lineh.set_visible(False)
+            if self.needclear:
+                self.canvas.draw()
+                self.needclear = False
+            return
+        self.needclear = True
+        xdata, ydata = self._get_data_coords(event)
+        self.linev.set_xdata((xdata, xdata))
+        self.linev.set_visible(self.visible and self.vertOn)
+        self.lineh.set_ydata((ydata, ydata))
+        self.lineh.set_visible(self.visible and self.horizOn)
+        if not (self.visible and (self.vertOn or self.horizOn)):
+            return
+        # Redraw.
+        if self.useblit:
+            if self.background is not None:
+                self.canvas.restore_region(self.background)
+            self.ax.draw_artist(self.linev)
+            self.ax.draw_artist(self.lineh)
+            self.canvas.blit(self.ax.bbox)
+        else:
+            self.canvas.draw_idle()
+
+
+class MultiCursor(Widget):
+    """
+    Provide a vertical (default) and/or horizontal line cursor shared between
+    multiple Axes.
+
+    For the cursor to remain responsive you must keep a reference to it.
+
+    Parameters
+    ----------
+    canvas : object
+        This parameter is entirely unused and only kept for back-compatibility.
+
+    axes : list of `~matplotlib.axes.Axes`
+        The `~.axes.Axes` to attach the cursor to.
+
+    useblit : bool, default: True
+        Use blitting for faster drawing if supported by the backend.
+        See the tutorial :ref:`blitting`
+        for details.
+
+    horizOn : bool, default: False
+        Whether to draw the horizontal line.
+
+    vertOn : bool, default: True
+        Whether to draw the vertical line.
+
+    Other Parameters
+    ----------------
+    **lineprops
+        `.Line2D` properties that control the appearance of the lines.
+        See also `~.Axes.axhline`.
+
+    Examples
+    --------
+    See :doc:`/gallery/widgets/multicursor`.
+    """
+
+    def __init__(self, canvas, axes, *, useblit=True, horizOn=False, vertOn=True,
+                 **lineprops):
+        # canvas is stored only to provide the deprecated .canvas attribute;
+        # once it goes away the unused argument won't need to be stored at all.
+        self._canvas = canvas
+
+        self.axes = axes
+        self.horizOn = horizOn
+        self.vertOn = vertOn
+
+        self._canvas_infos = {
+            ax.get_figure(root=True).canvas:
+                {"cids": [], "background": None} for ax in axes}
+
+        xmin, xmax = axes[-1].get_xlim()
+        ymin, ymax = axes[-1].get_ylim()
+        xmid = 0.5 * (xmin + xmax)
+        ymid = 0.5 * (ymin + ymax)
+
+        self.visible = True
+        self.useblit = (
+            useblit
+            and all(canvas.supports_blit for canvas in self._canvas_infos))
+
+        if self.useblit:
+            lineprops['animated'] = True
+
+        self.vlines = [ax.axvline(xmid, visible=False, **lineprops)
+                       for ax in axes]
+        self.hlines = [ax.axhline(ymid, visible=False, **lineprops)
+                       for ax in axes]
+
+        self.connect()
+
+    def connect(self):
+        """Connect events."""
+        for canvas, info in self._canvas_infos.items():
+            info["cids"] = [
+                canvas.mpl_connect('motion_notify_event', self.onmove),
+                canvas.mpl_connect('draw_event', self.clear),
+            ]
+
+    def disconnect(self):
+        """Disconnect events."""
+        for canvas, info in self._canvas_infos.items():
+            for cid in info["cids"]:
+                canvas.mpl_disconnect(cid)
+            info["cids"].clear()
+
+    def clear(self, event):
+        """Clear the cursor."""
+        if self.ignore(event):
+            return
+        if self.useblit:
+            for canvas, info in self._canvas_infos.items():
+                # someone has switched the canvas on us!  This happens if
+                # `savefig` needs to save to a format the previous backend did
+                # not support (e.g. saving a figure using an Agg based backend
+                # saved to a vector format).
+                if canvas is not canvas.figure.canvas:
+                    continue
+                info["background"] = canvas.copy_from_bbox(canvas.figure.bbox)
+
+    def onmove(self, event):
+        axs = [ax for ax in self.axes if ax.contains(event)[0]]
+        if self.ignore(event) or not axs or not event.canvas.widgetlock.available(self):
+            return
+        ax = cbook._topmost_artist(axs)
+        xdata, ydata = ((event.xdata, event.ydata) if event.inaxes is ax
+                        else ax.transData.inverted().transform((event.x, event.y)))
+        for line in self.vlines:
+            line.set_xdata((xdata, xdata))
+            line.set_visible(self.visible and self.vertOn)
+        for line in self.hlines:
+            line.set_ydata((ydata, ydata))
+            line.set_visible(self.visible and self.horizOn)
+        if not (self.visible and (self.vertOn or self.horizOn)):
+            return
+        # Redraw.
+        if self.useblit:
+            for canvas, info in self._canvas_infos.items():
+                if info["background"]:
+                    canvas.restore_region(info["background"])
+            if self.vertOn:
+                for ax, line in zip(self.axes, self.vlines):
+                    ax.draw_artist(line)
+            if self.horizOn:
+                for ax, line in zip(self.axes, self.hlines):
+                    ax.draw_artist(line)
+            for canvas in self._canvas_infos:
+                canvas.blit()
+        else:
+            for canvas in self._canvas_infos:
+                canvas.draw_idle()
+
+
+class _SelectorWidget(AxesWidget):
+
+    def __init__(self, ax, onselect=None, useblit=False, button=None,
+                 state_modifier_keys=None, use_data_coordinates=False):
+        super().__init__(ax)
+
+        self._visible = True
+        if onselect is None:
+            self.onselect = lambda *args: None
+        else:
+            self.onselect = onselect
+        self.useblit = useblit and self.canvas.supports_blit
+        self.connect_default_events()
+
+        self._state_modifier_keys = dict(move=' ', clear='escape',
+                                         square='shift', center='control',
+                                         rotate='r')
+        self._state_modifier_keys.update(state_modifier_keys or {})
+        self._use_data_coordinates = use_data_coordinates
+
+        self.background = None
+
+        if isinstance(button, Integral):
+            self.validButtons = [button]
+        else:
+            self.validButtons = button
+
+        # Set to True when a selection is completed, otherwise is False
+        self._selection_completed = False
+
+        # will save the data (position at mouseclick)
+        self._eventpress = None
+        # will save the data (pos. at mouserelease)
+        self._eventrelease = None
+        self._prev_event = None
+        self._state = set()
+
+    def set_active(self, active):
+        super().set_active(active)
+        if active:
+            self.update_background(None)
+
+    def _get_animated_artists(self):
+        """
+        Convenience method to get all animated artists of the figure containing
+        this widget, excluding those already present in self.artists.
+        The returned tuple is not sorted by 'z_order': z_order sorting is
+        valid only when considering all artists and not only a subset of all
+        artists.
+        """
+        return tuple(a for ax_ in self.ax.get_figure().get_axes()
+                     for a in ax_.get_children()
+                     if a.get_animated() and a not in self.artists)
+
+    def update_background(self, event):
+        """Force an update of the background."""
+        # If you add a call to `ignore` here, you'll want to check edge case:
+        # `release` can call a draw event even when `ignore` is True.
+        if not self.useblit:
+            return
+        # Make sure that widget artists don't get accidentally included in the
+        # background, by re-rendering the background if needed (and then
+        # re-re-rendering the canvas with the visible widget artists).
+        # We need to remove all artists which will be drawn when updating
+        # the selector: if we have animated artists in the figure, it is safer
+        # to redrawn by default, in case they have updated by the callback
+        # zorder needs to be respected when redrawing
+        artists = sorted(self.artists + self._get_animated_artists(),
+                         key=lambda a: a.get_zorder())
+        needs_redraw = any(artist.get_visible() for artist in artists)
+        with ExitStack() as stack:
+            if needs_redraw:
+                for artist in artists:
+                    stack.enter_context(artist._cm_set(visible=False))
+                self.canvas.draw()
+            self.background = self.canvas.copy_from_bbox(self.ax.bbox)
+        if needs_redraw:
+            for artist in artists:
+                self.ax.draw_artist(artist)
+
+    def connect_default_events(self):
+        """Connect the major canvas events to methods."""
+        self.connect_event('motion_notify_event', self.onmove)
+        self.connect_event('button_press_event', self.press)
+        self.connect_event('button_release_event', self.release)
+        self.connect_event('draw_event', self.update_background)
+        self.connect_event('key_press_event', self.on_key_press)
+        self.connect_event('key_release_event', self.on_key_release)
+        self.connect_event('scroll_event', self.on_scroll)
+
+    def ignore(self, event):
+        # docstring inherited
+        if not self.active or not self.ax.get_visible():
+            return True
+        # If canvas was locked
+        if not self.canvas.widgetlock.available(self):
+            return True
+        if not hasattr(event, 'button'):
+            event.button = None
+        # Only do rectangle selection if event was triggered
+        # with a desired button
+        if (self.validButtons is not None
+                and event.button not in self.validButtons):
+            return True
+        # If no button was pressed yet ignore the event if it was out of the Axes.
+        if self._eventpress is None:
+            return not self.ax.contains(event)[0]
+        # If a button was pressed, check if the release-button is the same.
+        if event.button == self._eventpress.button:
+            return False
+        # If a button was pressed, check if the release-button is the same.
+        return (not self.ax.contains(event)[0] or
+                event.button != self._eventpress.button)
+
+    def update(self):
+        """Draw using blit() or draw_idle(), depending on ``self.useblit``."""
+        if (not self.ax.get_visible() or
+                self.ax.get_figure(root=True)._get_renderer() is None):
+            return
+        if self.useblit:
+            if self.background is not None:
+                self.canvas.restore_region(self.background)
+            else:
+                self.update_background(None)
+            # We need to draw all artists, which are not included in the
+            # background, therefore we also draw self._get_animated_artists()
+            # and we make sure that we respect z_order
+            artists = sorted(self.artists + self._get_animated_artists(),
+                             key=lambda a: a.get_zorder())
+            for artist in artists:
+                self.ax.draw_artist(artist)
+            self.canvas.blit(self.ax.bbox)
+        else:
+            self.canvas.draw_idle()
+
+    def _get_data(self, event):
+        """Get the xdata and ydata for event, with limits."""
+        if event.xdata is None:
+            return None, None
+        xdata, ydata = self._get_data_coords(event)
+        xdata = np.clip(xdata, *self.ax.get_xbound())
+        ydata = np.clip(ydata, *self.ax.get_ybound())
+        return xdata, ydata
+
+    def _clean_event(self, event):
+        """
+        Preprocess an event:
+
+        - Replace *event* by the previous event if *event* has no ``xdata``.
+        - Get ``xdata`` and ``ydata`` from this widget's Axes, and clip them to the axes
+          limits.
+        - Update the previous event.
+        """
+        if event.xdata is None:
+            event = self._prev_event
+        else:
+            event = copy.copy(event)
+        event.xdata, event.ydata = self._get_data(event)
+        self._prev_event = event
+        return event
+
+    def press(self, event):
+        """Button press handler and validator."""
+        if not self.ignore(event):
+            event = self._clean_event(event)
+            self._eventpress = event
+            self._prev_event = event
+            key = event.key or ''
+            key = key.replace('ctrl', 'control')
+            # move state is locked in on a button press
+            if key == self._state_modifier_keys['move']:
+                self._state.add('move')
+            self._press(event)
+            return True
+        return False
+
+    def _press(self, event):
+        """Button press event handler."""
+
+    def release(self, event):
+        """Button release event handler and validator."""
+        if not self.ignore(event) and self._eventpress:
+            event = self._clean_event(event)
+            self._eventrelease = event
+            self._release(event)
+            self._eventpress = None
+            self._eventrelease = None
+            self._state.discard('move')
+            return True
+        return False
+
+    def _release(self, event):
+        """Button release event handler."""
+
+    def onmove(self, event):
+        """Cursor move event handler and validator."""
+        if not self.ignore(event) and self._eventpress:
+            event = self._clean_event(event)
+            self._onmove(event)
+            return True
+        return False
+
+    def _onmove(self, event):
+        """Cursor move event handler."""
+
+    def on_scroll(self, event):
+        """Mouse scroll event handler and validator."""
+        if not self.ignore(event):
+            self._on_scroll(event)
+
+    def _on_scroll(self, event):
+        """Mouse scroll event handler."""
+
+    def on_key_press(self, event):
+        """Key press event handler and validator for all selection widgets."""
+        if self.active:
+            key = event.key or ''
+            key = key.replace('ctrl', 'control')
+            if key == self._state_modifier_keys['clear']:
+                self.clear()
+                return
+            for (state, modifier) in self._state_modifier_keys.items():
+                if modifier in key.split('+'):
+                    # 'rotate' is changing _state on press and is not removed
+                    # from _state when releasing
+                    if state == 'rotate':
+                        if state in self._state:
+                            self._state.discard(state)
+                        else:
+                            self._state.add(state)
+                    else:
+                        self._state.add(state)
+            self._on_key_press(event)
+
+    def _on_key_press(self, event):
+        """Key press event handler - for widget-specific key press actions."""
+
+    def on_key_release(self, event):
+        """Key release event handler and validator."""
+        if self.active:
+            key = event.key or ''
+            for (state, modifier) in self._state_modifier_keys.items():
+                # 'rotate' is changing _state on press and is not removed
+                # from _state when releasing
+                if modifier in key.split('+') and state != 'rotate':
+                    self._state.discard(state)
+            self._on_key_release(event)
+
+    def _on_key_release(self, event):
+        """Key release event handler."""
+
+    def set_visible(self, visible):
+        """Set the visibility of the selector artists."""
+        self._visible = visible
+        for artist in self.artists:
+            artist.set_visible(visible)
+
+    def get_visible(self):
+        """Get the visibility of the selector artists."""
+        return self._visible
+
+    def clear(self):
+        """Clear the selection and set the selector ready to make a new one."""
+        self._clear_without_update()
+        self.update()
+
+    def _clear_without_update(self):
+        self._selection_completed = False
+        self.set_visible(False)
+
+    @property
+    def artists(self):
+        """Tuple of the artists of the selector."""
+        handles_artists = getattr(self, '_handles_artists', ())
+        return (self._selection_artist,) + handles_artists
+
+    def set_props(self, **props):
+        """
+        Set the properties of the selector artist.
+
+        See the *props* argument in the selector docstring to know which properties are
+        supported.
+        """
+        artist = self._selection_artist
+        props = cbook.normalize_kwargs(props, artist)
+        artist.set(**props)
+        if self.useblit:
+            self.update()
+
+    def set_handle_props(self, **handle_props):
+        """
+        Set the properties of the handles selector artist. See the
+        `handle_props` argument in the selector docstring to know which
+        properties are supported.
+        """
+        if not hasattr(self, '_handles_artists'):
+            raise NotImplementedError("This selector doesn't have handles.")
+
+        artist = self._handles_artists[0]
+        handle_props = cbook.normalize_kwargs(handle_props, artist)
+        for handle in self._handles_artists:
+            handle.set(**handle_props)
+        if self.useblit:
+            self.update()
+        self._handle_props.update(handle_props)
+
+    def _validate_state(self, state):
+        supported_state = [
+            key for key, value in self._state_modifier_keys.items()
+            if key != 'clear' and value != 'not-applicable'
+            ]
+        _api.check_in_list(supported_state, state=state)
+
+    def add_state(self, state):
+        """
+        Add a state to define the widget's behavior. See the
+        `state_modifier_keys` parameters for details.
+
+        Parameters
+        ----------
+        state : str
+            Must be a supported state of the selector. See the
+            `state_modifier_keys` parameters for details.
+
+        Raises
+        ------
+        ValueError
+            When the state is not supported by the selector.
+
+        """
+        self._validate_state(state)
+        self._state.add(state)
+
+    def remove_state(self, state):
+        """
+        Remove a state to define the widget's behavior. See the
+        `state_modifier_keys` parameters for details.
+
+        Parameters
+        ----------
+        state : str
+            Must be a supported state of the selector. See the
+            `state_modifier_keys` parameters for details.
+
+        Raises
+        ------
+        ValueError
+            When the state is not supported by the selector.
+
+        """
+        self._validate_state(state)
+        self._state.remove(state)
+
+
+class SpanSelector(_SelectorWidget):
+    """
+    Visually select a min/max range on a single axis and call a function with
+    those values.
+
+    To guarantee that the selector remains responsive, keep a reference to it.
+
+    In order to turn off the SpanSelector, set ``span_selector.active`` to
+    False.  To turn it back on, set it to True.
+
+    Press and release events triggered at the same coordinates outside the
+    selection will clear the selector, except when
+    ``ignore_event_outside=True``.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+
+    onselect : callable with signature ``func(min: float, max: float)``
+        A callback function that is called after a release event and the
+        selection is created, changed or removed.
+
+    direction : {"horizontal", "vertical"}
+        The direction along which to draw the span selector.
+
+    minspan : float, default: 0
+        If selection is less than or equal to *minspan*, the selection is
+        removed (when already existing) or cancelled.
+
+    useblit : bool, default: False
+        If True, use the backend-dependent blitting features for faster
+        canvas updates. See the tutorial :ref:`blitting` for details.
+
+    props : dict, default: {'facecolor': 'red', 'alpha': 0.5}
+        Dictionary of `.Patch` properties.
+
+    onmove_callback : callable with signature ``func(min: float, max: float)``, optional
+        Called on mouse move while the span is being selected.
+
+    interactive : bool, default: False
+        Whether to draw a set of handles that allow interaction with the
+        widget after it is drawn.
+
+    button : `.MouseButton` or list of `.MouseButton`, default: all buttons
+        The mouse buttons which activate the span selector.
+
+    handle_props : dict, default: None
+        Properties of the handle lines at the edges of the span. Only used
+        when *interactive* is True. See `.Line2D` for valid properties.
+
+    grab_range : float, default: 10
+        Distance in pixels within which the interactive tool handles can be activated.
+
+    state_modifier_keys : dict, optional
+        Keyboard modifiers which affect the widget's behavior.  Values
+        amend the defaults, which are:
+
+        - "clear": Clear the current shape, default: "escape".
+
+    drag_from_anywhere : bool, default: False
+        If `True`, the widget can be moved by clicking anywhere within its bounds.
+
+    ignore_event_outside : bool, default: False
+        If `True`, the event triggered outside the span selector will be ignored.
+
+    snap_values : 1D array-like, optional
+        Snap the selector edges to the given values.
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> import matplotlib.widgets as mwidgets
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3], [10, 50, 100])
+    >>> def onselect(vmin, vmax):
+    ...     print(vmin, vmax)
+    >>> span = mwidgets.SpanSelector(ax, onselect, 'horizontal',
+    ...                              props=dict(facecolor='blue', alpha=0.5))
+    >>> fig.show()
+
+    See also: :doc:`/gallery/widgets/span_selector`
+    """
+
+    def __init__(self, ax, onselect, direction, *, minspan=0, useblit=False,
+                 props=None, onmove_callback=None, interactive=False,
+                 button=None, handle_props=None, grab_range=10,
+                 state_modifier_keys=None, drag_from_anywhere=False,
+                 ignore_event_outside=False, snap_values=None):
+
+        if state_modifier_keys is None:
+            state_modifier_keys = dict(clear='escape',
+                                       square='not-applicable',
+                                       center='not-applicable',
+                                       rotate='not-applicable')
+        super().__init__(ax, onselect, useblit=useblit, button=button,
+                         state_modifier_keys=state_modifier_keys)
+
+        if props is None:
+            props = dict(facecolor='red', alpha=0.5)
+
+        props['animated'] = self.useblit
+
+        self.direction = direction
+        self._extents_on_press = None
+        self.snap_values = snap_values
+
+        self.onmove_callback = onmove_callback
+        self.minspan = minspan
+
+        self.grab_range = grab_range
+        self._interactive = interactive
+        self._edge_handles = None
+        self.drag_from_anywhere = drag_from_anywhere
+        self.ignore_event_outside = ignore_event_outside
+
+        self.new_axes(ax, _props=props, _init=True)
+
+        # Setup handles
+        self._handle_props = {
+            'color': props.get('facecolor', 'r'),
+            **cbook.normalize_kwargs(handle_props, Line2D)}
+
+        if self._interactive:
+            self._edge_order = ['min', 'max']
+            self._setup_edge_handles(self._handle_props)
+
+        self._active_handle = None
+
+    def new_axes(self, ax, *, _props=None, _init=False):
+        """Set SpanSelector to operate on a new Axes."""
+        reconnect = False
+        if _init or self.canvas is not ax.get_figure(root=True).canvas:
+            if self.canvas is not None:
+                self.disconnect_events()
+            reconnect = True
+        self.ax = ax
+        if reconnect:
+            self.connect_default_events()
+
+        # Reset
+        self._selection_completed = False
+
+        if self.direction == 'horizontal':
+            trans = ax.get_xaxis_transform()
+            w, h = 0, 1
+        else:
+            trans = ax.get_yaxis_transform()
+            w, h = 1, 0
+        rect_artist = Rectangle((0, 0), w, h, transform=trans, visible=False)
+        if _props is not None:
+            rect_artist.update(_props)
+        elif self._selection_artist is not None:
+            rect_artist.update_from(self._selection_artist)
+
+        self.ax.add_patch(rect_artist)
+        self._selection_artist = rect_artist
+
+    def _setup_edge_handles(self, props):
+        # Define initial position using the axis bounds to keep the same bounds
+        if self.direction == 'horizontal':
+            positions = self.ax.get_xbound()
+        else:
+            positions = self.ax.get_ybound()
+        self._edge_handles = ToolLineHandles(self.ax, positions,
+                                             direction=self.direction,
+                                             line_props=props,
+                                             useblit=self.useblit)
+
+    @property
+    def _handles_artists(self):
+        if self._edge_handles is not None:
+            return self._edge_handles.artists
+        else:
+            return ()
+
+    def _set_cursor(self, enabled):
+        """Update the canvas cursor based on direction of the selector."""
+        if enabled:
+            cursor = (backend_tools.Cursors.RESIZE_HORIZONTAL
+                      if self.direction == 'horizontal' else
+                      backend_tools.Cursors.RESIZE_VERTICAL)
+        else:
+            cursor = backend_tools.Cursors.POINTER
+
+        self.ax.get_figure(root=True).canvas.set_cursor(cursor)
+
+    def connect_default_events(self):
+        # docstring inherited
+        super().connect_default_events()
+        if getattr(self, '_interactive', False):
+            self.connect_event('motion_notify_event', self._hover)
+
+    def _press(self, event):
+        """Button press event handler."""
+        self._set_cursor(True)
+        if self._interactive and self._selection_artist.get_visible():
+            self._set_active_handle(event)
+        else:
+            self._active_handle = None
+
+        if self._active_handle is None or not self._interactive:
+            # Clear previous rectangle before drawing new rectangle.
+            self.update()
+
+        xdata, ydata = self._get_data_coords(event)
+        v = xdata if self.direction == 'horizontal' else ydata
+
+        if self._active_handle is None and not self.ignore_event_outside:
+            # when the press event outside the span, we initially set the
+            # visibility to False and extents to (v, v)
+            # update will be called when setting the extents
+            self._visible = False
+            self._set_extents((v, v))
+            # We need to set the visibility back, so the span selector will be
+            # drawn when necessary (span width > 0)
+            self._visible = True
+        else:
+            self.set_visible(True)
+
+        return False
+
+    @property
+    def direction(self):
+        """Direction of the span selector: 'vertical' or 'horizontal'."""
+        return self._direction
+
+    @direction.setter
+    def direction(self, direction):
+        """Set the direction of the span selector."""
+        _api.check_in_list(['horizontal', 'vertical'], direction=direction)
+        if hasattr(self, '_direction') and direction != self._direction:
+            # remove previous artists
+            self._selection_artist.remove()
+            if self._interactive:
+                self._edge_handles.remove()
+            self._direction = direction
+            self.new_axes(self.ax)
+            if self._interactive:
+                self._setup_edge_handles(self._handle_props)
+        else:
+            self._direction = direction
+
+    def _release(self, event):
+        """Button release event handler."""
+        self._set_cursor(False)
+
+        if not self._interactive:
+            self._selection_artist.set_visible(False)
+
+        if (self._active_handle is None and self._selection_completed and
+                self.ignore_event_outside):
+            return
+
+        vmin, vmax = self.extents
+        span = vmax - vmin
+
+        if span <= self.minspan:
+            # Remove span and set self._selection_completed = False
+            self.set_visible(False)
+            if self._selection_completed:
+                # Call onselect, only when the span is already existing
+                self.onselect(vmin, vmax)
+            self._selection_completed = False
+        else:
+            self.onselect(vmin, vmax)
+            self._selection_completed = True
+
+        self.update()
+
+        self._active_handle = None
+
+        return False
+
+    def _hover(self, event):
+        """Update the canvas cursor if it's over a handle."""
+        if self.ignore(event):
+            return
+
+        if self._active_handle is not None or not self._selection_completed:
+            # Do nothing if button is pressed and a handle is active, which may
+            # occur with drag_from_anywhere=True.
+            # Do nothing if selection is not completed, which occurs when
+            # a selector has been cleared
+            return
+
+        _, e_dist = self._edge_handles.closest(event.x, event.y)
+        self._set_cursor(e_dist <= self.grab_range)
+
+    def _onmove(self, event):
+        """Motion notify event handler."""
+
+        xdata, ydata = self._get_data_coords(event)
+        if self.direction == 'horizontal':
+            v = xdata
+            vpress = self._eventpress.xdata
+        else:
+            v = ydata
+            vpress = self._eventpress.ydata
+
+        # move existing span
+        # When "dragging from anywhere", `self._active_handle` is set to 'C'
+        # (match notation used in the RectangleSelector)
+        if self._active_handle == 'C' and self._extents_on_press is not None:
+            vmin, vmax = self._extents_on_press
+            dv = v - vpress
+            vmin += dv
+            vmax += dv
+
+        # resize an existing shape
+        elif self._active_handle and self._active_handle != 'C':
+            vmin, vmax = self._extents_on_press
+            if self._active_handle == 'min':
+                vmin = v
+            else:
+                vmax = v
+        # new shape
+        else:
+            # Don't create a new span if there is already one when
+            # ignore_event_outside=True
+            if self.ignore_event_outside and self._selection_completed:
+                return
+            vmin, vmax = vpress, v
+            if vmin > vmax:
+                vmin, vmax = vmax, vmin
+
+        self._set_extents((vmin, vmax))
+
+        if self.onmove_callback is not None:
+            self.onmove_callback(vmin, vmax)
+
+        return False
+
+    def _draw_shape(self, vmin, vmax):
+        if vmin > vmax:
+            vmin, vmax = vmax, vmin
+        if self.direction == 'horizontal':
+            self._selection_artist.set_x(vmin)
+            self._selection_artist.set_width(vmax - vmin)
+        else:
+            self._selection_artist.set_y(vmin)
+            self._selection_artist.set_height(vmax - vmin)
+
+    def _set_active_handle(self, event):
+        """Set active handle based on the location of the mouse event."""
+        # Note: event.xdata/ydata in data coordinates, event.x/y in pixels
+        e_idx, e_dist = self._edge_handles.closest(event.x, event.y)
+
+        # Prioritise center handle over other handles
+        # Use 'C' to match the notation used in the RectangleSelector
+        if 'move' in self._state:
+            self._active_handle = 'C'
+        elif e_dist > self.grab_range:
+            # Not close to any handles
+            self._active_handle = None
+            if self.drag_from_anywhere and self._contains(event):
+                # Check if we've clicked inside the region
+                self._active_handle = 'C'
+                self._extents_on_press = self.extents
+            else:
+                self._active_handle = None
+                return
+        else:
+            # Closest to an edge handle
+            self._active_handle = self._edge_order[e_idx]
+
+        # Save coordinates of rectangle at the start of handle movement.
+        self._extents_on_press = self.extents
+
+    def _contains(self, event):
+        """Return True if event is within the patch."""
+        return self._selection_artist.contains(event, radius=0)[0]
+
+    @staticmethod
+    def _snap(values, snap_values):
+        """Snap values to a given array values (snap_values)."""
+        # take into account machine precision
+        eps = np.min(np.abs(np.diff(snap_values))) * 1e-12
+        return tuple(
+            snap_values[np.abs(snap_values - v + np.sign(v) * eps).argmin()]
+            for v in values)
+
+    @property
+    def extents(self):
+        """
+        (float, float)
+            The values, in data coordinates, for the start and end points of the current
+            selection. If there is no selection then the start and end values will be
+            the same.
+        """
+        if self.direction == 'horizontal':
+            vmin = self._selection_artist.get_x()
+            vmax = vmin + self._selection_artist.get_width()
+        else:
+            vmin = self._selection_artist.get_y()
+            vmax = vmin + self._selection_artist.get_height()
+        return vmin, vmax
+
+    @extents.setter
+    def extents(self, extents):
+        self._set_extents(extents)
+        self._selection_completed = True
+
+    def _set_extents(self, extents):
+        # Update displayed shape
+        if self.snap_values is not None:
+            extents = tuple(self._snap(extents, self.snap_values))
+        self._draw_shape(*extents)
+        if self._interactive:
+            # Update displayed handles
+            self._edge_handles.set_data(self.extents)
+        self.set_visible(self._visible)
+        self.update()
+
+
+class ToolLineHandles:
+    """
+    Control handles for canvas tools.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        Matplotlib Axes where tool handles are displayed.
+    positions : 1D array
+        Positions of handles in data coordinates.
+    direction : {"horizontal", "vertical"}
+        Direction of handles, either 'vertical' or 'horizontal'
+    line_props : dict, optional
+        Additional line properties. See `.Line2D`.
+    useblit : bool, default: True
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+    """
+
+    def __init__(self, ax, positions, direction, *, line_props=None,
+                 useblit=True):
+        self.ax = ax
+
+        _api.check_in_list(['horizontal', 'vertical'], direction=direction)
+        self._direction = direction
+
+        line_props = {
+            **(line_props if line_props is not None else {}),
+            'visible': False,
+            'animated': useblit,
+        }
+
+        line_fun = ax.axvline if self.direction == 'horizontal' else ax.axhline
+
+        self._artists = [line_fun(p, **line_props) for p in positions]
+
+    @property
+    def artists(self):
+        return tuple(self._artists)
+
+    @property
+    def positions(self):
+        """Positions of the handle in data coordinates."""
+        method = 'get_xdata' if self.direction == 'horizontal' else 'get_ydata'
+        return [getattr(line, method)()[0] for line in self.artists]
+
+    @property
+    def direction(self):
+        """Direction of the handle: 'vertical' or 'horizontal'."""
+        return self._direction
+
+    def set_data(self, positions):
+        """
+        Set x- or y-positions of handles, depending on if the lines are
+        vertical or horizontal.
+
+        Parameters
+        ----------
+        positions : tuple of length 2
+            Set the positions of the handle in data coordinates
+        """
+        method = 'set_xdata' if self.direction == 'horizontal' else 'set_ydata'
+        for line, p in zip(self.artists, positions):
+            getattr(line, method)([p, p])
+
+    def set_visible(self, value):
+        """Set the visibility state of the handles artist."""
+        for artist in self.artists:
+            artist.set_visible(value)
+
+    def set_animated(self, value):
+        """Set the animated state of the handles artist."""
+        for artist in self.artists:
+            artist.set_animated(value)
+
+    def remove(self):
+        """Remove the handles artist from the figure."""
+        for artist in self._artists:
+            artist.remove()
+
+    def closest(self, x, y):
+        """
+        Return index and pixel distance to closest handle.
+
+        Parameters
+        ----------
+        x, y : float
+            x, y position from which the distance will be calculated to
+            determinate the closest handle
+
+        Returns
+        -------
+        index, distance : index of the handle and its distance from
+            position x, y
+        """
+        if self.direction == 'horizontal':
+            p_pts = np.array([
+                self.ax.transData.transform((p, 0))[0] for p in self.positions
+                ])
+            dist = abs(p_pts - x)
+        else:
+            p_pts = np.array([
+                self.ax.transData.transform((0, p))[1] for p in self.positions
+                ])
+            dist = abs(p_pts - y)
+        index = np.argmin(dist)
+        return index, dist[index]
+
+
+class ToolHandles:
+    """
+    Control handles for canvas tools.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        Matplotlib Axes where tool handles are displayed.
+    x, y : 1D arrays
+        Coordinates of control handles.
+    marker : str, default: 'o'
+        Shape of marker used to display handle. See `~.pyplot.plot`.
+    marker_props : dict, optional
+        Additional marker properties. See `.Line2D`.
+    useblit : bool, default: True
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+    """
+
+    def __init__(self, ax, x, y, *, marker='o', marker_props=None, useblit=True):
+        self.ax = ax
+        props = {'marker': marker, 'markersize': 7, 'markerfacecolor': 'w',
+                 'linestyle': 'none', 'alpha': 0.5, 'visible': False,
+                 'label': '_nolegend_',
+                 **cbook.normalize_kwargs(marker_props, Line2D._alias_map)}
+        self._markers = Line2D(x, y, animated=useblit, **props)
+        self.ax.add_line(self._markers)
+
+    @property
+    def x(self):
+        return self._markers.get_xdata()
+
+    @property
+    def y(self):
+        return self._markers.get_ydata()
+
+    @property
+    def artists(self):
+        return (self._markers, )
+
+    def set_data(self, pts, y=None):
+        """Set x and y positions of handles."""
+        if y is not None:
+            x = pts
+            pts = np.array([x, y])
+        self._markers.set_data(pts)
+
+    def set_visible(self, val):
+        self._markers.set_visible(val)
+
+    def set_animated(self, val):
+        self._markers.set_animated(val)
+
+    def closest(self, x, y):
+        """Return index and pixel distance to closest index."""
+        pts = np.column_stack([self.x, self.y])
+        # Transform data coordinates to pixel coordinates.
+        pts = self.ax.transData.transform(pts)
+        diff = pts - [x, y]
+        dist = np.hypot(*diff.T)
+        min_index = np.argmin(dist)
+        return min_index, dist[min_index]
+
+
+_RECTANGLESELECTOR_PARAMETERS_DOCSTRING = \
+    r"""
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+
+    onselect : function, optional
+        A callback function that is called after a release event and the
+        selection is created, changed or removed.
+        It must have the signature::
+
+            def onselect(eclick: MouseEvent, erelease: MouseEvent)
+
+        where *eclick* and *erelease* are the mouse click and release
+        `.MouseEvent`\s that start and complete the selection.
+
+    minspanx : float, default: 0
+        Selections with an x-span less than or equal to *minspanx* are removed
+        (when already existing) or cancelled.
+
+    minspany : float, default: 0
+        Selections with an y-span less than or equal to *minspanx* are removed
+        (when already existing) or cancelled.
+
+    useblit : bool, default: False
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+
+    props : dict, optional
+        Properties with which the __ARTIST_NAME__ is drawn. See
+        `.Patch` for valid properties.
+        Default:
+
+        ``dict(facecolor='red', edgecolor='black', alpha=0.2, fill=True)``
+
+    spancoords : {"data", "pixels"}, default: "data"
+        Whether to interpret *minspanx* and *minspany* in data or in pixel
+        coordinates.
+
+    button : `.MouseButton`, list of `.MouseButton`, default: all buttons
+        Button(s) that trigger rectangle selection.
+
+    grab_range : float, default: 10
+        Distance in pixels within which the interactive tool handles can be
+        activated.
+
+    handle_props : dict, optional
+        Properties with which the interactive handles (marker artists) are
+        drawn. See the marker arguments in `.Line2D` for valid
+        properties.  Default values are defined in ``mpl.rcParams`` except for
+        the default value of ``markeredgecolor`` which will be the same as the
+        ``edgecolor`` property in *props*.
+
+    interactive : bool, default: False
+        Whether to draw a set of handles that allow interaction with the
+        widget after it is drawn.
+
+    state_modifier_keys : dict, optional
+        Keyboard modifiers which affect the widget's behavior.  Values
+        amend the defaults, which are:
+
+        - "move": Move the existing shape, default: no modifier.
+        - "clear": Clear the current shape, default: "escape".
+        - "square": Make the shape square, default: "shift".
+        - "center": change the shape around its center, default: "ctrl".
+        - "rotate": Rotate the shape around its center between -45° and 45°,
+          default: "r".
+
+        "square" and "center" can be combined. The square shape can be defined
+        in data or display coordinates as determined by the
+        ``use_data_coordinates`` argument specified when creating the selector.
+
+    drag_from_anywhere : bool, default: False
+        If `True`, the widget can be moved by clicking anywhere within
+        its bounds.
+
+    ignore_event_outside : bool, default: False
+        If `True`, the event triggered outside the span selector will be
+        ignored.
+
+    use_data_coordinates : bool, default: False
+        If `True`, the "square" shape of the selector is defined in
+        data coordinates instead of display coordinates.
+    """
+
+
+@_docstring.Substitution(_RECTANGLESELECTOR_PARAMETERS_DOCSTRING.replace(
+    '__ARTIST_NAME__', 'rectangle'))
+class RectangleSelector(_SelectorWidget):
+    """
+    Select a rectangular region of an Axes.
+
+    For the cursor to remain responsive you must keep a reference to it.
+
+    Press and release events triggered at the same coordinates outside the
+    selection will clear the selector, except when
+    ``ignore_event_outside=True``.
+
+    %s
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> import matplotlib.widgets as mwidgets
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3], [10, 50, 100])
+    >>> def onselect(eclick, erelease):
+    ...     print(eclick.xdata, eclick.ydata)
+    ...     print(erelease.xdata, erelease.ydata)
+    >>> props = dict(facecolor='blue', alpha=0.5)
+    >>> rect = mwidgets.RectangleSelector(ax, onselect, interactive=True,
+    ...                                   props=props)
+    >>> fig.show()
+    >>> rect.add_state('square')
+
+    See also: :doc:`/gallery/widgets/rectangle_selector`
+    """
+
+    def __init__(self, ax, onselect=None, *, minspanx=0,
+                 minspany=0, useblit=False,
+                 props=None, spancoords='data', button=None, grab_range=10,
+                 handle_props=None, interactive=False,
+                 state_modifier_keys=None, drag_from_anywhere=False,
+                 ignore_event_outside=False, use_data_coordinates=False):
+        super().__init__(ax, onselect, useblit=useblit, button=button,
+                         state_modifier_keys=state_modifier_keys,
+                         use_data_coordinates=use_data_coordinates)
+
+        self._interactive = interactive
+        self.drag_from_anywhere = drag_from_anywhere
+        self.ignore_event_outside = ignore_event_outside
+        self._rotation = 0.0
+        self._aspect_ratio_correction = 1.0
+
+        # State to allow the option of an interactive selector that can't be
+        # interactively drawn. This is used in PolygonSelector as an
+        # interactive bounding box to allow the polygon to be easily resized
+        self._allow_creation = True
+
+        if props is None:
+            props = dict(facecolor='red', edgecolor='black',
+                         alpha=0.2, fill=True)
+        props = {**props, 'animated': self.useblit}
+        self._visible = props.pop('visible', self._visible)
+        to_draw = self._init_shape(**props)
+        self.ax.add_patch(to_draw)
+
+        self._selection_artist = to_draw
+        self._set_aspect_ratio_correction()
+
+        self.minspanx = minspanx
+        self.minspany = minspany
+
+        _api.check_in_list(['data', 'pixels'], spancoords=spancoords)
+        self.spancoords = spancoords
+
+        self.grab_range = grab_range
+
+        if self._interactive:
+            self._handle_props = {
+                'markeredgecolor': (props or {}).get('edgecolor', 'black'),
+                **cbook.normalize_kwargs(handle_props, Line2D)}
+
+            self._corner_order = ['SW', 'SE', 'NE', 'NW']
+            xc, yc = self.corners
+            self._corner_handles = ToolHandles(self.ax, xc, yc,
+                                               marker_props=self._handle_props,
+                                               useblit=self.useblit)
+
+            self._edge_order = ['W', 'S', 'E', 'N']
+            xe, ye = self.edge_centers
+            self._edge_handles = ToolHandles(self.ax, xe, ye, marker='s',
+                                             marker_props=self._handle_props,
+                                             useblit=self.useblit)
+
+            xc, yc = self.center
+            self._center_handle = ToolHandles(self.ax, [xc], [yc], marker='s',
+                                              marker_props=self._handle_props,
+                                              useblit=self.useblit)
+
+            self._active_handle = None
+
+        self._extents_on_press = None
+
+    @property
+    def _handles_artists(self):
+        return (*self._center_handle.artists, *self._corner_handles.artists,
+                *self._edge_handles.artists)
+
+    def _init_shape(self, **props):
+        return Rectangle((0, 0), 0, 1, visible=False,
+                         rotation_point='center', **props)
+
+    def _press(self, event):
+        """Button press event handler."""
+        # make the drawn box/line visible get the click-coordinates, button, ...
+        if self._interactive and self._selection_artist.get_visible():
+            self._set_active_handle(event)
+        else:
+            self._active_handle = None
+
+        if ((self._active_handle is None or not self._interactive) and
+                self._allow_creation):
+            # Clear previous rectangle before drawing new rectangle.
+            self.update()
+
+        if (self._active_handle is None and not self.ignore_event_outside and
+                self._allow_creation):
+            x, y = self._get_data_coords(event)
+            self._visible = False
+            self.extents = x, x, y, y
+            self._visible = True
+        else:
+            self.set_visible(True)
+
+        self._extents_on_press = self.extents
+        self._rotation_on_press = self._rotation
+        self._set_aspect_ratio_correction()
+
+        return False
+
+    def _release(self, event):
+        """Button release event handler."""
+        if not self._interactive:
+            self._selection_artist.set_visible(False)
+
+        if (self._active_handle is None and self._selection_completed and
+                self.ignore_event_outside):
+            return
+
+        # update the eventpress and eventrelease with the resulting extents
+        x0, x1, y0, y1 = self.extents
+        self._eventpress.xdata = x0
+        self._eventpress.ydata = y0
+        xy0 = self.ax.transData.transform([x0, y0])
+        self._eventpress.x, self._eventpress.y = xy0
+
+        self._eventrelease.xdata = x1
+        self._eventrelease.ydata = y1
+        xy1 = self.ax.transData.transform([x1, y1])
+        self._eventrelease.x, self._eventrelease.y = xy1
+
+        # calculate dimensions of box or line
+        if self.spancoords == 'data':
+            spanx = abs(self._eventpress.xdata - self._eventrelease.xdata)
+            spany = abs(self._eventpress.ydata - self._eventrelease.ydata)
+        elif self.spancoords == 'pixels':
+            spanx = abs(self._eventpress.x - self._eventrelease.x)
+            spany = abs(self._eventpress.y - self._eventrelease.y)
+        else:
+            _api.check_in_list(['data', 'pixels'],
+                               spancoords=self.spancoords)
+        # check if drawn distance (if it exists) is not too small in
+        # either x or y-direction
+        if spanx <= self.minspanx or spany <= self.minspany:
+            if self._selection_completed:
+                # Call onselect, only when the selection is already existing
+                self.onselect(self._eventpress, self._eventrelease)
+            self._clear_without_update()
+        else:
+            self.onselect(self._eventpress, self._eventrelease)
+            self._selection_completed = True
+
+        self.update()
+        self._active_handle = None
+        self._extents_on_press = None
+
+        return False
+
+    def _onmove(self, event):
+        """
+        Motion notify event handler.
+
+        This can do one of four things:
+        - Translate
+        - Rotate
+        - Re-size
+        - Continue the creation of a new shape
+        """
+        eventpress = self._eventpress
+        # The calculations are done for rotation at zero: we apply inverse
+        # transformation to events except when we rotate and move
+        state = self._state
+        rotate = 'rotate' in state and self._active_handle in self._corner_order
+        move = self._active_handle == 'C'
+        resize = self._active_handle and not move
+
+        xdata, ydata = self._get_data_coords(event)
+        if resize:
+            inv_tr = self._get_rotation_transform().inverted()
+            xdata, ydata = inv_tr.transform([xdata, ydata])
+            eventpress.xdata, eventpress.ydata = inv_tr.transform(
+                (eventpress.xdata, eventpress.ydata))
+
+        dx = xdata - eventpress.xdata
+        dy = ydata - eventpress.ydata
+        # refmax is used when moving the corner handle with the square state
+        # and is the maximum between refx and refy
+        refmax = None
+        if self._use_data_coordinates:
+            refx, refy = dx, dy
+        else:
+            # Get dx/dy in display coordinates
+            refx = event.x - eventpress.x
+            refy = event.y - eventpress.y
+
+        x0, x1, y0, y1 = self._extents_on_press
+        # rotate an existing shape
+        if rotate:
+            # calculate angle abc
+            a = (eventpress.xdata, eventpress.ydata)
+            b = self.center
+            c = (xdata, ydata)
+            angle = (np.arctan2(c[1]-b[1], c[0]-b[0]) -
+                     np.arctan2(a[1]-b[1], a[0]-b[0]))
+            self.rotation = np.rad2deg(self._rotation_on_press + angle)
+
+        elif resize:
+            size_on_press = [x1 - x0, y1 - y0]
+            center = (x0 + size_on_press[0] / 2, y0 + size_on_press[1] / 2)
+
+            # Keeping the center fixed
+            if 'center' in state:
+                # hh, hw are half-height and half-width
+                if 'square' in state:
+                    # when using a corner, find which reference to use
+                    if self._active_handle in self._corner_order:
+                        refmax = max(refx, refy, key=abs)
+                    if self._active_handle in ['E', 'W'] or refmax == refx:
+                        hw = xdata - center[0]
+                        hh = hw / self._aspect_ratio_correction
+                    else:
+                        hh = ydata - center[1]
+                        hw = hh * self._aspect_ratio_correction
+                else:
+                    hw = size_on_press[0] / 2
+                    hh = size_on_press[1] / 2
+                    # cancel changes in perpendicular direction
+                    if self._active_handle in ['E', 'W'] + self._corner_order:
+                        hw = abs(xdata - center[0])
+                    if self._active_handle in ['N', 'S'] + self._corner_order:
+                        hh = abs(ydata - center[1])
+
+                x0, x1, y0, y1 = (center[0] - hw, center[0] + hw,
+                                  center[1] - hh, center[1] + hh)
+
+            else:
+                # change sign of relative changes to simplify calculation
+                # Switch variables so that x1 and/or y1 are updated on move
+                if 'W' in self._active_handle:
+                    x0 = x1
+                if 'S' in self._active_handle:
+                    y0 = y1
+                if self._active_handle in ['E', 'W'] + self._corner_order:
+                    x1 = xdata
+                if self._active_handle in ['N', 'S'] + self._corner_order:
+                    y1 = ydata
+                if 'square' in state:
+                    # when using a corner, find which reference to use
+                    if self._active_handle in self._corner_order:
+                        refmax = max(refx, refy, key=abs)
+                    if self._active_handle in ['E', 'W'] or refmax == refx:
+                        sign = np.sign(ydata - y0)
+                        y1 = y0 + sign * abs(x1 - x0) / self._aspect_ratio_correction
+                    else:
+                        sign = np.sign(xdata - x0)
+                        x1 = x0 + sign * abs(y1 - y0) * self._aspect_ratio_correction
+
+        elif move:
+            x0, x1, y0, y1 = self._extents_on_press
+            dx = xdata - eventpress.xdata
+            dy = ydata - eventpress.ydata
+            x0 += dx
+            x1 += dx
+            y0 += dy
+            y1 += dy
+
+        else:
+            # Create a new shape
+            self._rotation = 0
+            # Don't create a new rectangle if there is already one when
+            # ignore_event_outside=True
+            if ((self.ignore_event_outside and self._selection_completed) or
+                    not self._allow_creation):
+                return
+            center = [eventpress.xdata, eventpress.ydata]
+            dx = (xdata - center[0]) / 2
+            dy = (ydata - center[1]) / 2
+
+            # square shape
+            if 'square' in state:
+                refmax = max(refx, refy, key=abs)
+                if refmax == refx:
+                    dy = np.sign(dy) * abs(dx) / self._aspect_ratio_correction
+                else:
+                    dx = np.sign(dx) * abs(dy) * self._aspect_ratio_correction
+
+            # from center
+            if 'center' in state:
+                dx *= 2
+                dy *= 2
+
+            # from corner
+            else:
+                center[0] += dx
+                center[1] += dy
+
+            x0, x1, y0, y1 = (center[0] - dx, center[0] + dx,
+                              center[1] - dy, center[1] + dy)
+
+        self.extents = x0, x1, y0, y1
+
+    @property
+    def _rect_bbox(self):
+        return self._selection_artist.get_bbox().bounds
+
+    def _set_aspect_ratio_correction(self):
+        aspect_ratio = self.ax._get_aspect_ratio()
+        self._selection_artist._aspect_ratio_correction = aspect_ratio
+        if self._use_data_coordinates:
+            self._aspect_ratio_correction = 1
+        else:
+            self._aspect_ratio_correction = aspect_ratio
+
+    def _get_rotation_transform(self):
+        aspect_ratio = self.ax._get_aspect_ratio()
+        return Affine2D().translate(-self.center[0], -self.center[1]) \
+                .scale(1, aspect_ratio) \
+                .rotate(self._rotation) \
+                .scale(1, 1 / aspect_ratio) \
+                .translate(*self.center)
+
+    @property
+    def corners(self):
+        """
+        Corners of rectangle in data coordinates from lower left,
+        moving clockwise.
+        """
+        x0, y0, width, height = self._rect_bbox
+        xc = x0, x0 + width, x0 + width, x0
+        yc = y0, y0, y0 + height, y0 + height
+        transform = self._get_rotation_transform()
+        coords = transform.transform(np.array([xc, yc]).T).T
+        return coords[0], coords[1]
+
+    @property
+    def edge_centers(self):
+        """
+        Midpoint of rectangle edges in data coordinates from left,
+        moving anti-clockwise.
+        """
+        x0, y0, width, height = self._rect_bbox
+        w = width / 2.
+        h = height / 2.
+        xe = x0, x0 + w, x0 + width, x0 + w
+        ye = y0 + h, y0, y0 + h, y0 + height
+        transform = self._get_rotation_transform()
+        coords = transform.transform(np.array([xe, ye]).T).T
+        return coords[0], coords[1]
+
+    @property
+    def center(self):
+        """Center of rectangle in data coordinates."""
+        x0, y0, width, height = self._rect_bbox
+        return x0 + width / 2., y0 + height / 2.
+
+    @property
+    def extents(self):
+        """
+        Return (xmin, xmax, ymin, ymax) in data coordinates as defined by the
+        bounding box before rotation.
+        """
+        x0, y0, width, height = self._rect_bbox
+        xmin, xmax = sorted([x0, x0 + width])
+        ymin, ymax = sorted([y0, y0 + height])
+        return xmin, xmax, ymin, ymax
+
+    @extents.setter
+    def extents(self, extents):
+        # Update displayed shape
+        self._draw_shape(extents)
+        if self._interactive:
+            # Update displayed handles
+            self._corner_handles.set_data(*self.corners)
+            self._edge_handles.set_data(*self.edge_centers)
+            x, y = self.center
+            self._center_handle.set_data([x], [y])
+        self.set_visible(self._visible)
+        self.update()
+
+    @property
+    def rotation(self):
+        """
+        Rotation in degree in interval [-45°, 45°]. The rotation is limited in
+        range to keep the implementation simple.
+        """
+        return np.rad2deg(self._rotation)
+
+    @rotation.setter
+    def rotation(self, value):
+        # Restrict to a limited range of rotation [-45°, 45°] to avoid changing
+        # order of handles
+        if -45 <= value and value <= 45:
+            self._rotation = np.deg2rad(value)
+            # call extents setter to draw shape and update handles positions
+            self.extents = self.extents
+
+    def _draw_shape(self, extents):
+        x0, x1, y0, y1 = extents
+        xmin, xmax = sorted([x0, x1])
+        ymin, ymax = sorted([y0, y1])
+        xlim = sorted(self.ax.get_xlim())
+        ylim = sorted(self.ax.get_ylim())
+
+        xmin = max(xlim[0], xmin)
+        ymin = max(ylim[0], ymin)
+        xmax = min(xmax, xlim[1])
+        ymax = min(ymax, ylim[1])
+
+        self._selection_artist.set_x(xmin)
+        self._selection_artist.set_y(ymin)
+        self._selection_artist.set_width(xmax - xmin)
+        self._selection_artist.set_height(ymax - ymin)
+        self._selection_artist.set_angle(self.rotation)
+
+    def _set_active_handle(self, event):
+        """Set active handle based on the location of the mouse event."""
+        # Note: event.xdata/ydata in data coordinates, event.x/y in pixels
+        c_idx, c_dist = self._corner_handles.closest(event.x, event.y)
+        e_idx, e_dist = self._edge_handles.closest(event.x, event.y)
+        m_idx, m_dist = self._center_handle.closest(event.x, event.y)
+
+        if 'move' in self._state:
+            self._active_handle = 'C'
+        # Set active handle as closest handle, if mouse click is close enough.
+        elif m_dist < self.grab_range * 2:
+            # Prioritise center handle over other handles
+            self._active_handle = 'C'
+        elif c_dist > self.grab_range and e_dist > self.grab_range:
+            # Not close to any handles
+            if self.drag_from_anywhere and self._contains(event):
+                # Check if we've clicked inside the region
+                self._active_handle = 'C'
+            else:
+                self._active_handle = None
+                return
+        elif c_dist < e_dist:
+            # Closest to a corner handle
+            self._active_handle = self._corner_order[c_idx]
+        else:
+            # Closest to an edge handle
+            self._active_handle = self._edge_order[e_idx]
+
+    def _contains(self, event):
+        """Return True if event is within the patch."""
+        return self._selection_artist.contains(event, radius=0)[0]
+
+    @property
+    def geometry(self):
+        """
+        Return an array of shape (2, 5) containing the
+        x (``RectangleSelector.geometry[1, :]``) and
+        y (``RectangleSelector.geometry[0, :]``) data coordinates of the four
+        corners of the rectangle starting and ending in the top left corner.
+        """
+        if hasattr(self._selection_artist, 'get_verts'):
+            xfm = self.ax.transData.inverted()
+            y, x = xfm.transform(self._selection_artist.get_verts()).T
+            return np.array([x, y])
+        else:
+            return np.array(self._selection_artist.get_data())
+
+
+@_docstring.Substitution(_RECTANGLESELECTOR_PARAMETERS_DOCSTRING.replace(
+    '__ARTIST_NAME__', 'ellipse'))
+class EllipseSelector(RectangleSelector):
+    """
+    Select an elliptical region of an Axes.
+
+    For the cursor to remain responsive you must keep a reference to it.
+
+    Press and release events triggered at the same coordinates outside the
+    selection will clear the selector, except when
+    ``ignore_event_outside=True``.
+
+    %s
+
+    Examples
+    --------
+    :doc:`/gallery/widgets/rectangle_selector`
+    """
+    def _init_shape(self, **props):
+        return Ellipse((0, 0), 0, 1, visible=False, **props)
+
+    def _draw_shape(self, extents):
+        x0, x1, y0, y1 = extents
+        xmin, xmax = sorted([x0, x1])
+        ymin, ymax = sorted([y0, y1])
+        center = [x0 + (x1 - x0) / 2., y0 + (y1 - y0) / 2.]
+        a = (xmax - xmin) / 2.
+        b = (ymax - ymin) / 2.
+
+        self._selection_artist.center = center
+        self._selection_artist.width = 2 * a
+        self._selection_artist.height = 2 * b
+        self._selection_artist.angle = self.rotation
+
+    @property
+    def _rect_bbox(self):
+        x, y = self._selection_artist.center
+        width = self._selection_artist.width
+        height = self._selection_artist.height
+        return x - width / 2., y - height / 2., width, height
+
+
+class LassoSelector(_SelectorWidget):
+    """
+    Selection curve of an arbitrary shape.
+
+    For the selector to remain responsive you must keep a reference to it.
+
+    The selected path can be used in conjunction with `~.Path.contains_point`
+    to select data points from an image.
+
+    In contrast to `Lasso`, `LassoSelector` is written with an interface
+    similar to `RectangleSelector` and `SpanSelector`, and will continue to
+    interact with the Axes until disconnected.
+
+    Example usage::
+
+        ax = plt.subplot()
+        ax.plot(x, y)
+
+        def onselect(verts):
+            print(verts)
+        lasso = LassoSelector(ax, onselect)
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    onselect : function, optional
+        Whenever the lasso is released, the *onselect* function is called and
+        passed the vertices of the selected path.
+    useblit : bool, default: True
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+    props : dict, optional
+        Properties with which the line is drawn, see `.Line2D`
+        for valid properties. Default values are defined in ``mpl.rcParams``.
+    button : `.MouseButton` or list of `.MouseButton`, optional
+        The mouse buttons used for rectangle selection.  Default is ``None``,
+        which corresponds to all buttons.
+    """
+
+    def __init__(self, ax, onselect=None, *, useblit=True, props=None, button=None):
+        super().__init__(ax, onselect, useblit=useblit, button=button)
+        self.verts = None
+        props = {
+            **(props if props is not None else {}),
+            # Note that self.useblit may be != useblit, if the canvas doesn't
+            # support blitting.
+            'animated': self.useblit, 'visible': False,
+        }
+        line = Line2D([], [], **props)
+        self.ax.add_line(line)
+        self._selection_artist = line
+
+    def _press(self, event):
+        self.verts = [self._get_data(event)]
+        self._selection_artist.set_visible(True)
+
+    def _release(self, event):
+        if self.verts is not None:
+            self.verts.append(self._get_data(event))
+            self.onselect(self.verts)
+        self._selection_artist.set_data([[], []])
+        self._selection_artist.set_visible(False)
+        self.verts = None
+
+    def _onmove(self, event):
+        if self.verts is None:
+            return
+        self.verts.append(self._get_data(event))
+        self._selection_artist.set_data(list(zip(*self.verts)))
+
+        self.update()
+
+
+class PolygonSelector(_SelectorWidget):
+    """
+    Select a polygon region of an Axes.
+
+    Place vertices with each mouse click, and make the selection by completing
+    the polygon (clicking on the first vertex). Once drawn individual vertices
+    can be moved by clicking and dragging with the left mouse button, or
+    removed by clicking the right mouse button.
+
+    In addition, the following modifier keys can be used:
+
+    - Hold *ctrl* and click and drag a vertex to reposition it before the
+      polygon has been completed.
+    - Hold the *shift* key and click and drag anywhere in the Axes to move
+      all vertices.
+    - Press the *esc* key to start a new polygon.
+
+    For the selector to remain responsive you must keep a reference to it.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+
+    onselect : function, optional
+        When a polygon is completed or modified after completion,
+        the *onselect* function is called and passed a list of the vertices as
+        ``(xdata, ydata)`` tuples.
+
+    useblit : bool, default: False
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+
+    props : dict, optional
+        Properties with which the line is drawn, see `.Line2D` for valid properties.
+        Default::
+
+            dict(color='k', linestyle='-', linewidth=2, alpha=0.5)
+
+    handle_props : dict, optional
+        Artist properties for the markers drawn at the vertices of the polygon.
+        See the marker arguments in `.Line2D` for valid
+        properties.  Default values are defined in ``mpl.rcParams`` except for
+        the default value of ``markeredgecolor`` which will be the same as the
+        ``color`` property in *props*.
+
+    grab_range : float, default: 10
+        A vertex is selected (to complete the polygon or to move a vertex) if
+        the mouse click is within *grab_range* pixels of the vertex.
+
+    draw_bounding_box : bool, optional
+        If `True`, a bounding box will be drawn around the polygon selector
+        once it is complete. This box can be used to move and resize the
+        selector.
+
+    box_handle_props : dict, optional
+        Properties to set for the box handles. See the documentation for the
+        *handle_props* argument to `RectangleSelector` for more info.
+
+    box_props : dict, optional
+        Properties to set for the box. See the documentation for the *props*
+        argument to `RectangleSelector` for more info.
+
+    Examples
+    --------
+    :doc:`/gallery/widgets/polygon_selector_simple`
+    :doc:`/gallery/widgets/polygon_selector_demo`
+
+    Notes
+    -----
+    If only one point remains after removing points, the selector reverts to an
+    incomplete state and you can start drawing a new polygon from the existing
+    point.
+    """
+
+    def __init__(self, ax, onselect=None, *, useblit=False,
+                 props=None, handle_props=None, grab_range=10,
+                 draw_bounding_box=False, box_handle_props=None,
+                 box_props=None):
+        # The state modifiers 'move', 'square', and 'center' are expected by
+        # _SelectorWidget but are not supported by PolygonSelector
+        # Note: could not use the existing 'move' state modifier in-place of
+        # 'move_all' because _SelectorWidget automatically discards 'move'
+        # from the state on button release.
+        state_modifier_keys = dict(clear='escape', move_vertex='control',
+                                   move_all='shift', move='not-applicable',
+                                   square='not-applicable',
+                                   center='not-applicable',
+                                   rotate='not-applicable')
+        super().__init__(ax, onselect, useblit=useblit,
+                         state_modifier_keys=state_modifier_keys)
+
+        self._xys = [(0, 0)]
+
+        if props is None:
+            props = dict(color='k', linestyle='-', linewidth=2, alpha=0.5)
+        props = {**props, 'animated': self.useblit}
+        self._selection_artist = line = Line2D([], [], **props)
+        self.ax.add_line(line)
+
+        if handle_props is None:
+            handle_props = dict(markeredgecolor='k',
+                                markerfacecolor=props.get('color', 'k'))
+        self._handle_props = handle_props
+        self._polygon_handles = ToolHandles(self.ax, [], [],
+                                            useblit=self.useblit,
+                                            marker_props=self._handle_props)
+
+        self._active_handle_idx = -1
+        self.grab_range = grab_range
+
+        self.set_visible(True)
+        self._draw_box = draw_bounding_box
+        self._box = None
+
+        if box_handle_props is None:
+            box_handle_props = {}
+        self._box_handle_props = self._handle_props.update(box_handle_props)
+        self._box_props = box_props
+
+    def _get_bbox(self):
+        return self._selection_artist.get_bbox()
+
+    def _add_box(self):
+        self._box = RectangleSelector(self.ax,
+                                      useblit=self.useblit,
+                                      grab_range=self.grab_range,
+                                      handle_props=self._box_handle_props,
+                                      props=self._box_props,
+                                      interactive=True)
+        self._box._state_modifier_keys.pop('rotate')
+        self._box.connect_event('motion_notify_event', self._scale_polygon)
+        self._update_box()
+        # Set state that prevents the RectangleSelector from being created
+        # by the user
+        self._box._allow_creation = False
+        self._box._selection_completed = True
+        self._draw_polygon()
+
+    def _remove_box(self):
+        if self._box is not None:
+            self._box.set_visible(False)
+            self._box = None
+
+    def _update_box(self):
+        # Update selection box extents to the extents of the polygon
+        if self._box is not None:
+            bbox = self._get_bbox()
+            self._box.extents = [bbox.x0, bbox.x1, bbox.y0, bbox.y1]
+            # Save a copy
+            self._old_box_extents = self._box.extents
+
+    def _scale_polygon(self, event):
+        """
+        Scale the polygon selector points when the bounding box is moved or
+        scaled.
+
+        This is set as a callback on the bounding box RectangleSelector.
+        """
+        if not self._selection_completed:
+            return
+
+        if self._old_box_extents == self._box.extents:
+            return
+
+        # Create transform from old box to new box
+        x1, y1, w1, h1 = self._box._rect_bbox
+        old_bbox = self._get_bbox()
+        t = (transforms.Affine2D()
+             .translate(-old_bbox.x0, -old_bbox.y0)
+             .scale(1 / old_bbox.width, 1 / old_bbox.height)
+             .scale(w1, h1)
+             .translate(x1, y1))
+
+        # Update polygon verts.  Must be a list of tuples for consistency.
+        new_verts = [(x, y) for x, y in t.transform(np.array(self.verts))]
+        self._xys = [*new_verts, new_verts[0]]
+        self._draw_polygon()
+        self._old_box_extents = self._box.extents
+
+    @property
+    def _handles_artists(self):
+        return self._polygon_handles.artists
+
+    def _remove_vertex(self, i):
+        """Remove vertex with index i."""
+        if (len(self._xys) > 2 and
+                self._selection_completed and
+                i in (0, len(self._xys) - 1)):
+            # If selecting the first or final vertex, remove both first and
+            # last vertex as they are the same for a closed polygon
+            self._xys.pop(0)
+            self._xys.pop(-1)
+            # Close the polygon again by appending the new first vertex to the
+            # end
+            self._xys.append(self._xys[0])
+        else:
+            self._xys.pop(i)
+        if len(self._xys) <= 2:
+            # If only one point left, return to incomplete state to let user
+            # start drawing again
+            self._selection_completed = False
+            self._remove_box()
+
+    def _press(self, event):
+        """Button press event handler."""
+        # Check for selection of a tool handle.
+        if ((self._selection_completed or 'move_vertex' in self._state)
+                and len(self._xys) > 0):
+            h_idx, h_dist = self._polygon_handles.closest(event.x, event.y)
+            if h_dist < self.grab_range:
+                self._active_handle_idx = h_idx
+        # Save the vertex positions at the time of the press event (needed to
+        # support the 'move_all' state modifier).
+        self._xys_at_press = self._xys.copy()
+
+    def _release(self, event):
+        """Button release event handler."""
+        # Release active tool handle.
+        if self._active_handle_idx >= 0:
+            if event.button == 3:
+                self._remove_vertex(self._active_handle_idx)
+                self._draw_polygon()
+            self._active_handle_idx = -1
+
+        # Complete the polygon.
+        elif len(self._xys) > 3 and self._xys[-1] == self._xys[0]:
+            self._selection_completed = True
+            if self._draw_box and self._box is None:
+                self._add_box()
+
+        # Place new vertex.
+        elif (not self._selection_completed
+              and 'move_all' not in self._state
+              and 'move_vertex' not in self._state):
+            self._xys.insert(-1, self._get_data_coords(event))
+
+        if self._selection_completed:
+            self.onselect(self.verts)
+
+    def onmove(self, event):
+        """Cursor move event handler and validator."""
+        # Method overrides _SelectorWidget.onmove because the polygon selector
+        # needs to process the move callback even if there is no button press.
+        # _SelectorWidget.onmove include logic to ignore move event if
+        # _eventpress is None.
+        if self.ignore(event):
+            # Hide the cursor when interactive zoom/pan is active
+            if not self.canvas.widgetlock.available(self) and self._xys:
+                self._xys[-1] = (np.nan, np.nan)
+                self._draw_polygon()
+            return False
+
+        else:
+            event = self._clean_event(event)
+            self._onmove(event)
+            return True
+
+    def _onmove(self, event):
+        """Cursor move event handler."""
+        # Move the active vertex (ToolHandle).
+        if self._active_handle_idx >= 0:
+            idx = self._active_handle_idx
+            self._xys[idx] = self._get_data_coords(event)
+            # Also update the end of the polygon line if the first vertex is
+            # the active handle and the polygon is completed.
+            if idx == 0 and self._selection_completed:
+                self._xys[-1] = self._get_data_coords(event)
+
+        # Move all vertices.
+        elif 'move_all' in self._state and self._eventpress:
+            xdata, ydata = self._get_data_coords(event)
+            dx = xdata - self._eventpress.xdata
+            dy = ydata - self._eventpress.ydata
+            for k in range(len(self._xys)):
+                x_at_press, y_at_press = self._xys_at_press[k]
+                self._xys[k] = x_at_press + dx, y_at_press + dy
+
+        # Do nothing if completed or waiting for a move.
+        elif (self._selection_completed
+              or 'move_vertex' in self._state or 'move_all' in self._state):
+            return
+
+        # Position pending vertex.
+        else:
+            # Calculate distance to the start vertex.
+            x0, y0 = \
+                self._selection_artist.get_transform().transform(self._xys[0])
+            v0_dist = np.hypot(x0 - event.x, y0 - event.y)
+            # Lock on to the start vertex if near it and ready to complete.
+            if len(self._xys) > 3 and v0_dist < self.grab_range:
+                self._xys[-1] = self._xys[0]
+            else:
+                self._xys[-1] = self._get_data_coords(event)
+
+        self._draw_polygon()
+
+    def _on_key_press(self, event):
+        """Key press event handler."""
+        # Remove the pending vertex if entering the 'move_vertex' or
+        # 'move_all' mode
+        if (not self._selection_completed
+                and ('move_vertex' in self._state or
+                     'move_all' in self._state)):
+            self._xys.pop()
+            self._draw_polygon()
+
+    def _on_key_release(self, event):
+        """Key release event handler."""
+        # Add back the pending vertex if leaving the 'move_vertex' or
+        # 'move_all' mode (by checking the released key)
+        if (not self._selection_completed
+                and
+                (event.key == self._state_modifier_keys.get('move_vertex')
+                 or event.key == self._state_modifier_keys.get('move_all'))):
+            self._xys.append(self._get_data_coords(event))
+            self._draw_polygon()
+        # Reset the polygon if the released key is the 'clear' key.
+        elif event.key == self._state_modifier_keys.get('clear'):
+            event = self._clean_event(event)
+            self._xys = [self._get_data_coords(event)]
+            self._selection_completed = False
+            self._remove_box()
+            self.set_visible(True)
+
+    def _draw_polygon_without_update(self):
+        """Redraw the polygon based on new vertex positions, no update()."""
+        xs, ys = zip(*self._xys) if self._xys else ([], [])
+        self._selection_artist.set_data(xs, ys)
+        self._update_box()
+        # Only show one tool handle at the start and end vertex of the polygon
+        # if the polygon is completed or the user is locked on to the start
+        # vertex.
+        if (self._selection_completed
+                or (len(self._xys) > 3
+                    and self._xys[-1] == self._xys[0])):
+            self._polygon_handles.set_data(xs[:-1], ys[:-1])
+        else:
+            self._polygon_handles.set_data(xs, ys)
+
+    def _draw_polygon(self):
+        """Redraw the polygon based on the new vertex positions."""
+        self._draw_polygon_without_update()
+        self.update()
+
+    @property
+    def verts(self):
+        """The polygon vertices, as a list of ``(x, y)`` pairs."""
+        return self._xys[:-1]
+
+    @verts.setter
+    def verts(self, xys):
+        """
+        Set the polygon vertices.
+
+        This will remove any preexisting vertices, creating a complete polygon
+        with the new vertices.
+        """
+        self._xys = [*xys, xys[0]]
+        self._selection_completed = True
+        self.set_visible(True)
+        if self._draw_box and self._box is None:
+            self._add_box()
+        self._draw_polygon()
+
+    def _clear_without_update(self):
+        self._selection_completed = False
+        self._xys = [(0, 0)]
+        self._draw_polygon_without_update()
+
+
+class Lasso(AxesWidget):
+    """
+    Selection curve of an arbitrary shape.
+
+    The selected path can be used in conjunction with
+    `~matplotlib.path.Path.contains_point` to select data points from an image.
+
+    Unlike `LassoSelector`, this must be initialized with a starting
+    point *xy*, and the `Lasso` events are destroyed upon release.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+        The parent Axes for the widget.
+    xy : (float, float)
+        Coordinates of the start of the lasso.
+    callback : callable
+        Whenever the lasso is released, the *callback* function is called and
+        passed the vertices of the selected path.
+    useblit : bool, default: True
+        Whether to use blitting for faster drawing (if supported by the
+        backend). See the tutorial :ref:`blitting`
+        for details.
+    props: dict, optional
+        Lasso line properties. See `.Line2D` for valid properties.
+        Default *props* are::
+
+            {'linestyle' : '-', 'color' : 'black', 'lw' : 2}
+
+        .. versionadded:: 3.9
+    """
+    def __init__(self, ax, xy, callback, *, useblit=True, props=None):
+        super().__init__(ax)
+
+        self.useblit = useblit and self.canvas.supports_blit
+        if self.useblit:
+            self.background = self.canvas.copy_from_bbox(self.ax.bbox)
+
+        style = {'linestyle': '-', 'color': 'black', 'lw': 2}
+
+        if props is not None:
+            style.update(props)
+
+        x, y = xy
+        self.verts = [(x, y)]
+        self.line = Line2D([x], [y], **style)
+        self.ax.add_line(self.line)
+        self.callback = callback
+        self.connect_event('button_release_event', self.onrelease)
+        self.connect_event('motion_notify_event', self.onmove)
+
+    def onrelease(self, event):
+        if self.ignore(event):
+            return
+        if self.verts is not None:
+            self.verts.append(self._get_data_coords(event))
+            if len(self.verts) > 2:
+                self.callback(self.verts)
+            self.line.remove()
+        self.verts = None
+        self.disconnect_events()
+
+    def onmove(self, event):
+        if (self.ignore(event)
+                or self.verts is None
+                or event.button != 1
+                or not self.ax.contains(event)[0]):
+            return
+        self.verts.append(self._get_data_coords(event))
+        self.line.set_data(list(zip(*self.verts)))
+
+        if self.useblit:
+            self.canvas.restore_region(self.background)
+            self.ax.draw_artist(self.line)
+            self.canvas.blit(self.ax.bbox)
+        else:
+            self.canvas.draw_idle()
diff --git a/lib/python3.12/site-packages/matplotlib/widgets.pyi b/lib/python3.12/site-packages/matplotlib/widgets.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..0fcd1990e17e0a005532522de33bb27cf1d05d17
--- /dev/null
+++ b/lib/python3.12/site-packages/matplotlib/widgets.pyi
@@ -0,0 +1,488 @@
+from .artist import Artist
+from .axes import Axes
+from .backend_bases import FigureCanvasBase, Event, MouseEvent, MouseButton
+from .collections import LineCollection
+from .figure import Figure
+from .lines import Line2D
+from .patches import Polygon, Rectangle
+from .text import Text
+
+import PIL.Image
+
+from collections.abc import Callable, Collection, Iterable, Sequence
+from typing import Any, Literal
+from numpy.typing import ArrayLike
+from .typing import ColorType
+import numpy as np
+
+class LockDraw:
+    def __init__(self) -> None: ...
+    def __call__(self, o: Any) -> None: ...
+    def release(self, o: Any) -> None: ...
+    def available(self, o: Any) -> bool: ...
+    def isowner(self, o: Any) -> bool: ...
+    def locked(self) -> bool: ...
+
+class Widget:
+    drawon: bool
+    eventson: bool
+    active: bool
+    def set_active(self, active: bool) -> None: ...
+    def get_active(self) -> None: ...
+    def ignore(self, event) -> bool: ...
+
+class AxesWidget(Widget):
+    ax: Axes
+    def __init__(self, ax: Axes) -> None: ...
+    @property
+    def canvas(self) -> FigureCanvasBase | None: ...
+    def connect_event(self, event: Event, callback: Callable) -> None: ...
+    def disconnect_events(self) -> None: ...
+
+class Button(AxesWidget):
+    label: Text
+    color: ColorType
+    hovercolor: ColorType
+    def __init__(
+        self,
+        ax: Axes,
+        label: str,
+        image: ArrayLike | PIL.Image.Image | None = ...,
+        color: ColorType = ...,
+        hovercolor: ColorType = ...,
+        *,
+        useblit: bool = ...
+    ) -> None: ...
+    def on_clicked(self, func: Callable[[Event], Any]) -> int: ...
+    def disconnect(self, cid: int) -> None: ...
+
+class SliderBase(AxesWidget):
+    orientation: Literal["horizontal", "vertical"]
+    closedmin: bool
+    closedmax: bool
+    valmin: float
+    valmax: float
+    valstep: float | ArrayLike | None
+    drag_active: bool
+    valfmt: str
+    def __init__(
+        self,
+        ax: Axes,
+        orientation: Literal["horizontal", "vertical"],
+        closedmin: bool,
+        closedmax: bool,
+        valmin: float,
+        valmax: float,
+        valfmt: str,
+        dragging: Slider | None,
+        valstep: float | ArrayLike | None,
+    ) -> None: ...
+    def disconnect(self, cid: int) -> None: ...
+    def reset(self) -> None: ...
+
+class Slider(SliderBase):
+    slidermin: Slider | None
+    slidermax: Slider | None
+    val: float
+    valinit: float
+    track: Rectangle
+    poly: Polygon
+    hline: Line2D
+    vline: Line2D
+    label: Text
+    valtext: Text
+    def __init__(
+        self,
+        ax: Axes,
+        label: str,
+        valmin: float,
+        valmax: float,
+        *,
+        valinit: float = ...,
+        valfmt: str | None = ...,
+        closedmin: bool = ...,
+        closedmax: bool = ...,
+        slidermin: Slider | None = ...,
+        slidermax: Slider | None = ...,
+        dragging: bool = ...,
+        valstep: float | ArrayLike | None = ...,
+        orientation: Literal["horizontal", "vertical"] = ...,
+        initcolor: ColorType = ...,
+        track_color: ColorType = ...,
+        handle_style: dict[str, Any] | None = ...,
+        **kwargs
+    ) -> None: ...
+    def set_val(self, val: float) -> None: ...
+    def on_changed(self, func: Callable[[float], Any]) -> int: ...
+
+class RangeSlider(SliderBase):
+    val: tuple[float, float]
+    valinit: tuple[float, float]
+    track: Rectangle
+    poly: Polygon
+    label: Text
+    valtext: Text
+    def __init__(
+        self,
+        ax: Axes,
+        label: str,
+        valmin: float,
+        valmax: float,
+        *,
+        valinit: tuple[float, float] | None = ...,
+        valfmt: str | None = ...,
+        closedmin: bool = ...,
+        closedmax: bool = ...,
+        dragging: bool = ...,
+        valstep: float | ArrayLike | None = ...,
+        orientation: Literal["horizontal", "vertical"] = ...,
+        track_color: ColorType = ...,
+        handle_style: dict[str, Any] | None = ...,
+        **kwargs
+    ) -> None: ...
+    def set_min(self, min: float) -> None: ...
+    def set_max(self, max: float) -> None: ...
+    def set_val(self, val: ArrayLike) -> None: ...
+    def on_changed(self, func: Callable[[tuple[float, float]], Any]) -> int: ...
+
+class CheckButtons(AxesWidget):
+    labels: list[Text]
+    def __init__(
+        self,
+        ax: Axes,
+        labels: Sequence[str],
+        actives: Iterable[bool] | None = ...,
+        *,
+        useblit: bool = ...,
+        label_props: dict[str, Any] | None = ...,
+        frame_props: dict[str, Any] | None = ...,
+        check_props: dict[str, Any] | None = ...,
+    ) -> None: ...
+    def set_label_props(self, props: dict[str, Any]) -> None: ...
+    def set_frame_props(self, props: dict[str, Any]) -> None: ...
+    def set_check_props(self, props: dict[str, Any]) -> None: ...
+    def set_active(self, index: int, state: bool | None = ...) -> None: ...  # type: ignore[override]
+    def clear(self) -> None: ...
+    def get_status(self) -> list[bool]: ...
+    def get_checked_labels(self) -> list[str]: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
+    def disconnect(self, cid: int) -> None: ...
+
+class TextBox(AxesWidget):
+    label: Text
+    text_disp: Text
+    cursor_index: int
+    cursor: LineCollection
+    color: ColorType
+    hovercolor: ColorType
+    capturekeystrokes: bool
+    def __init__(
+        self,
+        ax: Axes,
+        label: str,
+        initial: str = ...,
+        *,
+        color: ColorType = ...,
+        hovercolor: ColorType = ...,
+        label_pad: float = ...,
+        textalignment: Literal["left", "center", "right"] = ...,
+    ) -> None: ...
+    @property
+    def text(self) -> str: ...
+    def set_val(self, val: str) -> None: ...
+    def begin_typing(self) -> None: ...
+    def stop_typing(self) -> None: ...
+    def on_text_change(self, func: Callable[[str], Any]) -> int: ...
+    def on_submit(self, func: Callable[[str], Any]) -> int: ...
+    def disconnect(self, cid: int) -> None: ...
+
+class RadioButtons(AxesWidget):
+    activecolor: ColorType
+    value_selected: str
+    labels: list[Text]
+    def __init__(
+        self,
+        ax: Axes,
+        labels: Iterable[str],
+        active: int = ...,
+        activecolor: ColorType | None = ...,
+        *,
+        useblit: bool = ...,
+        label_props: dict[str, Any] | Sequence[dict[str, Any]] | None = ...,
+        radio_props: dict[str, Any] | None = ...,
+    ) -> None: ...
+    def set_label_props(self, props: dict[str, Any]) -> None: ...
+    def set_radio_props(self, props: dict[str, Any]) -> None: ...
+    def set_active(self, index: int) -> None: ...
+    def clear(self) -> None: ...
+    def on_clicked(self, func: Callable[[str | None], Any]) -> int: ...
+    def disconnect(self, cid: int) -> None: ...
+
+class SubplotTool(Widget):
+    figure: Figure
+    targetfig: Figure
+    buttonreset: Button
+    def __init__(self, targetfig: Figure, toolfig: Figure) -> None: ...
+
+class Cursor(AxesWidget):
+    visible: bool
+    horizOn: bool
+    vertOn: bool
+    useblit: bool
+    lineh: Line2D
+    linev: Line2D
+    background: Any
+    needclear: bool
+    def __init__(
+        self,
+        ax: Axes,
+        *,
+        horizOn: bool = ...,
+        vertOn: bool = ...,
+        useblit: bool = ...,
+        **lineprops
+    ) -> None: ...
+    def clear(self, event: Event) -> None: ...
+    def onmove(self, event: Event) -> None: ...
+
+class MultiCursor(Widget):
+    axes: Sequence[Axes]
+    horizOn: bool
+    vertOn: bool
+    visible: bool
+    useblit: bool
+    vlines: list[Line2D]
+    hlines: list[Line2D]
+    def __init__(
+        self,
+        canvas: Any,
+        axes: Sequence[Axes],
+        *,
+        useblit: bool = ...,
+        horizOn: bool = ...,
+        vertOn: bool = ...,
+        **lineprops
+    ) -> None: ...
+    def connect(self) -> None: ...
+    def disconnect(self) -> None: ...
+    def clear(self, event: Event) -> None: ...
+    def onmove(self, event: Event) -> None: ...
+
+class _SelectorWidget(AxesWidget):
+    onselect: Callable[[float, float], Any]
+    useblit: bool
+    background: Any
+    validButtons: list[MouseButton]
+    def __init__(
+        self,
+        ax: Axes,
+        onselect: Callable[[float, float], Any] | None = ...,
+        useblit: bool = ...,
+        button: MouseButton | Collection[MouseButton] | None = ...,
+        state_modifier_keys: dict[str, str] | None = ...,
+        use_data_coordinates: bool = ...,
+    ) -> None: ...
+    def update_background(self, event: Event) -> None: ...
+    def connect_default_events(self) -> None: ...
+    def ignore(self, event: Event) -> bool: ...
+    def update(self) -> None: ...
+    def press(self, event: Event) -> bool: ...
+    def release(self, event: Event) -> bool: ...
+    def onmove(self, event: Event) -> bool: ...
+    def on_scroll(self, event: Event) -> None: ...
+    def on_key_press(self, event: Event) -> None: ...
+    def on_key_release(self, event: Event) -> None: ...
+    def set_visible(self, visible: bool) -> None: ...
+    def get_visible(self) -> bool: ...
+    def clear(self) -> None: ...
+    @property
+    def artists(self) -> tuple[Artist]: ...
+    def set_props(self, **props) -> None: ...
+    def set_handle_props(self, **handle_props) -> None: ...
+    def add_state(self, state: str) -> None: ...
+    def remove_state(self, state: str) -> None: ...
+
+class SpanSelector(_SelectorWidget):
+    snap_values: ArrayLike | None
+    onmove_callback: Callable[[float, float], Any]
+    minspan: float
+    grab_range: float
+    drag_from_anywhere: bool
+    ignore_event_outside: bool
+    def __init__(
+        self,
+        ax: Axes,
+        onselect: Callable[[float, float], Any],
+        direction: Literal["horizontal", "vertical"],
+        *,
+        minspan: float = ...,
+        useblit: bool = ...,
+        props: dict[str, Any] | None = ...,
+        onmove_callback: Callable[[float, float], Any] | None = ...,
+        interactive: bool = ...,
+        button: MouseButton | Collection[MouseButton] | None = ...,
+        handle_props: dict[str, Any] | None = ...,
+        grab_range: float = ...,
+        state_modifier_keys: dict[str, str] | None = ...,
+        drag_from_anywhere: bool = ...,
+        ignore_event_outside: bool = ...,
+        snap_values: ArrayLike | None = ...,
+    ) -> None: ...
+    def new_axes(
+        self,
+        ax: Axes,
+        *,
+        _props: dict[str, Any] | None = ...,
+        _init: bool = ...,
+    ) -> None: ...
+    def connect_default_events(self) -> None: ...
+    @property
+    def direction(self) -> Literal["horizontal", "vertical"]: ...
+    @direction.setter
+    def direction(self, direction: Literal["horizontal", "vertical"]) -> None: ...
+    @property
+    def extents(self) -> tuple[float, float]: ...
+    @extents.setter
+    def extents(self, extents: tuple[float, float]) -> None: ...
+
+class ToolLineHandles:
+    ax: Axes
+    def __init__(
+        self,
+        ax: Axes,
+        positions: ArrayLike,
+        direction: Literal["horizontal", "vertical"],
+        *,
+        line_props: dict[str, Any] | None = ...,
+        useblit: bool = ...,
+    ) -> None: ...
+    @property
+    def artists(self) -> tuple[Line2D]: ...
+    @property
+    def positions(self) -> list[float]: ...
+    @property
+    def direction(self) -> Literal["horizontal", "vertical"]: ...
+    def set_data(self, positions: ArrayLike) -> None: ...
+    def set_visible(self, value: bool) -> None: ...
+    def set_animated(self, value: bool) -> None: ...
+    def remove(self) -> None: ...
+    def closest(self, x: float, y: float) -> tuple[int, float]: ...
+
+class ToolHandles:
+    ax: Axes
+    def __init__(
+        self,
+        ax: Axes,
+        x: ArrayLike,
+        y: ArrayLike,
+        *,
+        marker: str = ...,
+        marker_props: dict[str, Any] | None = ...,
+        useblit: bool = ...,
+    ) -> None: ...
+    @property
+    def x(self) -> ArrayLike: ...
+    @property
+    def y(self) -> ArrayLike: ...
+    @property
+    def artists(self) -> tuple[Line2D]: ...
+    def set_data(self, pts: ArrayLike, y: ArrayLike | None = ...) -> None: ...
+    def set_visible(self, val: bool) -> None: ...
+    def set_animated(self, val: bool) -> None: ...
+    def closest(self, x: float, y: float) -> tuple[int, float]: ...
+
+class RectangleSelector(_SelectorWidget):
+    drag_from_anywhere: bool
+    ignore_event_outside: bool
+    minspanx: float
+    minspany: float
+    spancoords: Literal["data", "pixels"]
+    grab_range: float
+    def __init__(
+        self,
+        ax: Axes,
+        onselect: Callable[[MouseEvent, MouseEvent], Any] | None = ...,
+        *,
+        minspanx: float = ...,
+        minspany: float = ...,
+        useblit: bool = ...,
+        props: dict[str, Any] | None = ...,
+        spancoords: Literal["data", "pixels"] = ...,
+        button: MouseButton | Collection[MouseButton] | None = ...,
+        grab_range: float = ...,
+        handle_props: dict[str, Any] | None = ...,
+        interactive: bool = ...,
+        state_modifier_keys: dict[str, str] | None = ...,
+        drag_from_anywhere: bool = ...,
+        ignore_event_outside: bool = ...,
+        use_data_coordinates: bool = ...,
+    ) -> None: ...
+    @property
+    def corners(self) -> tuple[np.ndarray, np.ndarray]: ...
+    @property
+    def edge_centers(self) -> tuple[np.ndarray, np.ndarray]: ...
+    @property
+    def center(self) -> tuple[float, float]: ...
+    @property
+    def extents(self) -> tuple[float, float, float, float]: ...
+    @extents.setter
+    def extents(self, extents: tuple[float, float, float, float]) -> None: ...
+    @property
+    def rotation(self) -> float: ...
+    @rotation.setter
+    def rotation(self, value: float) -> None: ...
+    @property
+    def geometry(self) -> np.ndarray: ...
+
+class EllipseSelector(RectangleSelector): ...
+
+class LassoSelector(_SelectorWidget):
+    verts: None | list[tuple[float, float]]
+    def __init__(
+        self,
+        ax: Axes,
+        onselect: Callable[[list[tuple[float, float]]], Any] | None = ...,
+        *,
+        useblit: bool = ...,
+        props: dict[str, Any] | None = ...,
+        button: MouseButton | Collection[MouseButton] | None = ...,
+    ) -> None: ...
+
+class PolygonSelector(_SelectorWidget):
+    grab_range: float
+    def __init__(
+        self,
+        ax: Axes,
+        onselect: Callable[[ArrayLike, ArrayLike], Any] | None = ...,
+        *,
+        useblit: bool = ...,
+        props: dict[str, Any] | None = ...,
+        handle_props: dict[str, Any] | None = ...,
+        grab_range: float = ...,
+        draw_bounding_box: bool = ...,
+        box_handle_props: dict[str, Any] | None = ...,
+        box_props: dict[str, Any] | None = ...
+    ) -> None: ...
+    def onmove(self, event: Event) -> bool: ...
+    @property
+    def verts(self) -> list[tuple[float, float]]: ...
+    @verts.setter
+    def verts(self, xys: Sequence[tuple[float, float]]) -> None: ...
+
+class Lasso(AxesWidget):
+    useblit: bool
+    background: Any
+    verts: list[tuple[float, float]] | None
+    line: Line2D
+    callback: Callable[[list[tuple[float, float]]], Any]
+    def __init__(
+        self,
+        ax: Axes,
+        xy: tuple[float, float],
+        callback: Callable[[list[tuple[float, float]]], Any],
+        *,
+        useblit: bool = ...,
+        props: dict[str, Any] | None = ...,
+    ) -> None: ...
+    def onrelease(self, event: Event) -> None: ...
+    def onmove(self, event: Event) -> None: ...
diff --git a/lib/python3.12/site-packages/sglang/srt/__pycache__/_custom_ops.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/__pycache__/_custom_ops.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..27e41c6f0ce8a1d950d530f6cbe883378c23dae0
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/__pycache__/_custom_ops.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/__pycache__/aio_rwlock.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/__pycache__/aio_rwlock.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..623b68e4e414979c48319c546f93b17d7bad2b36
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/__pycache__/aio_rwlock.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/__pycache__/hf_transformers_utils.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/__pycache__/hf_transformers_utils.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..661da81006bd9791ab20bb9ed2a535bfdae1037a
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/__pycache__/hf_transformers_utils.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/__pycache__/server_args.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/__pycache__/server_args.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..6055945dac59b5c19bc552751885428e2a5b2ade
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/__pycache__/server_args.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/__pycache__/torch_memory_saver_adapter.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/__pycache__/torch_memory_saver_adapter.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..c38418e33e60463c20e56064141e50f89a0588fc
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/__pycache__/torch_memory_saver_adapter.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/__init__.py b/lib/python3.12/site-packages/sglang/srt/distributed/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..12f802055c504552b3bfd540017c7874956b4078
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/__init__.py
@@ -0,0 +1,3 @@
+from sglang.srt.distributed.communication_op import *
+from sglang.srt.distributed.parallel_state import *
+from sglang.srt.distributed.utils import *
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/communication_op.py b/lib/python3.12/site-packages/sglang/srt/distributed/communication_op.py
new file mode 100644
index 0000000000000000000000000000000000000000..95600edfb410698770c682b6109df329dfa2f574
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/communication_op.py
@@ -0,0 +1,35 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/communication_op.py
+
+from typing import Any, Dict, Optional, Union
+
+import torch
+import torch.distributed
+
+from .parallel_state import get_tp_group
+
+
+def tensor_model_parallel_all_reduce(input_: torch.Tensor) -> torch.Tensor:
+    """All-reduce the input tensor across model parallel group."""
+    return get_tp_group().all_reduce(input_)
+
+
+def tensor_model_parallel_all_gather(
+    input_: torch.Tensor, dim: int = -1
+) -> torch.Tensor:
+    """All-gather the input tensor across model parallel group."""
+    return get_tp_group().all_gather(input_, dim)
+
+
+def tensor_model_parallel_gather(
+    input_: torch.Tensor, dst: int = 0, dim: int = -1
+) -> Optional[torch.Tensor]:
+    """Gather the input tensor across model parallel group."""
+    return get_tp_group().gather(input_, dst, dim)
+
+
+def broadcast_tensor_dict(
+    tensor_dict: Optional[Dict[Any, Union[torch.Tensor, Any]]] = None, src: int = 0
+):
+    if not torch.distributed.is_initialized():
+        return tensor_dict
+    return get_tp_group().broadcast_tensor_dict(tensor_dict, src)
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/cuda_wrapper.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/cuda_wrapper.py
new file mode 100644
index 0000000000000000000000000000000000000000..c902f314112e40d301f69eef9f21b62057db8160
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/cuda_wrapper.py
@@ -0,0 +1,183 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/cuda_wrapper.py
+
+"""This file is a pure Python wrapper for the cudart library.
+It avoids the need to compile a separate shared library, and is
+convenient for use when we just need to call a few functions.
+"""
+
+import ctypes
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+# this line makes it possible to directly load `libcudart.so` using `ctypes`
+import torch  # noqa
+
+logger = logging.getLogger(__name__)
+
+# === export types and functions from cudart to Python ===
+# for the original cudart definition, please check
+# https://docs.nvidia.com/cuda/cuda-runtime-api/index.html
+
+cudaError_t = ctypes.c_int
+cudaMemcpyKind = ctypes.c_int
+
+
+class cudaIpcMemHandle_t(ctypes.Structure):
+    _fields_ = [("internal", ctypes.c_byte * 128)]
+
+
+@dataclass
+class Function:
+    name: str
+    restype: Any
+    argtypes: List[Any]
+
+
+def find_loaded_library(lib_name) -> Optional[str]:
+    """
+    According to according to https://man7.org/linux/man-pages/man5/proc_pid_maps.5.html,
+    the file `/proc/self/maps` contains the memory maps of the process, which includes the
+    shared libraries loaded by the process. We can use this file to find the path of the
+    a loaded library.
+    """  # noqa
+    found = False
+    with open("/proc/self/maps") as f:
+        for line in f:
+            if lib_name in line:
+                found = True
+                break
+    if not found:
+        # the library is not loaded in the current process
+        return None
+    # if lib_name is libcudart, we need to match a line with:
+    # address /path/to/libcudart-hash.so.11.0
+    start = line.index("/")
+    path = line[start:].strip()
+    filename = path.split("/")[-1]
+    assert filename.rpartition(".so")[0].startswith(
+        lib_name
+    ), f"Unexpected filename: {filename} for library {lib_name}"
+    return path
+
+
+class CudaRTLibrary:
+    exported_functions = [
+        # ​cudaError_t cudaSetDevice ( int  device )
+        Function("cudaSetDevice", cudaError_t, [ctypes.c_int]),
+        # cudaError_t 	cudaDeviceSynchronize ( void )
+        Function("cudaDeviceSynchronize", cudaError_t, []),
+        # ​cudaError_t cudaDeviceReset ( void )
+        Function("cudaDeviceReset", cudaError_t, []),
+        # const char* 	cudaGetErrorString ( cudaError_t error )
+        Function("cudaGetErrorString", ctypes.c_char_p, [cudaError_t]),
+        # ​cudaError_t 	cudaMalloc ( void** devPtr, size_t size )
+        Function(
+            "cudaMalloc",
+            cudaError_t,
+            [ctypes.POINTER(ctypes.c_void_p), ctypes.c_size_t],
+        ),
+        # ​cudaError_t 	cudaFree ( void* devPtr )
+        Function("cudaFree", cudaError_t, [ctypes.c_void_p]),
+        # ​cudaError_t cudaMemset ( void* devPtr, int  value, size_t count )
+        Function(
+            "cudaMemset", cudaError_t, [ctypes.c_void_p, ctypes.c_int, ctypes.c_size_t]
+        ),
+        # ​cudaError_t cudaMemcpy ( void* dst, const void* src, size_t count, cudaMemcpyKind kind ) # noqa
+        Function(
+            "cudaMemcpy",
+            cudaError_t,
+            [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_size_t, cudaMemcpyKind],
+        ),
+        # cudaError_t cudaIpcGetMemHandle ( cudaIpcMemHandle_t* handle, void* devPtr ) # noqa
+        Function(
+            "cudaIpcGetMemHandle",
+            cudaError_t,
+            [ctypes.POINTER(cudaIpcMemHandle_t), ctypes.c_void_p],
+        ),
+        # ​cudaError_t cudaIpcOpenMemHandle ( void** devPtr, cudaIpcMemHandle_t handle, unsigned int  flags ) # noqa
+        Function(
+            "cudaIpcOpenMemHandle",
+            cudaError_t,
+            [ctypes.POINTER(ctypes.c_void_p), cudaIpcMemHandle_t, ctypes.c_uint],
+        ),
+    ]
+
+    # class attribute to store the mapping from the path to the library
+    # to avoid loading the same library multiple times
+    path_to_library_cache: Dict[str, Any] = {}
+
+    # class attribute to store the mapping from library path
+    #  to the corresponding dictionary
+    path_to_dict_mapping: Dict[str, Dict[str, Any]] = {}
+
+    def __init__(self, so_file: Optional[str] = None):
+        if so_file is None:
+            so_file = find_loaded_library("libcudart")
+            assert so_file is not None, "libcudart is not loaded in the current process"
+        if so_file not in CudaRTLibrary.path_to_library_cache:
+            lib = ctypes.CDLL(so_file)
+            CudaRTLibrary.path_to_library_cache[so_file] = lib
+        self.lib = CudaRTLibrary.path_to_library_cache[so_file]
+
+        if so_file not in CudaRTLibrary.path_to_dict_mapping:
+            _funcs = {}
+            for func in CudaRTLibrary.exported_functions:
+                f = getattr(self.lib, func.name)
+                f.restype = func.restype
+                f.argtypes = func.argtypes
+                _funcs[func.name] = f
+            CudaRTLibrary.path_to_dict_mapping[so_file] = _funcs
+        self.funcs = CudaRTLibrary.path_to_dict_mapping[so_file]
+
+    def CUDART_CHECK(self, result: cudaError_t) -> None:
+        if result != 0:
+            error_str = self.cudaGetErrorString(result)
+            raise RuntimeError(f"CUDART error: {error_str}")
+
+    def cudaGetErrorString(self, error: cudaError_t) -> str:
+        return self.funcs["cudaGetErrorString"](error).decode("utf-8")
+
+    def cudaSetDevice(self, device: int) -> None:
+        self.CUDART_CHECK(self.funcs["cudaSetDevice"](device))
+
+    def cudaDeviceSynchronize(self) -> None:
+        self.CUDART_CHECK(self.funcs["cudaDeviceSynchronize"]())
+
+    def cudaDeviceReset(self) -> None:
+        self.CUDART_CHECK(self.funcs["cudaDeviceReset"]())
+
+    def cudaMalloc(self, size: int) -> ctypes.c_void_p:
+        devPtr = ctypes.c_void_p()
+        self.CUDART_CHECK(self.funcs["cudaMalloc"](ctypes.byref(devPtr), size))
+        return devPtr
+
+    def cudaFree(self, devPtr: ctypes.c_void_p) -> None:
+        self.CUDART_CHECK(self.funcs["cudaFree"](devPtr))
+
+    def cudaMemset(self, devPtr: ctypes.c_void_p, value: int, count: int) -> None:
+        self.CUDART_CHECK(self.funcs["cudaMemset"](devPtr, value, count))
+
+    def cudaMemcpy(
+        self, dst: ctypes.c_void_p, src: ctypes.c_void_p, count: int
+    ) -> None:
+        cudaMemcpyDefault = 4
+        kind = cudaMemcpyDefault
+        self.CUDART_CHECK(self.funcs["cudaMemcpy"](dst, src, count, kind))
+
+    def cudaIpcGetMemHandle(self, devPtr: ctypes.c_void_p) -> cudaIpcMemHandle_t:
+        handle = cudaIpcMemHandle_t()
+        self.CUDART_CHECK(
+            self.funcs["cudaIpcGetMemHandle"](ctypes.byref(handle), devPtr)
+        )
+        return handle
+
+    def cudaIpcOpenMemHandle(self, handle: cudaIpcMemHandle_t) -> ctypes.c_void_p:
+        cudaIpcMemLazyEnablePeerAccess = 1
+        devPtr = ctypes.c_void_p()
+        self.CUDART_CHECK(
+            self.funcs["cudaIpcOpenMemHandle"](
+                ctypes.byref(devPtr), handle, cudaIpcMemLazyEnablePeerAccess
+            )
+        )
+        return devPtr
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce.py
new file mode 100644
index 0000000000000000000000000000000000000000..51bcd47227095a5f1d55997dc4f50ae933ffb6b6
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce.py
@@ -0,0 +1,516 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/custom_all_reduce.py
+
+import ctypes
+import logging
+import os
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any, Callable, List, Optional, TypeVar, Union
+
+import torch
+import torch.distributed as dist
+from torch.distributed import ProcessGroup
+from typing_extensions import ParamSpec
+
+from sglang.srt import _custom_ops as ops
+from sglang.srt.distributed.device_communicators.cuda_wrapper import CudaRTLibrary
+from sglang.srt.distributed.device_communicators.custom_all_reduce_utils import (
+    gpu_p2p_access_check,
+)
+from sglang.srt.distributed.parallel_state import in_the_same_node_as
+from sglang.srt.utils import is_cuda, is_hip
+
+logger = logging.getLogger(__name__)
+
+_is_cuda = is_cuda()
+_is_hip = is_hip()
+
+if _is_cuda:
+    try:
+        import pynvml
+    except ImportError as e:
+        logger.warning("Failed to import pynvml with %r", e)
+
+if _is_hip:
+    try:
+        from amdsmi import (
+            AmdSmiException,
+            amdsmi_get_processor_handles,
+            amdsmi_init,
+            amdsmi_shut_down,
+            amdsmi_topo_get_link_type,
+        )
+    except ImportError as e:
+        logger.warning("Failed to import amdsmi with %r", e)
+
+try:
+    if ops.use_vllm_custom_allreduce and not _is_hip:
+        # Use vLLM custom allreduce
+        ops.meta_size()
+    else:
+        # Use custom allreduce from sgl kernel (ROCM and TRT-LLM)
+        import sgl_kernel
+    custom_ar = True
+except Exception:
+    # For CPUs
+    custom_ar = False
+
+logger = logging.getLogger(__name__)
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def with_nvml_context(fn: Callable[_P, _R]) -> Callable[_P, _R]:
+    @wraps(fn)
+    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        if _is_hip:
+            try:
+                amdsmi_init()
+                return fn(*args, **kwargs)
+            finally:
+                amdsmi_shut_down()
+        else:
+            pynvml.nvmlInit()
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                pynvml.nvmlShutdown()
+
+    return wrapper
+
+
+@with_nvml_context
+def is_full_nvlink(physical_device_ids: List[int], world_size: int) -> bool:
+    if _is_hip:
+        """
+        query if the set of gpus are fully connected by xgmi (1 hop)
+        """
+        handles = [amdsmi_get_processor_handles()[i] for i in physical_device_ids]
+        for i, handle in enumerate(handles):
+            for j, peer_handle in enumerate(handles):
+                if i < j:
+                    try:
+                        link_type = amdsmi_topo_get_link_type(handle, peer_handle)
+                        # type is 2 for XGMI
+                        if link_type["hops"] != 1 or link_type["type"] != 2:
+                            return False
+                    except AmdSmiException as error:
+                        logger.error("AMD 1 hop XGMI detection failed.", exc_info=error)
+                        return False
+        return True
+    else:
+        """
+        query if the set of gpus are fully connected by nvlink (1 hop)
+        """
+        handles = [pynvml.nvmlDeviceGetHandleByIndex(i) for i in physical_device_ids]
+        for i, handle in enumerate(handles):
+            for j, peer_handle in enumerate(handles):
+                if i < j:
+                    try:
+                        p2p_status = pynvml.nvmlDeviceGetP2PStatus(
+                            handle, peer_handle, pynvml.NVML_P2P_CAPS_INDEX_NVLINK
+                        )
+                        if p2p_status != pynvml.NVML_P2P_STATUS_OK:
+                            return False
+                    except pynvml.NVMLError:
+                        logger.exception(
+                            "NVLink detection failed. This is normal if your"
+                            " machine has no NVLink equipped."
+                        )
+                        return False
+        return True
+
+
+def _can_p2p(rank: int, world_size: int) -> bool:
+    # SGLANG_SKIP_P2P_CHECK can be set to False in sglang
+    SGLANG_SKIP_P2P_CHECK = os.getenv("SGLANG_SKIP_P2P_CHECK", "0") == "1"
+    for i in range(world_size):
+        if i == rank:
+            continue
+        if SGLANG_SKIP_P2P_CHECK:
+            logger.info("Skipping P2P check and trusting the driver's P2P report.")
+            return torch.cuda.can_device_access_peer(rank, i)
+        if not gpu_p2p_access_check(rank, i):
+            return False
+    return True
+
+
+def is_weak_contiguous(inp: torch.Tensor):
+    return inp.is_contiguous() or (
+        inp.storage().nbytes() - inp.storage_offset() * inp.element_size()
+        == inp.numel() * inp.element_size()
+    )
+
+
+class CustomAllreduce:
+    _SUPPORTED_WORLD_SIZES = [2, 4, 6, 8]
+    _MAX_CAR_SIZE = 8192 * 1024
+    if _is_hip:
+        # crossover is at 16MB buffer size for ROCm
+        _MAX_CAR_SIZE = 2 * 8192 * 1024
+
+    # max_size: max supported allreduce size
+    def __init__(
+        self,
+        group: ProcessGroup,
+        device: Union[int, str, torch.device],
+        max_size=_MAX_CAR_SIZE,
+    ) -> None:
+        """
+        Args:
+            group: the process group to work on. If None, it will use the
+                default process group.
+            device: the device to bind the CustomAllreduce to. If None,
+                it will be bind to f"cuda:{local_rank}".
+        It is the caller's responsibility to make sure each communicator
+        is bind to a unique device, and all communicators in this group
+        are in the same node.
+        """
+        self._IS_CAPTURING = False
+        self.disabled = True
+
+        if not custom_ar:
+            # disable because of missing custom allreduce library
+            # e.g. in a non-cuda environment
+            return
+
+        self.group = group
+
+        assert (
+            dist.get_backend(group) != dist.Backend.NCCL
+        ), "CustomAllreduce should be attached to a non-NCCL group."
+
+        if not all(in_the_same_node_as(group, source_rank=0)):
+            # No need to initialize custom allreduce for multi-node case.
+            logger.warning(
+                "Custom allreduce is disabled because this process group"
+                " spans across nodes."
+            )
+            return
+
+        rank = dist.get_rank(group=self.group)
+        world_size = dist.get_world_size(group=self.group)
+        if world_size == 1:
+            # No need to initialize custom allreduce for single GPU case.
+            return
+
+        if world_size not in CustomAllreduce._SUPPORTED_WORLD_SIZES:
+            logger.warning(
+                "Custom allreduce is disabled due to an unsupported world"
+                " size: %d. Supported world sizes: %s. To silence this "
+                "warning, specify disable_custom_all_reduce=True explicitly.",
+                world_size,
+                str(CustomAllreduce._SUPPORTED_WORLD_SIZES),
+            )
+            return
+
+        if isinstance(device, int):
+            device = torch.device(f"cuda:{device}")
+        elif isinstance(device, str):
+            device = torch.device(device)
+        # now `device` is a `torch.device` object
+        assert isinstance(device, torch.device)
+        self.device = device
+
+        cuda_visible_devices = os.environ.get("CUDA_VISIBLE_DEVICES", None)
+        if cuda_visible_devices:
+            device_ids = list(map(int, cuda_visible_devices.split(",")))
+        else:
+            device_ids = list(range(torch.cuda.device_count()))
+
+        physical_device_id = device_ids[device.index]
+        tensor = torch.tensor([physical_device_id], dtype=torch.int, device="cpu")
+        gather_list = [
+            torch.tensor([0], dtype=torch.int, device="cpu") for _ in range(world_size)
+        ]
+        dist.all_gather(gather_list, tensor, group=self.group)
+        physical_device_ids = [t.item() for t in gather_list]
+
+        # test nvlink first, this will filter out most of the cases
+        # where custom allreduce is not supported
+        # this checks hardware and driver support for NVLink
+        if _is_cuda or _is_hip:
+            full_nvlink = is_full_nvlink(physical_device_ids, world_size)
+
+        if world_size > 2 and not full_nvlink:
+            logger.warning(
+                "Custom allreduce is disabled because it's not supported on"
+                " more than two PCIe-only GPUs. To silence this warning, "
+                "specify disable_custom_all_reduce=True explicitly."
+            )
+            return
+        # test P2P capability, this checks software/cudaruntime support
+        # this is expensive to compute at the first time
+        # then we cache the result
+        # On AMD GPU, p2p is always enabled between XGMI connected GPUs
+        if not _is_hip and not _can_p2p(rank, world_size):
+            logger.warning(
+                "Custom allreduce is disabled because your platform lacks "
+                "GPU P2P capability or P2P test failed. To silence this "
+                "warning, specify disable_custom_all_reduce=True explicitly."
+            )
+            return
+
+        self.max_size = max_size
+        self.rank = rank
+        self.world_size = world_size
+        self.full_nvlink = full_nvlink
+
+        if not _is_hip:
+            # Buffers memory are owned by this Python class and passed to C++.
+            # Meta data composes of two parts: meta data for synchronization and a
+            # temporary buffer for storing intermediate allreduce results.
+            self.meta_ptrs = self.create_shared_buffer(
+                ops.meta_size() + max_size, group=group
+            )
+            # This is a pre-registered IPC buffer. In eager mode, input tensors
+            # are first copied into this buffer before allreduce is performed
+            self.buffer_ptrs = self.create_shared_buffer(max_size, group=group)
+            # This is a buffer for storing the tuples of pointers pointing to
+            # IPC buffers from all ranks. Each registered tuple has size of
+            # 8*world_size bytes where world_size is at most 8. Allocating 8MB
+            # is enough for 131072 such tuples. The largest model I've seen only
+            # needs less than 10000 of registered tuples.
+            self.rank_data = torch.empty(
+                8 * 1024 * 1024, dtype=torch.uint8, device=self.device
+            )
+            self._ptr = ops.init_custom_ar(
+                self.meta_ptrs, self.rank_data, rank, self.full_nvlink
+            )
+            ops.register_buffer(self._ptr, self.buffer_ptrs)
+        else:
+            # meta data buffers need to be "uncached" for signal on MI200
+            self.meta = ops.allocate_meta_buffer(ops.meta_size() + max_size)
+            self.buffer = torch.empty(max_size, dtype=torch.uint8, device=self.device)
+            handle = ops.get_meta_buffer_ipc_handle(self.meta)
+            shard_data = (
+                bytes(handle),  # ipc handle to base ptr
+                0,  # offset of base ptr
+            )
+            handles, offsets = self._gather_ipc_meta(shard_data)
+            self.rank_data = torch.empty(
+                8 * 1024 * 1024, dtype=torch.uint8, device=self.device
+            )
+            self._ptr = ops.init_custom_ar(
+                self.meta, self.rank_data, handles, offsets, rank, self.full_nvlink
+            )
+            self.register_buffer(self.buffer)
+            self.MSCCL = os.getenv("RCCL_MSCCL_ENABLE", "1") == "1"
+
+        self.disabled = False
+
+    @staticmethod
+    def create_shared_buffer(
+        size_in_bytes: int, group: Optional[ProcessGroup] = None
+    ) -> List[int]:
+        """
+        Creates a shared buffer and returns a list of pointers
+        representing the buffer on all processes in the group.
+        """
+        lib = CudaRTLibrary()
+        pointer = lib.cudaMalloc(size_in_bytes)
+        handle = lib.cudaIpcGetMemHandle(pointer)
+        world_size = dist.get_world_size(group=group)
+        rank = dist.get_rank(group=group)
+        handles = [None] * world_size
+        dist.all_gather_object(handles, handle, group=group)
+
+        pointers: List[int] = []
+        for i, h in enumerate(handles):
+            if i == rank:
+                pointers.append(pointer.value)  # type: ignore
+            else:
+                pointers.append(lib.cudaIpcOpenMemHandle(h).value)  # type: ignore
+
+        return pointers
+
+    @staticmethod
+    def free_shared_buffer(
+        pointers: List[int], group: Optional[ProcessGroup] = None
+    ) -> None:
+        rank = dist.get_rank(group=group)
+        lib = CudaRTLibrary()
+        lib.cudaFree(ctypes.c_void_p(pointers[rank]))
+
+    @contextmanager
+    def capture(self):
+        """
+        The main responsibility of this context manager is the
+        `register_graph_buffers` call at the end of the context.
+        It records all the buffer addresses used in the CUDA graph.
+        """
+        try:
+            self._IS_CAPTURING = True
+            yield
+        finally:
+            self._IS_CAPTURING = False
+            if not self.disabled:
+                self.register_graph_buffers()
+
+    def _get_ipc_meta(self, inp: torch.Tensor):
+        # _share_cuda_() doesn't accept meta buffer not allocated from
+        # PyTorch cache allocator, use direct HIP call to get IPC handle
+        handle = ops.get_meta_buffer_ipc_handle(inp)
+        shard_data = (
+            bytes(handle),  # ipc handle to base ptr
+            0,  # offset of base ptr
+        )
+        return self._gather_ipc_meta(shard_data)
+
+    def _gather_ipc_meta(self, shard_data):
+        # Note: don't use `[[None]] * self.world_size` here
+        # because it will create a list of the same reference
+        all_data: List[Optional[Any]] = [[None] for i in range(self.world_size)]
+        all_data[self.rank][0] = shard_data
+
+        ranks = dist.get_process_group_ranks(group=self.group)
+        ranks.sort()
+        for i, rank in enumerate(ranks):
+            dist.broadcast_object_list(
+                all_data[i], src=rank, group=self.group, device="cpu"
+            )
+
+        # we cannot directly use `dist.all_gather_object` here
+        # because it is incompatible with `gloo` backend under inference mode.
+        # see https://github.com/pytorch/pytorch/issues/126032 for details.
+
+        handles = []
+        offsets = []
+        for i in range(len(all_data)):
+            handles.append(all_data[i][0][0])  # type: ignore
+            offsets.append(all_data[i][0][1])  # type: ignore
+        return handles, offsets
+
+    def register_buffer(self, inp: torch.Tensor):
+        handles, offsets = self._get_ipc_meta(inp)
+        ops.register_buffer(self._ptr, inp, handles, offsets)
+
+    def register_graph_buffers(self):
+        if _is_hip:
+            handle, offset = ops.get_graph_buffer_ipc_meta(self._ptr)
+            handles, offsets = self._gather_ipc_meta((bytes(handle), offset))
+            logger.info("Registering %d cuda graph addresses", len(offset))
+            ops.register_graph_buffers(self._ptr, handles, offsets)
+        else:
+            handle, offset = ops.get_graph_buffer_ipc_meta(self._ptr)
+            logger.info("Registering %d cuda graph addresses", len(offset))
+            # We cannot directly use `dist.all_gather_object` here
+            # because it is incompatible with `gloo` backend under inference mode.
+            # see https://github.com/pytorch/pytorch/issues/126032 for details.
+            all_data = [
+                [None, None] for _ in range(dist.get_world_size(group=self.group))
+            ]
+            all_data[self.rank] = [handle, offset]
+            ranks = sorted(dist.get_process_group_ranks(group=self.group))
+            for i, rank in enumerate(ranks):
+                dist.broadcast_object_list(
+                    all_data[i], src=rank, group=self.group, device="cpu"
+                )
+            # Unpack list of tuples to tuple of lists.
+            handles = [d[0] for d in all_data]  # type: ignore
+            offsets = [d[1] for d in all_data]  # type: ignore
+            ops.register_graph_buffers(self._ptr, handles, offsets)
+
+    def should_custom_ar(self, inp: torch.Tensor):
+        if self.disabled:
+            return False
+        inp_size = inp.numel() * inp.element_size()
+        # custom allreduce requires input byte size to be multiples of 16
+        if inp_size % 16 != 0:
+            return False
+        if not is_weak_contiguous(inp):
+            return False
+        # for 4 or more non NVLink-capable GPUs, custom allreduce provides
+        # little performance improvement over NCCL.
+        if not _is_hip:
+            if self.world_size == 2 or self.full_nvlink:
+                return inp_size < self.max_size
+            return False
+
+        if _is_hip:
+            if self.full_nvlink:
+                if self.world_size == 8:
+                    if self.MSCCL:
+                        return False
+                    else:
+                        return inp_size < self.max_size
+                else:
+                    return inp_size < self.max_size
+            return False
+
+        return False
+
+    # all reduce, assuming inp tensor is IPC registered with register_buffer,
+    # or, in the context of cuda graphs, register_graph_buffers
+    def all_reduce_reg(self, inp: torch.Tensor, out: torch.Tensor = None):
+        if out is None:
+            out = torch.empty_like(inp)
+        ops.all_reduce_reg(self._ptr, inp, out)
+        return out
+
+    # all reduce, assuming inp tensor is NOT IPC registered
+    def all_reduce_unreg(self, inp: torch.Tensor, out: torch.Tensor = None):
+        if out is None:
+            out = torch.empty_like(inp)
+        ops.all_reduce_unreg(self._ptr, inp, self.buffer, out)
+        return out
+
+    def all_reduce(
+        self,
+        inp: torch.Tensor,
+        *,
+        out: torch.Tensor = None,
+        registered: bool = False,
+    ):
+        """Performs an out-of-place all reduce.
+
+        If registered is True, this assumes inp's pointer is already
+        IPC-registered. Otherwise, inp is first copied into a pre-registered
+        buffer.
+        """
+        if out is None:
+            out = torch.empty_like(inp)
+        if registered:
+            ops.all_reduce(self._ptr, inp, out, 0, 0)
+        else:
+            ops.all_reduce(
+                self._ptr, inp, out, self.buffer_ptrs[self.rank], self.max_size
+            )
+        return out
+
+    def custom_all_reduce(self, input: torch.Tensor) -> Optional[torch.Tensor]:
+        """The main allreduce API that provides support for cuda graph."""
+        # When custom allreduce is disabled, this will be None.
+        if self.disabled or not self.should_custom_ar(input):
+            return None
+        if self._IS_CAPTURING:
+            if torch.cuda.is_current_stream_capturing():
+                if _is_hip:
+                    return self.all_reduce_reg(input)
+                else:
+                    return self.all_reduce(input, registered=True)
+            else:
+                # If warm up, mimic the allocation pattern since custom
+                # allreduce is out-of-place.
+                return torch.empty_like(input)
+        else:
+            if _is_hip:
+                # note: outside of cuda graph context,
+                # custom allreduce incurs a cost of cudaMemcpy, which should
+                # be small(<=1% of overall latency) compared to the performance
+                # gains of using custom kernels
+                return self.all_reduce_unreg(input)
+            else:
+                return self.all_reduce(input, registered=False)
+
+    def close(self):
+        if not self.disabled and self._ptr:
+            ops.dispose(self._ptr)
+            if _is_cuda:
+                self.free_shared_buffer(self.meta_ptrs)
+                self.free_shared_buffer(self.buffer_ptrs)
+            self._ptr = 0
+
+    def __del__(self):
+        self.close()
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce_utils.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..86121ac976eef783e1410b7e177ad09d276b4b6b
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/custom_all_reduce_utils.py
@@ -0,0 +1,291 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/custom_all_reduce_utils.py
+
+import ctypes
+import json
+import logging
+import os
+import pickle
+import subprocess
+import sys
+import tempfile
+from itertools import product
+from typing import Dict, List, Optional, Sequence
+
+import torch
+import torch.distributed as dist
+import torch.multiprocessing as mp
+
+from sglang.srt.distributed.device_communicators.cuda_wrapper import CudaRTLibrary
+
+logger = logging.getLogger(__name__)
+
+
+def update_environment_variables(envs: Dict[str, str]):
+    for k, v in envs.items():
+        if k in os.environ and os.environ[k] != v:
+            logger.warning(
+                "Overwriting environment variable %s " "from '%s' to '%s'",
+                k,
+                os.environ[k],
+                v,
+            )
+        os.environ[k] = v
+
+
+def producer(
+    batch_src: Sequence[int],
+    producer_queue,
+    consumer_queue,
+    result_queue,
+    cuda_visible_devices: Optional[str] = None,
+):
+    if cuda_visible_devices is not None:
+        update_environment_variables({"CUDA_VISIBLE_DEVICES": cuda_visible_devices})
+
+    lib = CudaRTLibrary()
+    for i in batch_src:
+        lib.cudaSetDevice(i)
+        pointer = lib.cudaMalloc(1024)
+        lib.cudaMemset(pointer, 1, 1024)
+        lib.cudaDeviceSynchronize()
+        handle = lib.cudaIpcGetMemHandle(pointer)
+        producer_queue.put(handle)
+        open_success = consumer_queue.get()
+        if open_success:
+            # use two queues to simulate barrier
+            producer_queue.put(0)
+            consumer_queue.get()
+            # check if the memory is modified
+            host_data = (ctypes.c_char * 1024)()
+            lib.cudaMemcpy(host_data, pointer, 1024)  # type: ignore
+            for i in range(1024):
+                if ord(host_data[i]) != 2:
+                    open_success = False
+                    break
+        result_queue.put(open_success)
+        lib.cudaDeviceReset()
+
+
+def consumer(
+    batch_tgt: Sequence[int],
+    producer_queue,
+    consumer_queue,
+    result_queue,
+    cuda_visible_devices: Optional[str] = None,
+):
+    if cuda_visible_devices is not None:
+        update_environment_variables({"CUDA_VISIBLE_DEVICES": cuda_visible_devices})
+
+    lib = CudaRTLibrary()
+    for j in batch_tgt:
+        lib.cudaSetDevice(j)
+        handle = producer_queue.get()
+        open_success = False
+        try:
+            pointer = lib.cudaIpcOpenMemHandle(handle)  # type: ignore
+            open_success = True
+        except RuntimeError:
+            # cannot error out here, because the producer process
+            # is still waiting for the response.
+            pass
+        consumer_queue.put(open_success)
+        if open_success:
+            # modify the memory
+            lib.cudaMemset(pointer, 2, 1024)
+            lib.cudaDeviceSynchronize()
+            # use two queues to simulate barrier
+            producer_queue.get()
+            consumer_queue.put(0)
+            # check if the memory is modified
+            host_data = (ctypes.c_char * 1024)()
+            lib.cudaMemcpy(host_data, pointer, 1024)  # type: ignore
+            for i in range(1024):
+                if ord(host_data[i]) != 2:
+                    open_success = False
+                    break
+        result_queue.put(open_success)
+        lib.cudaDeviceReset()
+
+
+def can_actually_p2p(
+    batch_src: Sequence[int],
+    batch_tgt: Sequence[int],
+) -> Sequence[bool]:
+    """
+    Usually, checking if P2P access is enabled can be done by
+    `torch.cuda.can_device_access_peer(src, tgt)`. However, sometimes
+    the driver might be broken, and `torch.cuda.can_device_access_peer(src, tgt)`
+    returns `True` even if P2P access is not actually possible.
+    See https://github.com/vllm-project/vllm/issues/2728 and
+    https://forums.developer.nvidia.com/t/direct-gpu-gpu-communication-does-not-seem-to-work-properly/283264/10
+    Therefore, we have to perform a real P2P access to check if it is actually
+    possible.
+
+    Note on p2p and cuda IPC:
+    Usually, one process uses one GPU:
+    GPU src --> cuda context src --> tensor src --> process src
+
+    We need to combine p2p and cuda IPC, so that:
+    GPU src --> cuda context src --> tensor src --> process src
+                                      |shared|
+    GPU tgt --> cuda context tgt --> tensor tgt --> process tgt
+    That is to say, process src creates a tensor in GPU src, passes IPC handle to
+    process tgt, and process tgt accesses the tensor in GPU tgt. Any operation on the
+    tensor in process tgt will be reflected in the tensor in process src, because
+    they are the same memory segment.
+    It is important to note that process tgt accesses the tensor in GPU tgt, not
+    GPU src. That's why we need p2p access.
+
+    The most time-consuming part is the process creation. To avoid creating
+    processes for every pair of GPUs, we use batched testing. We create two
+    processes for testing all pairs of GPUs in batch. The trick is to reset
+    the device after each test (which is not available in PyTorch).
+    """  # noqa
+    cuda_visible_devices = os.environ.get("CUDA_VISIBLE_DEVICES", None)
+    # pass the CUDA_VISIBLE_DEVICES to the child process
+    # to make sure they see the same set of GPUs
+
+    # make sure the processes are spawned
+    smp = mp.get_context("spawn")
+    producer_queue = smp.Queue()
+    consumer_queue = smp.Queue()
+    result_queue = smp.Queue()
+    p_src = smp.Process(
+        target=producer,
+        args=(
+            batch_src,
+            producer_queue,
+            consumer_queue,
+            result_queue,
+            cuda_visible_devices,
+        ),
+    )
+    p_tgt = smp.Process(
+        target=consumer,
+        args=(
+            batch_tgt,
+            producer_queue,
+            consumer_queue,
+            result_queue,
+            cuda_visible_devices,
+        ),
+    )
+    p_src.start()
+    p_tgt.start()
+    p_src.join()
+    p_tgt.join()
+    assert p_src.exitcode == 0 and p_tgt.exitcode == 0
+    result: List[bool] = []
+    for src, tgt in zip(batch_src, batch_tgt):
+        a = result_queue.get()
+        b = result_queue.get()
+        if a != b:
+            logger.warning(
+                "Two processes do not agree on the P2P access"
+                " status on %d -> %d, treat as disabled.",
+                src,
+                tgt,
+            )
+            result.append(False)
+        else:
+            result.append(a)
+    return result
+
+
+# why do we need this cache?
+# we are testing peer-to-peer (p2p) access between GPUs,across processes.
+# if we test it every time, it will be very slow, because we need to create
+#  N * N * 2 processes, where N is the world size. This is very slow.
+# to reduce the time, we use a cache file to store the p2p access status.
+# the cache file is generated by the master process if it does not exist.
+# then all the processes can read the cache file to check the p2p access status.
+# Note that the cache file is suffixed by the CUDA_VISIBLE_DEVICES, so that we
+#  can have different cache files for different CUDA_VISIBLE_DEVICES settings,
+#  e.g. used by different vllm engines. The device id in the cache file is a
+#  **local** device id, i.e. from 0 to num_dev-1, where num_dev is the number
+#  of visible devices in the vllm engine.
+_gpu_p2p_access_cache: Optional[Dict[str, bool]] = None
+
+
+def gpu_p2p_access_check(src: int, tgt: int) -> bool:
+    """Check if GPU src can access GPU tgt."""
+
+    # if the cache variable is already calculated,
+    # read from the cache instead of checking it again
+    global _gpu_p2p_access_cache
+    if _gpu_p2p_access_cache is not None:
+        return _gpu_p2p_access_cache[f"{src}->{tgt}"]
+
+    is_distributed = dist.is_initialized()
+
+    num_dev = torch.cuda.device_count()
+    cuda_visible_devices = os.environ.get("CUDA_VISIBLE_DEVICES", None)
+    if cuda_visible_devices is None:
+        cuda_visible_devices = ",".join(str(i) for i in range(num_dev))
+
+    # VLLM_CACHE_ROOT -> SGLANG_CACHE_ROOT
+    # "~/.cache/vllm" -> "~/.cache/sglang"
+    SGLANG_CACHE_ROOT = os.path.expanduser("~/.cache/sglang")
+    path = os.path.join(
+        SGLANG_CACHE_ROOT, f"gpu_p2p_access_cache_for_{cuda_visible_devices}.json"
+    )
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    from sglang.srt.distributed.parallel_state import get_world_group
+
+    if (not is_distributed or get_world_group().local_rank == 0) and (
+        not os.path.exists(path)
+    ):
+        # only the local master process (with local_rank == 0) can
+        #  enter this block to calculate the cache
+        logger.info("generating GPU P2P access cache in %s", path)
+        cache: Dict[str, bool] = {}
+        ids = list(range(num_dev))
+        # batch of all pairs of GPUs
+        batch_src, batch_tgt = zip(*list(product(ids, ids)))
+        # NOTE: we use `subprocess` rather than `multiprocessing` here
+        # because the caller might not have `if __name__ == "__main__":`,
+        # in that case we cannot use spawn method in multiprocessing.
+        # However, `can_actually_p2p` requires spawn method.
+        # The fix is, we use `subprocess` to call the function,
+        # where we have `if __name__ == "__main__":` in this file.
+
+        # use a temporary file to store the result
+        # we don't use the output of the subprocess directly,
+        # because the subprocess might produce logging output
+        with tempfile.NamedTemporaryFile() as output_file:
+            input_bytes = pickle.dumps((batch_src, batch_tgt, output_file.name))
+            returned = subprocess.run(
+                [sys.executable, __file__], input=input_bytes, capture_output=True
+            )
+            # check if the subprocess is successful
+            try:
+                returned.check_returncode()
+            except Exception as e:
+                # wrap raised exception to provide more information
+                raise RuntimeError(
+                    f"Error happened when batch testing "
+                    f"peer-to-peer access from {batch_src} to {batch_tgt}:\n"
+                    f"{returned.stderr.decode()}"
+                ) from e
+            with open(output_file.name, "rb") as f:
+                result = pickle.load(f)
+        for _i, _j, r in zip(batch_src, batch_tgt, result):
+            cache[f"{_i}->{_j}"] = r
+        with open(path, "w") as f:
+            json.dump(cache, f, indent=4)
+    if is_distributed:
+        get_world_group().barrier()
+    logger.info("reading GPU P2P access cache from %s", path)
+    with open(path) as f:
+        cache = json.load(f)
+    _gpu_p2p_access_cache = cache
+    return _gpu_p2p_access_cache[f"{src}->{tgt}"]
+
+
+__all__ = ["gpu_p2p_access_check"]
+
+if __name__ == "__main__":
+    batch_src, batch_tgt, output_file = pickle.loads(sys.stdin.buffer.read())
+    result = can_actually_p2p(batch_src, batch_tgt)
+    with open(output_file, "wb") as f:
+        f.write(pickle.dumps(result))
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/hpu_communicator.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/hpu_communicator.py
new file mode 100644
index 0000000000000000000000000000000000000000..722e494cf775cf3a72d73ca511f49de1c6d87059
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/hpu_communicator.py
@@ -0,0 +1,49 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/hpu_communicator.py
+
+import torch
+import torch.distributed as dist
+from torch.distributed import ProcessGroup
+
+from sglang.srt.utils import is_hpu
+
+if is_hpu():
+    import habana_frameworks.torch as htorch  # noqa: F401
+
+
+class HpuCommunicator:
+
+    def __init__(self, group: ProcessGroup):
+        if not is_hpu():
+            self.disabled = True
+            return
+        self.disabled = False
+        self.group = group
+        self.world_size = dist.get_world_size(self.group)
+
+    def all_reduce(self, x: torch.Tensor) -> torch.Tensor:
+        # FIXME(kzawora): this is a workaround for a bug in Habana PT bridge
+        # occurring when PT_HPU_ENABLE_LAZY_COLLECTIVES=true env var is used
+        # (which is required for tensor parallel HPUGraph inference)
+        htorch.core.mark_step()
+        dist.all_reduce(x, group=self.group)
+        return x
+
+    def all_gather(self, x: torch.Tensor, dim: int = -1) -> torch.Tensor:
+        world_size = self.world_size
+        if dim < 0:
+            # Convert negative dim to positive.
+            dim += x.dim()
+        input_size = x.size()
+        # Allocate output tensor.
+        output_tensor = torch.empty(
+            (world_size,) + input_size, dtype=x.dtype, device=x.device
+        )
+        # All-gather.
+        htorch.core.mark_step()
+        dist.all_gather_into_tensor(output_tensor, x, group=self.group)
+        # Reshape
+        output_tensor = output_tensor.movedim(0, dim)
+        output_tensor = output_tensor.reshape(
+            input_size[:dim] + (world_size * input_size[dim],) + input_size[dim + 1 :]
+        )
+        return output_tensor
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl.py
new file mode 100644
index 0000000000000000000000000000000000000000..9f65939f6d913fb4cee7a241dc7ae2a9fec5aecd
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl.py
@@ -0,0 +1,283 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/pynccl.py
+
+import logging
+from contextlib import contextmanager
+from typing import Optional, Union
+
+# ===================== import region =====================
+import torch
+import torch.distributed as dist
+from torch.distributed import ProcessGroup, ReduceOp
+
+from sglang.srt.distributed.device_communicators.pynccl_wrapper import (
+    NCCLLibrary,
+    buffer_type,
+    cudaStream_t,
+    ncclComm_t,
+    ncclDataTypeEnum,
+    ncclRedOpTypeEnum,
+    ncclUniqueId,
+)
+from sglang.srt.distributed.utils import StatelessProcessGroup
+
+logger = logging.getLogger(__name__)
+
+
+class PyNcclCommunicator:
+
+    def __init__(
+        self,
+        group: Union[ProcessGroup, StatelessProcessGroup],
+        device: Union[int, str, torch.device],
+        library_path: Optional[str] = None,
+    ):
+        """
+        Args:
+            group: the process group to work on. If None, it will use the
+                default process group.
+            device: the device to bind the PyNcclCommunicator to. If None,
+                it will be bind to f"cuda:{local_rank}".
+            library_path: the path to the NCCL library. If None, it will
+                use the default library path.
+        It is the caller's responsibility to make sure each communicator
+        is bind to a unique device.
+        """
+        if not isinstance(group, StatelessProcessGroup):
+            assert dist.is_initialized()
+            assert (
+                dist.get_backend(group) != dist.Backend.NCCL
+            ), "PyNcclCommunicator should be attached to a non-NCCL group."
+            # note: this rank is the rank in the group
+            self.rank = dist.get_rank(group)
+            self.world_size = dist.get_world_size(group)
+        else:
+            self.rank = group.rank
+            self.world_size = group.world_size
+
+        self.group = group
+
+        # if world_size == 1, no need to create communicator
+        if self.world_size == 1:
+            self.available = False
+            self.disabled = True
+            self.stream = None
+            return
+        try:
+            self.nccl = NCCLLibrary(library_path)
+        except Exception:
+            # disable because of missing NCCL library
+            # e.g. in a non-GPU environment
+            self.available = False
+            self.disabled = True
+            self.stream = None
+            return
+
+        self.available = True
+        self.disabled = False
+
+        logger.info("sglang is using nccl==%s", self.nccl.ncclGetVersion())
+
+        if self.rank == 0:
+            # get the unique id from NCCL
+            self.unique_id = self.nccl.ncclGetUniqueId()
+        else:
+            # construct an empty unique id
+            self.unique_id = ncclUniqueId()
+
+        if not isinstance(group, StatelessProcessGroup):
+            tensor = torch.ByteTensor(list(self.unique_id.internal))
+            ranks = dist.get_process_group_ranks(group)
+            # arg `src` in `broadcast` is the global rank
+            dist.broadcast(tensor, src=ranks[0], group=group)
+            byte_list = tensor.tolist()
+            for i, byte in enumerate(byte_list):
+                self.unique_id.internal[i] = byte
+        else:
+            self.unique_id = group.broadcast_obj(self.unique_id, src=0)
+        if isinstance(device, int):
+            device = torch.device(f"cuda:{device}")
+        elif isinstance(device, str):
+            device = torch.device(device)
+        # now `device` is a `torch.device` object
+        assert isinstance(device, torch.device)
+        self.device = device
+        # nccl communicator and stream will use this device
+        # `torch.cuda.device` is a context manager that changes the
+        # current cuda device to the specified one
+        with torch.cuda.device(device):
+            self.comm: ncclComm_t = self.nccl.ncclCommInitRank(
+                self.world_size, self.unique_id, self.rank
+            )
+            self.stream = torch.cuda.Stream()
+
+            # A small all_reduce for warmup.
+            data = torch.zeros(1, device=device)
+            self.all_reduce(data)
+            self.stream.synchronize()
+            del data
+
+        # by default it is disabled, e.g. in profiling models and prefill phase.
+        # to use it, use under `with obj.change_state(enable=True)`, usually
+        # when we are using CUDA graph.
+        self.disabled = True
+
+    def all_reduce(
+        self, tensor: torch.Tensor, op: ReduceOp = ReduceOp.SUM, stream=None
+    ):
+        if self.disabled:
+            return
+        # nccl communicator created on a specific device
+        # will only work on tensors on the same device
+        # otherwise it will cause "illegal memory access"
+        assert tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        self.nccl.ncclAllReduce(
+            buffer_type(tensor.data_ptr()),
+            buffer_type(tensor.data_ptr()),
+            tensor.numel(),
+            ncclDataTypeEnum.from_torch(tensor.dtype),
+            ncclRedOpTypeEnum.from_torch(op),
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    def all_gather(
+        self, output_tensor: torch.Tensor, input_tensor: torch.Tensor, stream=None
+    ):
+        if self.disabled:
+            return
+        # nccl communicator created on a specific device
+        # will only work on tensors on the same device
+        # otherwise it will cause "illegal memory access"
+        assert input_tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {input_tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        self.nccl.ncclAllGather(
+            buffer_type(input_tensor.data_ptr()),
+            buffer_type(output_tensor.data_ptr()),
+            input_tensor.numel(),
+            ncclDataTypeEnum.from_torch(input_tensor.dtype),
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    def reduce_scatter(
+        self,
+        output_tensor: torch.Tensor,
+        input_tensor: torch.Tensor,
+        op: ReduceOp = ReduceOp.SUM,
+        stream=None,
+    ):
+        if self.disabled:
+            return
+        # nccl communicator created on a specific device
+        # will only work on tensors on the same device
+        # otherwise it will cause "illegal memory access"
+        assert input_tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {input_tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        self.nccl.ncclReduceScatter(
+            buffer_type(input_tensor.data_ptr()),
+            buffer_type(output_tensor.data_ptr()),
+            output_tensor.numel(),
+            ncclDataTypeEnum.from_torch(input_tensor.dtype),
+            ncclRedOpTypeEnum.from_torch(op),
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    def send(self, tensor: torch.Tensor, dst: int, stream=None):
+        if self.disabled:
+            return
+        assert tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        self.nccl.ncclSend(
+            buffer_type(tensor.data_ptr()),
+            tensor.numel(),
+            ncclDataTypeEnum.from_torch(tensor.dtype),
+            dst,
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    def recv(self, tensor: torch.Tensor, src: int, stream=None):
+        if self.disabled:
+            return
+        assert tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        self.nccl.ncclRecv(
+            buffer_type(tensor.data_ptr()),
+            tensor.numel(),
+            ncclDataTypeEnum.from_torch(tensor.dtype),
+            src,
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    def broadcast(self, tensor: torch.Tensor, src: int, stream=None):
+        if self.disabled:
+            return
+        assert tensor.device == self.device, (
+            f"this nccl communicator is created to work on {self.device}, "
+            f"but the input tensor is on {tensor.device}"
+        )
+        if stream is None:
+            stream = self.stream
+        if src == self.rank:
+            sendbuff = buffer_type(tensor.data_ptr())
+            # NCCL requires the sender also to have a receive buffer
+            recvbuff = buffer_type(tensor.data_ptr())
+        else:
+            sendbuff = buffer_type()
+            recvbuff = buffer_type(tensor.data_ptr())
+        self.nccl.ncclBroadcast(
+            sendbuff,
+            recvbuff,
+            tensor.numel(),
+            ncclDataTypeEnum.from_torch(tensor.dtype),
+            src,
+            self.comm,
+            cudaStream_t(stream.cuda_stream),
+        )
+
+    @contextmanager
+    def change_state(
+        self, enable: Optional[bool] = None, stream: Optional[torch.cuda.Stream] = None
+    ):
+        """
+        A context manager to change the state of the communicator.
+        """
+        if enable is None:
+            # guess a default value when not specified
+            enable = self.available
+
+        if stream is None:
+            stream = self.stream
+
+        old_disable = self.disabled
+        old_stream = self.stream
+
+        self.stream = stream
+        self.disabled = not enable
+        yield
+
+        self.disabled = old_disable
+        self.stream = old_stream
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl_wrapper.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl_wrapper.py
new file mode 100644
index 0000000000000000000000000000000000000000..afb47733476a5a551cbad859694e2e8f8e710ebf
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/pynccl_wrapper.py
@@ -0,0 +1,472 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/pynccl.py
+
+# This file is a pure Python wrapper for the NCCL library.
+# The main purpose is to use NCCL combined with CUDA graph.
+# Before writing this script, we tried the following approach:
+# 1. We tried to use `cupy`, it calls NCCL correctly, but `cupy` itself
+#  often gets stuck when initializing the NCCL communicator.
+# 2. We tried to use `torch.distributed`, but `torch.distributed.all_reduce`
+#  contains many other potential cuda APIs, that are not allowed during
+#  capturing the CUDA graph. For further details, please check
+# https://discuss.pytorch.org/t/pytorch-cudagraph-with-nccl-operation-failed/ .
+#
+# Another rejected idea is to write a C/C++ binding for NCCL. It is usually
+# doable, but we often encounter issues related with nccl versions, and need
+# to switch between different versions of NCCL. See
+# https://github.com/NVIDIA/nccl/issues/1234 for more details.
+# A C/C++ binding is not flexible enough to handle this. It requires
+# recompilation of the code every time we want to switch between different
+# versions. This current implementation, with a **pure** Python wrapper, is
+# more flexible. We can easily switch between different versions of NCCL by
+# changing the environment variable `SGLANG_NCCL_SO_PATH`, or the `so_file`
+# variable in the code.
+
+import ctypes
+import logging
+import os
+import platform
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import torch
+from torch.distributed import ReduceOp
+
+logger = logging.getLogger(__name__)
+
+
+def find_nccl_library() -> str:
+    """
+    We either use the library file specified by the `SGLANG_NCCL_SO_PATH`
+    environment variable, or we find the library file brought by PyTorch.
+    After importing `torch`, `libnccl.so.2` or `librccl.so.1` can be
+    found by `ctypes` automatically.
+    """
+
+    # so_file can be set to None in sglang
+    so_file = os.environ.get("SGLANG_NCCL_SO_PATH", None)
+
+    # manually load the nccl library
+    if so_file:
+        logger.info(
+            "Found nccl from environment variable SGLANG_NCCL_SO_PATH=%s", so_file
+        )
+    else:
+        if torch.version.cuda is not None:
+            so_file = "libnccl.so.2"
+        elif torch.version.hip is not None:
+            so_file = "librccl.so.1"
+        else:
+            raise ValueError("NCCL only supports CUDA and ROCm backends.")
+        logger.debug("Found nccl from library %s", so_file)
+    return so_file
+
+
+# === export types and functions from nccl to Python ===
+# for the original nccl definition, please check
+# https://github.com/NVIDIA/nccl/blob/master/src/nccl.h.in
+
+ncclResult_t = ctypes.c_int
+ncclComm_t = ctypes.c_void_p
+
+
+class ncclUniqueId(ctypes.Structure):
+    _fields_ = [("internal", ctypes.c_byte * 128)]
+
+
+cudaStream_t = ctypes.c_void_p
+buffer_type = ctypes.c_void_p
+
+ncclDataType_t = ctypes.c_int
+
+
+class ncclDataTypeEnum:
+    ncclInt8 = 0
+    ncclChar = 0
+    ncclUint8 = 1
+    ncclInt32 = 2
+    ncclInt = 2
+    ncclUint32 = 3
+    ncclInt64 = 4
+    ncclUint64 = 5
+    ncclFloat16 = 6
+    ncclHalf = 6
+    ncclFloat32 = 7
+    ncclFloat = 7
+    ncclFloat64 = 8
+    ncclDouble = 8
+    ncclBfloat16 = 9
+    ncclNumTypes = 10
+
+    @classmethod
+    def from_torch(cls, dtype: torch.dtype) -> int:
+        if dtype == torch.int8:
+            return cls.ncclInt8
+        if dtype == torch.uint8:
+            return cls.ncclUint8
+        if dtype == torch.int32:
+            return cls.ncclInt32
+        if dtype == torch.int64:
+            return cls.ncclInt64
+        if dtype == torch.float16:
+            return cls.ncclFloat16
+        if dtype == torch.float32:
+            return cls.ncclFloat32
+        if dtype == torch.float64:
+            return cls.ncclFloat64
+        if dtype == torch.bfloat16:
+            return cls.ncclBfloat16
+        raise ValueError(f"Unsupported dtype: {dtype}")
+
+
+ncclRedOp_t = ctypes.c_int
+
+
+class ncclRedOpTypeEnum:
+    ncclSum = 0
+    ncclProd = 1
+    ncclMax = 2
+    ncclMin = 3
+    ncclAvg = 4
+    ncclNumOps = 5
+
+    @classmethod
+    def from_torch(cls, op: ReduceOp) -> int:
+        if op == ReduceOp.SUM:
+            return cls.ncclSum
+        if op == ReduceOp.PRODUCT:
+            return cls.ncclProd
+        if op == ReduceOp.MAX:
+            return cls.ncclMax
+        if op == ReduceOp.MIN:
+            return cls.ncclMin
+        if op == ReduceOp.AVG:
+            return cls.ncclAvg
+        raise ValueError(f"Unsupported op: {op}")
+
+
+@dataclass
+class Function:
+    name: str
+    restype: Any
+    argtypes: List[Any]
+
+
+class NCCLLibrary:
+    exported_functions = [
+        # const char* ncclGetErrorString(ncclResult_t result)
+        Function("ncclGetErrorString", ctypes.c_char_p, [ncclResult_t]),
+        # ncclResult_t  ncclGetVersion(int *version);
+        Function("ncclGetVersion", ncclResult_t, [ctypes.POINTER(ctypes.c_int)]),
+        # ncclResult_t ncclGetUniqueId(ncclUniqueId* uniqueId);
+        Function("ncclGetUniqueId", ncclResult_t, [ctypes.POINTER(ncclUniqueId)]),
+        # ncclResult_t  ncclCommInitRank(
+        #   ncclComm_t* comm, int nranks, ncclUniqueId commId, int rank);
+        # note that ncclComm_t is a pointer type, so the first argument
+        # is a pointer to a pointer
+        Function(
+            "ncclCommInitRank",
+            ncclResult_t,
+            [ctypes.POINTER(ncclComm_t), ctypes.c_int, ncclUniqueId, ctypes.c_int],
+        ),
+        # ncclResult_t  ncclAllReduce(
+        #   const void* sendbuff, void* recvbuff, size_t count,
+        #   ncclDataType_t datatype, ncclRedOp_t op, ncclComm_t comm,
+        #   cudaStream_t stream);
+        # note that cudaStream_t is a pointer type, so the last argument
+        # is a pointer
+        Function(
+            "ncclAllReduce",
+            ncclResult_t,
+            [
+                buffer_type,
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ncclRedOp_t,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # ncclResult_t  ncclAllGather(
+        #   const void* sendbuff, void* recvbuff, size_t count,
+        #   ncclDataType_t datatype, ncclComm_t comm,
+        #   cudaStream_t stream);
+        # note that cudaStream_t is a pointer type, so the last argument
+        # is a pointer
+        Function(
+            "ncclAllGather",
+            ncclResult_t,
+            [
+                buffer_type,
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # ncclResult_t  ncclReduceScatter(
+        #   const void* sendbuff, void* recvbuff, size_t count,
+        #   ncclDataType_t datatype, ncclRedOp_t op, ncclComm_t comm,
+        #   cudaStream_t stream);
+        # note that cudaStream_t is a pointer type, so the last argument
+        # is a pointer
+        Function(
+            "ncclReduceScatter",
+            ncclResult_t,
+            [
+                buffer_type,
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ncclRedOp_t,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # ncclResult_t  ncclSend(
+        #   const void* sendbuff, size_t count, ncclDataType_t datatype,
+        #   int dest, ncclComm_t comm, cudaStream_t stream);
+        Function(
+            "ncclSend",
+            ncclResult_t,
+            [
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ctypes.c_int,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # ncclResult_t  ncclRecv(
+        #   void* recvbuff, size_t count, ncclDataType_t datatype,
+        #   int src, ncclComm_t comm, cudaStream_t stream);
+        Function(
+            "ncclRecv",
+            ncclResult_t,
+            [
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ctypes.c_int,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # ncclResult_t ncclBroadcast(
+        #   const void* sendbuff, void* recvbuff, size_t count,
+        #   ncclDataType_t datatype, int root, ncclComm_t comm,
+        #   cudaStream_t stream);
+        Function(
+            "ncclBroadcast",
+            ncclResult_t,
+            [
+                buffer_type,
+                buffer_type,
+                ctypes.c_size_t,
+                ncclDataType_t,
+                ctypes.c_int,
+                ncclComm_t,
+                cudaStream_t,
+            ],
+        ),
+        # be cautious! this is a collective call, it will block until all
+        # processes in the communicator have called this function.
+        # because Python object destruction can happen in random order,
+        # it is better not to call it at all.
+        # ncclResult_t  ncclCommDestroy(ncclComm_t comm);
+        Function("ncclCommDestroy", ncclResult_t, [ncclComm_t]),
+    ]
+
+    # class attribute to store the mapping from the path to the library
+    # to avoid loading the same library multiple times
+    path_to_library_cache: Dict[str, Any] = {}
+
+    # class attribute to store the mapping from library path
+    #  to the corresponding dictionary
+    path_to_dict_mapping: Dict[str, Dict[str, Any]] = {}
+
+    def __init__(self, so_file: Optional[str] = None):
+
+        so_file = so_file or find_nccl_library()
+
+        try:
+            if so_file not in NCCLLibrary.path_to_dict_mapping:
+                lib = ctypes.CDLL(so_file)
+                NCCLLibrary.path_to_library_cache[so_file] = lib
+            self.lib = NCCLLibrary.path_to_library_cache[so_file]
+        except Exception as e:
+            logger.error(
+                "Failed to load NCCL library from %s ."
+                "It is expected if you are not running on NVIDIA/AMD GPUs."
+                "Otherwise, the nccl library might not exist, be corrupted "
+                "or it does not support the current platform %s."
+                "If you already have the library, please set the "
+                "environment variable SGLANG_NCCL_SO_PATH"
+                " to point to the correct nccl library path.",
+                so_file,
+                platform.platform(),
+            )
+            raise e
+
+        if so_file not in NCCLLibrary.path_to_dict_mapping:
+            _funcs: Dict[str, Any] = {}
+            for func in NCCLLibrary.exported_functions:
+                f = getattr(self.lib, func.name)
+                f.restype = func.restype
+                f.argtypes = func.argtypes
+                _funcs[func.name] = f
+            NCCLLibrary.path_to_dict_mapping[so_file] = _funcs
+        self._funcs = NCCLLibrary.path_to_dict_mapping[so_file]
+
+    def ncclGetErrorString(self, result: ncclResult_t) -> str:
+        return self._funcs["ncclGetErrorString"](result).decode("utf-8")
+
+    def NCCL_CHECK(self, result: ncclResult_t) -> None:
+        if result != 0:
+            error_str = self.ncclGetErrorString(result)
+            raise RuntimeError(f"NCCL error: {error_str}")
+
+    def ncclGetVersion(self) -> str:
+        version = ctypes.c_int()
+        self.NCCL_CHECK(self._funcs["ncclGetVersion"](ctypes.byref(version)))
+        version_str = str(version.value)
+        # something like 21903 --> "2.19.3"
+        major = version_str[0].lstrip("0")
+        minor = version_str[1:3].lstrip("0")
+        patch = version_str[3:].lstrip("0")
+        return f"{major}.{minor}.{patch}"
+
+    def ncclGetUniqueId(self) -> ncclUniqueId:
+        unique_id = ncclUniqueId()
+        self.NCCL_CHECK(self._funcs["ncclGetUniqueId"](ctypes.byref(unique_id)))
+        return unique_id
+
+    def ncclCommInitRank(
+        self, world_size: int, unique_id: ncclUniqueId, rank: int
+    ) -> ncclComm_t:
+        comm = ncclComm_t()
+        self.NCCL_CHECK(
+            self._funcs["ncclCommInitRank"](
+                ctypes.byref(comm), world_size, unique_id, rank
+            )
+        )
+        return comm
+
+    def ncclAllReduce(
+        self,
+        sendbuff: buffer_type,
+        recvbuff: buffer_type,
+        count: int,
+        datatype: int,
+        op: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        # `datatype` actually should be `ncclDataType_t`
+        # and `op` should be `ncclRedOp_t`
+        # both are aliases of `ctypes.c_int`
+        # when we pass int to a function, it will be converted to `ctypes.c_int`
+        # by ctypes automatically
+        self.NCCL_CHECK(
+            self._funcs["ncclAllReduce"](
+                sendbuff, recvbuff, count, datatype, op, comm, stream
+            )
+        )
+
+    def ncclReduceScatter(
+        self,
+        sendbuff: buffer_type,
+        recvbuff: buffer_type,
+        count: int,
+        datatype: int,
+        op: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        # `datatype` actually should be `ncclDataType_t`
+        # and `op` should be `ncclRedOp_t`
+        # both are aliases of `ctypes.c_int`
+        # when we pass int to a function, it will be converted to `ctypes.c_int`
+        # by ctypes automatically
+        self.NCCL_CHECK(
+            self._funcs["ncclReduceScatter"](
+                sendbuff, recvbuff, count, datatype, op, comm, stream
+            )
+        )
+
+    def ncclAllGather(
+        self,
+        sendbuff: buffer_type,
+        recvbuff: buffer_type,
+        count: int,
+        datatype: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        # `datatype` actually should be `ncclDataType_t`
+        # which is an aliases of `ctypes.c_int`
+        # when we pass int to a function, it will be converted to `ctypes.c_int`
+        # by ctypes automatically
+        self.NCCL_CHECK(
+            self._funcs["ncclAllGather"](
+                sendbuff, recvbuff, count, datatype, comm, stream
+            )
+        )
+
+    def ncclSend(
+        self,
+        sendbuff: buffer_type,
+        count: int,
+        datatype: int,
+        dest: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        self.NCCL_CHECK(
+            self._funcs["ncclSend"](sendbuff, count, datatype, dest, comm, stream)
+        )
+
+    def ncclRecv(
+        self,
+        recvbuff: buffer_type,
+        count: int,
+        datatype: int,
+        src: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        self.NCCL_CHECK(
+            self._funcs["ncclRecv"](recvbuff, count, datatype, src, comm, stream)
+        )
+
+    def ncclBroadcast(
+        self,
+        sendbuff: buffer_type,
+        recvbuff: buffer_type,
+        count: int,
+        datatype: int,
+        root: int,
+        comm: ncclComm_t,
+        stream: cudaStream_t,
+    ) -> None:
+        self.NCCL_CHECK(
+            self._funcs["ncclBroadcast"](
+                sendbuff, recvbuff, count, datatype, root, comm, stream
+            )
+        )
+
+    def ncclCommDestroy(self, comm: ncclComm_t) -> None:
+        self.NCCL_CHECK(self._funcs["ncclCommDestroy"](comm))
+
+
+__all__ = [
+    "NCCLLibrary",
+    "ncclDataTypeEnum",
+    "ncclRedOpTypeEnum",
+    "ncclUniqueId",
+    "ncclComm_t",
+    "cudaStream_t",
+    "buffer_type",
+]
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/xpu_communicator.py b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/xpu_communicator.py
new file mode 100644
index 0000000000000000000000000000000000000000..532279f70c358a48a43862ccfb600e1cda2fb3b2
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/device_communicators/xpu_communicator.py
@@ -0,0 +1,48 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/device_communicators/xpu_communicator.py
+
+import torch
+import torch.distributed as dist
+from torch.distributed import ProcessGroup
+
+from sglang.srt.utils import is_xpu
+
+
+class XpuCommunicator:
+
+    def __init__(self, group: ProcessGroup):
+        if not is_xpu():
+            self.disabled = True
+            return
+        self.disabled = False
+        self.group = group
+        self.world_size = dist.get_world_size(self.group)
+
+    def all_reduce(self, x: torch.Tensor) -> torch.Tensor:
+        dist.all_reduce(x, group=self.group)
+        return x
+
+    def gather(
+        self, input_: torch.Tensor, rank_in_group: int, dst: int = 0, dim: int = -1
+    ):
+        # For xpu path, gather doesn't work properly together with ray
+        # cluster so we use all_gather instead for now.
+        input_size = input_.size()
+        # Allocate output tensor.
+        output_tensor = torch.empty(
+            (self.world_size,) + input_size, dtype=input_.dtype, device=input_.device
+        )
+        # All-gather.
+        torch.distributed.all_gather_into_tensor(
+            output_tensor, input_, group=self.group
+        )
+        if rank_in_group == dst:
+            # Reshape
+            output_tensor = output_tensor.movedim(0, dim)
+            output_tensor = output_tensor.reshape(
+                input_size[:dim]
+                + (self.world_size * input_size[dim],)
+                + input_size[dim + 1 :]
+            )
+        else:
+            output_tensor = None
+        return output_tensor
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/parallel_state.py b/lib/python3.12/site-packages/sglang/srt/distributed/parallel_state.py
new file mode 100644
index 0000000000000000000000000000000000000000..e43bc0000135e4842efcde76d26f586f63f2a248
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/parallel_state.py
@@ -0,0 +1,1363 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/parallel_state.py
+
+# Copyright 2023 The vLLM team.
+# Adapted from
+# https://github.com/NVIDIA/Megatron-LM/blob/main/megatron/core/parallel_state.py
+# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved.
+"""vLLM distributed state.
+It takes over the control of the distributed environment from PyTorch.
+The typical workflow is:
+
+- call `init_distributed_environment` to initialize the distributed environment.
+- call `initialize_model_parallel` or `ensure_model_parallel_initialized` to
+ initialize the model parallel groups.
+
+- any code dealing with the distributed stuff
+
+- call `destroy_model_parallel` to destroy the model parallel groups.
+- call `destroy_distributed_environment` to destroy the distributed environment.
+
+If you only need to use the distributed environment without model/pipeline
+ parallelism, you can skip the model parallel initialization and destruction
+ steps.
+"""
+import contextlib
+import gc
+import logging
+import os
+import pickle
+import weakref
+from collections import namedtuple
+from contextlib import contextmanager, nullcontext
+from dataclasses import dataclass
+from datetime import timedelta
+from multiprocessing import shared_memory
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+from unittest.mock import patch
+
+import torch
+import torch.distributed
+from torch.distributed import Backend, ProcessGroup
+
+from sglang.srt.utils import (
+    direct_register_custom_op,
+    is_cuda_alike,
+    supports_custom_op,
+)
+
+
+@dataclass
+class GraphCaptureContext:
+    stream: torch.cuda.Stream
+
+
+TensorMetadata = namedtuple("TensorMetadata", ["device", "dtype", "size"])
+
+
+def _split_tensor_dict(
+    tensor_dict: Dict[str, Union[torch.Tensor, Any]]
+) -> Tuple[List[Tuple[str, Any]], List[torch.Tensor]]:
+    """Split the tensor dictionary into two parts:
+    1. A list of (key, value) pairs. If the value is a tensor, it is replaced
+         by its metadata.
+    2. A list of tensors.
+    """
+    metadata_list: List[Tuple[str, Any]] = []
+    tensor_list: List[torch.Tensor] = []
+    for key, value in tensor_dict.items():
+        if isinstance(value, torch.Tensor):
+            # Note: we cannot use `value.device` here,
+            # because it contains not only the device type but also the device
+            # index (e.g. "cuda:0"). We only need the device type.
+            # receiving side will set the device index.
+            device = value.device.type
+            metadata_list.append(
+                (key, TensorMetadata(device, value.dtype, value.size()))
+            )
+            tensor_list.append(value)
+        else:
+            metadata_list.append((key, value))
+    return metadata_list, tensor_list
+
+
+_group_name_counter: Dict[str, int] = {}
+
+
+def _get_unique_name(name: str) -> str:
+    """Get a unique name for the group.
+    Example:
+    _get_unique_name("tp") -> "tp:0"
+    _get_unique_name("tp") -> "tp:1"
+    """
+    if name not in _group_name_counter:
+        _group_name_counter[name] = 0
+    newname = f"{name}:{_group_name_counter[name]}"
+    _group_name_counter[name] += 1
+    return newname
+
+
+_groups: Dict[str, Callable[[], Optional["GroupCoordinator"]]] = {}
+
+
+def _register_group(group: "GroupCoordinator") -> None:
+    _groups[group.unique_name] = weakref.ref(group)
+
+
+if supports_custom_op():
+
+    def inplace_all_reduce(tensor: torch.Tensor, group_name: str) -> None:
+        assert group_name in _groups, f"Group {group_name} is not found."
+        group = _groups[group_name]()
+        if group is None:
+            raise ValueError(f"Group {group_name} is destroyed.")
+        group._all_reduce_in_place(tensor)
+
+    def inplace_all_reduce_fake(tensor: torch.Tensor, group_name: str) -> None:
+        return
+
+    direct_register_custom_op(
+        op_name="inplace_all_reduce",
+        op_func=inplace_all_reduce,
+        mutates_args=["tensor"],
+        fake_impl=inplace_all_reduce_fake,
+    )
+
+    def outplace_all_reduce(tensor: torch.Tensor, group_name: str) -> torch.Tensor:
+        assert group_name in _groups, f"Group {group_name} is not found."
+        group = _groups[group_name]()
+        if group is None:
+            raise ValueError(f"Group {group_name} is destroyed.")
+        return group._all_reduce_out_place(tensor)
+
+    def outplace_all_reduce_fake(tensor: torch.Tensor, group_name: str) -> torch.Tensor:
+        return torch.empty_like(tensor)
+
+    direct_register_custom_op(
+        op_name="outplace_all_reduce",
+        op_func=outplace_all_reduce,
+        mutates_args=[],
+        fake_impl=outplace_all_reduce_fake,
+    )
+
+    def reg_all_gather_into_tensor(
+        output: torch.Tensor, input: torch.Tensor, group_name: str
+    ) -> None:
+        assert group_name in _groups, f"Group {group_name} is not found."
+        group = _groups[group_name]()
+        if group is None:
+            raise ValueError(f"Group {group_name} is destroyed.")
+        group._all_gather_into_tensor(output, input)
+
+    def reg_all_gather_into_tensor_fake(
+        output: torch.Tensor, input: torch.Tensor, group_name: str
+    ) -> None:
+        pass
+
+    direct_register_custom_op(
+        op_name="reg_all_gather_into_tensor",
+        op_func=reg_all_gather_into_tensor,
+        mutates_args=["output"],
+        fake_impl=reg_all_gather_into_tensor_fake,
+    )
+
+
+class GroupCoordinator:
+    """
+    PyTorch ProcessGroup wrapper for a group of processes.
+    PyTorch ProcessGroup is bound to one specific communication backend,
+        e.g. NCCL, Gloo, MPI, etc.
+    GroupCoordinator takes charge of all the communication operations among
+        the processes in the group. It can route the communication to
+        a specific implementation (e.g. switch allreduce implementation
+        based on the tensor size and cuda graph mode).
+    """
+
+    # available attributes:
+    rank: int  # global rank
+    ranks: List[int]  # global ranks in the group
+    world_size: int  # size of the group
+    # difference between `local_rank` and `rank_in_group`:
+    # if we have a group of size 4 across two nodes:
+    # Process | Node | Rank | Local Rank | Rank in Group
+    #   0     |   0  |  0   |     0      |       0
+    #   1     |   0  |  1   |     1      |       1
+    #   2     |   1  |  2   |     0      |       2
+    #   3     |   1  |  3   |     1      |       3
+    local_rank: int  # local rank used to assign devices
+    rank_in_group: int  # rank inside the group
+    cpu_group: ProcessGroup  # group for CPU communication
+    device_group: ProcessGroup  # group for device communication
+    use_pynccl: bool  # a hint of whether to use PyNccl
+    use_custom_allreduce: bool  # a hint of whether to use CustomAllreduce
+    use_message_queue_broadcaster: (
+        bool  # a hint of whether to use message queue broadcaster
+    )
+    # communicators are only created for world size > 1
+    pynccl_comm: Optional[Any]  # PyNccl communicator
+    ca_comm: Optional[Any]  # Custom allreduce communicator
+    mq_broadcaster: Optional[Any]  # shared memory broadcaster
+
+    def __init__(
+        self,
+        group_ranks: List[List[int]],
+        local_rank: int,
+        torch_distributed_backend: Union[str, Backend],
+        use_pynccl: bool,
+        use_custom_allreduce: bool,
+        use_hpu_communicator: bool,
+        use_xpu_communicator: bool,
+        use_message_queue_broadcaster: bool = False,
+        group_name: Optional[str] = None,
+    ):
+        group_name = group_name or "anonymous"
+        self.unique_name = _get_unique_name(group_name)
+        _register_group(self)
+
+        self.rank = torch.distributed.get_rank()
+        self.local_rank = local_rank
+        self.device_group = None
+        self.cpu_group = None
+
+        for ranks in group_ranks:
+            device_group = torch.distributed.new_group(
+                ranks, backend=torch_distributed_backend
+            )
+            # a group with `gloo` backend, to allow direct coordination between
+            # processes through the CPU.
+            cpu_group = torch.distributed.new_group(ranks, backend="gloo")
+            if self.rank in ranks:
+                self.ranks = ranks
+                self.world_size = len(ranks)
+                self.rank_in_group = ranks.index(self.rank)
+                self.device_group = device_group
+                self.cpu_group = cpu_group
+
+        assert self.cpu_group is not None
+        assert self.device_group is not None
+
+        if is_cuda_alike():
+            self.device = torch.device(f"cuda:{local_rank}")
+        else:
+            self.device = torch.device("cpu")
+
+        self.use_pynccl = use_pynccl
+        self.use_custom_allreduce = use_custom_allreduce
+        self.use_hpu_communicator = use_hpu_communicator
+        self.use_xpu_communicator = use_xpu_communicator
+        self.use_message_queue_broadcaster = use_message_queue_broadcaster
+
+        # lazy import to avoid documentation build error
+        from sglang.srt.distributed.device_communicators.custom_all_reduce import (
+            CustomAllreduce,
+        )
+        from sglang.srt.distributed.device_communicators.pynccl import (
+            PyNcclCommunicator,
+        )
+
+        self.pynccl_comm: Optional[PyNcclCommunicator] = None
+        if use_pynccl and self.world_size > 1:
+            self.pynccl_comm = PyNcclCommunicator(
+                group=self.cpu_group,
+                device=self.device,
+            )
+
+        self.ca_comm: Optional[CustomAllreduce] = None
+        if use_custom_allreduce and self.world_size > 1:
+            # Initialize a custom fast all-reduce implementation.
+            try:
+                self.ca_comm = CustomAllreduce(
+                    group=self.cpu_group,
+                    device=self.device,
+                )
+            except Exception as e:
+                logger.warning(
+                    f"Setup Custom allreduce failed with {e}. To silence this "
+                    "warning, specify --disable-custom-all-reduce explicitly."
+                )
+
+        from sglang.srt.distributed.device_communicators.hpu_communicator import (
+            HpuCommunicator,
+        )
+
+        self.hpu_communicator: Optional[HpuCommunicator] = None
+        if use_hpu_communicator and self.world_size > 1:
+            self.hpu_communicator = HpuCommunicator(group=self.device_group)
+
+        from sglang.srt.distributed.device_communicators.xpu_communicator import (
+            XpuCommunicator,
+        )
+
+        self.xpu_communicator: Optional[XpuCommunicator] = None
+        if use_xpu_communicator and self.world_size > 1:
+            self.xpu_communicator = XpuCommunicator(group=self.device_group)
+
+        from sglang.srt.distributed.device_communicators.shm_broadcast import (
+            MessageQueue,
+        )
+
+        self.mq_broadcaster: Optional[MessageQueue] = None
+        if use_message_queue_broadcaster and self.world_size > 1:
+            self.mq_broadcaster = MessageQueue.create_from_process_group(
+                self.cpu_group, 1 << 22, 6
+            )
+
+    @property
+    def first_rank(self):
+        """Return the global rank of the first process in the group"""
+        return self.ranks[0]
+
+    @property
+    def last_rank(self):
+        """Return the global rank of the last process in the group"""
+        return self.ranks[-1]
+
+    @property
+    def is_first_rank(self):
+        """Return whether the caller is the first process in the group"""
+        return self.rank == self.first_rank
+
+    @property
+    def is_last_rank(self):
+        """Return whether the caller is the last process in the group"""
+        return self.rank == self.last_rank
+
+    @property
+    def next_rank(self):
+        """Return the global rank of the process that follows the caller"""
+        rank_in_group = self.rank_in_group
+        world_size = self.world_size
+        return self.ranks[(rank_in_group + 1) % world_size]
+
+    @property
+    def prev_rank(self):
+        """Return the global rank of the process that precedes the caller"""
+        rank_in_group = self.rank_in_group
+        world_size = self.world_size
+        return self.ranks[(rank_in_group - 1) % world_size]
+
+    @contextmanager
+    def graph_capture(
+        self, graph_capture_context: Optional[GraphCaptureContext] = None
+    ):
+        if graph_capture_context is None:
+            stream = torch.cuda.Stream()
+            graph_capture_context = GraphCaptureContext(stream)
+        else:
+            stream = graph_capture_context.stream
+
+        ca_comm = self.ca_comm
+        maybe_ca_context = nullcontext() if ca_comm is None else ca_comm.capture()
+
+        # ensure all initialization operations complete before attempting to
+        # capture the graph on another stream
+        curr_stream = torch.cuda.current_stream()
+        if curr_stream != stream:
+            stream.wait_stream(curr_stream)
+
+        with torch.cuda.stream(stream), maybe_ca_context:
+            # In graph mode, we have to be very careful about the collective
+            # operations. The current status is:
+            #     allreduce \ Mode   |  Eager  |  Graph  |
+            # --------------------------------------------
+            # custom allreduce       | enabled | enabled |
+            # PyNccl                 | disabled| enabled |
+            # torch.distributed      | enabled | disabled|
+            #
+            # Note that custom allreduce will have a runtime check, if the
+            #  tensor size is too large, it will fallback to the next
+            #  available option.
+            # In summary: When using CUDA graph, we use
+            #  either custom all-reduce kernel or pynccl. When not using
+            #  CUDA graph, we use either custom all-reduce kernel or
+            #  PyTorch NCCL. We always prioritize using custom all-reduce
+            #  kernel but fall back to PyTorch or pynccl if it is
+            #  disabled or not supported.
+            pynccl_comm = self.pynccl_comm
+            maybe_pynccl_context: Any
+            if not pynccl_comm:
+                maybe_pynccl_context = nullcontext()
+            else:
+                maybe_pynccl_context = pynccl_comm.change_state(
+                    enable=True, stream=torch.cuda.current_stream()
+                )
+            with maybe_pynccl_context:
+                yield graph_capture_context
+
+    def all_reduce(self, input_: torch.Tensor) -> torch.Tensor:
+        """
+        User-facing all-reduce function before we actually call the
+        all-reduce operation.
+
+        We need this because Dynamo does not support passing an arbitrary
+        object (`self` in this case) to a custom op. We need to pass the
+         group name as a string, and then look up the group coordinator from
+         the group name, dispatch the all-reduce operation to the group
+         coordinator.
+
+        In addition, PyTorch custom ops do not support mutation or returning
+        a new tensor in the same op. So we need to figure out if the op is
+        in-place or out-of-place ahead of time.
+        """
+        # Bypass the function if we are using only 1 GPU.
+        if self.world_size == 1:
+            return input_
+
+        if input_.is_cpu:
+            import intel_extension_for_pytorch as ipex
+
+            ipex.distributed.all_reduce(input_, group=self.device_group)
+            return input_
+
+        if not supports_custom_op():
+            self._all_reduce_in_place(input_)
+            return input_
+
+        if self.hpu_communicator is not None and not self.hpu_communicator.disabled:
+            return self.hpu_communicator.all_reduce(input_)
+
+        if self.xpu_communicator is not None and not self.xpu_communicator.disabled:
+            return self.xpu_communicator.all_reduce(input_)
+
+        if (
+            self.ca_comm is not None
+            and not self.ca_comm.disabled
+            and self.ca_comm.should_custom_ar(input_)
+        ):
+            return torch.ops.sglang.outplace_all_reduce(
+                input_, group_name=self.unique_name
+            )
+        else:
+            torch.ops.sglang.inplace_all_reduce(input_, group_name=self.unique_name)
+            return input_
+
+    def _all_reduce_out_place(self, input_: torch.Tensor) -> torch.Tensor:
+        ca_comm = self.ca_comm
+        assert ca_comm is not None
+        assert not ca_comm.disabled
+        out = ca_comm.custom_all_reduce(input_)
+        assert out is not None
+        return out
+
+    def _all_reduce_in_place(self, input_: torch.Tensor) -> None:
+        pynccl_comm = self.pynccl_comm
+        if pynccl_comm is not None and not pynccl_comm.disabled:
+            pynccl_comm.all_reduce(input_)
+        else:
+            torch.distributed.all_reduce(input_, group=self.device_group)
+
+    def reduce_scatter(
+        self,
+        output: torch.Tensor,
+        input_list: List[torch.Tensor],
+    ) -> None:
+        # TODO(ch-wan): support other backends
+        torch.distributed.reduce_scatter(output, input_list, group=self.device_group)
+        return output
+
+    def _all_gather_into_tensor(self, output: torch.Tensor, input: torch.Tensor):
+        pynccl_comm = self.pynccl_comm
+        if pynccl_comm is not None and not pynccl_comm.disabled:
+            pynccl_comm.all_gather(output, input)
+        else:
+            torch.distributed.all_gather_into_tensor(
+                output, input, group=self.device_group
+            )
+
+    def all_gather_into_tensor(self, output: torch.Tensor, input: torch.Tensor):
+        if not supports_custom_op():
+            self._all_gather_into_tensor(output, input)
+        else:
+            torch.ops.sglang.reg_all_gather_into_tensor(
+                output, input, group_name=self.unique_name
+            )
+
+    def all_gather(
+        self,
+        input_: torch.Tensor,
+        dim: int = -1,
+        tensor_list: List[torch.Tensor] = None,
+    ) -> torch.Tensor:
+        world_size = self.world_size
+        # Bypass the function if we are using only 1 GPU.
+        if world_size == 1:
+            return input_
+
+        if tensor_list is not None:
+            # TODO(ch-wan): support other backends
+            return torch.distributed.all_gather(
+                tensor_list, input_, group=self.device_group
+            )
+
+        assert (
+            -input_.dim() <= dim < input_.dim()
+        ), f"Invalid dim ({dim}) for input tensor with shape {input_.size()}"
+
+        # For HPUs, use HPU communicator.
+        hpu_comm = self.hpu_communicator
+        if hpu_comm is not None and not hpu_comm.disabled:
+            return hpu_comm.all_gather(input_, dim)
+
+        if dim < 0:
+            # Convert negative dim to positive.
+            dim += input_.dim()
+        input_size = input_.size()
+        # NOTE: we have to use concat-style all-gather here,
+        # stack-style all-gather has compatibility issues with
+        # torch.compile . see https://github.com/pytorch/pytorch/issues/138795
+        output_size = (input_size[0] * world_size,) + input_size[1:]
+        # Allocate output tensor.
+        output_tensor = torch.empty(
+            output_size, dtype=input_.dtype, device=input_.device
+        )
+        # All-gather.
+        self.all_gather_into_tensor(output_tensor, input_)
+        # Reshape
+        output_tensor = output_tensor.reshape((world_size,) + input_size)
+        output_tensor = output_tensor.movedim(0, dim)
+        output_tensor = output_tensor.reshape(
+            input_size[:dim] + (world_size * input_size[dim],) + input_size[dim + 1 :]
+        )
+        return output_tensor
+
+    def gather(
+        self, input_: torch.Tensor, dst: int = 0, dim: int = -1
+    ) -> Optional[torch.Tensor]:
+        """
+        NOTE: We assume that the input tensor is on the same device across
+        all the ranks.
+        NOTE: `dst` is the local rank of the destination rank.
+        """
+        world_size = self.world_size
+        # Bypass the function if we are using only 1 GPU.
+        if world_size == 1:
+            return input_
+        assert (
+            -input_.dim() <= dim < input_.dim()
+        ), f"Invalid dim ({dim}) for input tensor with shape {input_.size()}"
+        if dim < 0:
+            # Convert negative dim to positive.
+            dim += input_.dim()
+        if self.xpu_communicator is not None and not self.xpu_communicator.disabled:
+            return self.xpu_communicator.gather(input_, self.rank_in_group, dst, dim)
+        # Allocate output tensor.
+        if self.rank_in_group == dst:
+            gather_list = [torch.empty_like(input_) for _ in range(world_size)]
+        else:
+            gather_list = None
+        # Gather.
+        torch.distributed.gather(
+            input_, gather_list, dst=self.ranks[dst], group=self.device_group
+        )
+        if self.rank_in_group == dst:
+            output_tensor = torch.cat(gather_list, dim=dim)
+        else:
+            output_tensor = None
+        return output_tensor
+
+    def broadcast(self, input_: torch.Tensor, src: int = 0):
+        """Broadcast the input tensor.
+        NOTE: `src` is the local rank of the source rank.
+        """
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        # Bypass the function if we are using only 1 GPU.
+        if self.world_size == 1:
+            return input_
+        # Broadcast.
+        torch.distributed.broadcast(
+            input_, src=self.ranks[src], group=self.device_group
+        )
+        return input_
+
+    def broadcast_object(self, obj: Optional[Any] = None, src: int = 0):
+        """Broadcast the input object.
+        NOTE: `src` is the local rank of the source rank.
+        """
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        # Bypass the function if we are using only 1 GPU.
+        if self.world_size == 1:
+            return obj
+        if self.mq_broadcaster is not None:
+            assert src == 0, "Message queue broadcaster only supports src=0"
+            return self.mq_broadcaster.broadcast_object(obj)
+        if self.rank_in_group == src:
+            torch.distributed.broadcast_object_list(
+                [obj], src=self.ranks[src], group=self.cpu_group
+            )
+            return obj
+        else:
+            recv = [None]
+            torch.distributed.broadcast_object_list(
+                recv, src=self.ranks[src], group=self.cpu_group
+            )
+            return recv[0]
+
+    def broadcast_object_list(
+        self, obj_list: List[Any], src: int = 0, group: Optional[ProcessGroup] = None
+    ):
+        """Broadcast the input object list.
+        NOTE: `src` is the local rank of the source rank.
+        """
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        # Bypass the function if we are using only 1 GPU.
+        if self.world_size == 1:
+            return obj_list
+        # Broadcast.
+        torch.distributed.broadcast_object_list(
+            obj_list, src=self.ranks[src], group=self.device_group
+        )
+        return obj_list
+
+    def send_object(self, obj: Any, dst: int) -> None:
+        """Send the input object list to the destination rank."""
+        """NOTE: `dst` is the local rank of the destination rank."""
+
+        assert dst < self.world_size, f"Invalid dst rank ({dst})"
+
+        assert dst != self.rank_in_group, (
+            "Invalid destination rank. Destination rank is the same "
+            "as the current rank."
+        )
+
+        # Serialize object to tensor and get the size as well
+        object_tensor = torch.frombuffer(pickle.dumps(obj), dtype=torch.uint8)
+
+        size_tensor = torch.tensor(
+            [object_tensor.numel()], dtype=torch.long, device="cpu"
+        )
+
+        # Send object size
+
+        torch.distributed.send(size_tensor, dst=self.ranks[dst], group=self.cpu_group)
+
+        # Send object
+        torch.distributed.send(object_tensor, dst=self.ranks[dst], group=self.cpu_group)
+
+        return None
+
+    def recv_object(self, src: int) -> Any:
+        """Receive the input object list from the source rank."""
+        """NOTE: `src` is the local rank of the source rank."""
+
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        assert (
+            src != self.rank_in_group
+        ), "Invalid source rank. Source rank is the same as the current rank."
+
+        size_tensor = torch.empty(1, dtype=torch.long, device="cpu")
+
+        # Receive object size
+        rank_size = torch.distributed.recv(
+            size_tensor, src=self.ranks[src], group=self.cpu_group
+        )
+
+        # Tensor to receive serialized objects into.
+        object_tensor = torch.empty(  # type: ignore[call-overload]
+            size_tensor.item(),  # type: ignore[arg-type]
+            dtype=torch.uint8,
+            device="cpu",
+        )
+
+        rank_object = torch.distributed.recv(
+            object_tensor, src=self.ranks[src], group=self.cpu_group
+        )
+
+        assert (
+            rank_object == rank_size
+        ), "Received object sender rank does not match the size sender rank."
+
+        obj = pickle.loads(object_tensor.numpy().tobytes())
+
+        return obj
+
+    def broadcast_tensor_dict(
+        self,
+        tensor_dict: Optional[Dict[str, Union[torch.Tensor, Any]]] = None,
+        src: int = 0,
+        group: Optional[ProcessGroup] = None,
+        metadata_group: Optional[ProcessGroup] = None,
+    ) -> Optional[Dict[str, Union[torch.Tensor, Any]]]:
+        """Broadcast the input tensor dictionary.
+        NOTE: `src` is the local rank of the source rank.
+        """
+        # Bypass the function if we are using only 1 GPU.
+        if not torch.distributed.is_initialized() or self.world_size == 1:
+            return tensor_dict
+
+        group = self.device_group
+        metadata_group = self.cpu_group
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        rank_in_group = self.rank_in_group
+        if rank_in_group == src:
+            metadata_list: List[Tuple[Any, Any]] = []
+            assert isinstance(
+                tensor_dict, dict
+            ), f"Expecting a dictionary, got {type(tensor_dict)}"
+            metadata_list, tensor_list = _split_tensor_dict(tensor_dict)
+            # `metadata_list` lives in CPU memory.
+            # `broadcast_object_list` has serialization & deserialization,
+            # all happening on CPU. Therefore, we can use the CPU group.
+            self.broadcast_object(metadata_list, src=src)
+            async_handles = []
+            for tensor in tensor_list:
+                if tensor.numel() == 0:
+                    # Skip broadcasting empty tensors.
+                    continue
+                if tensor.is_cpu:
+                    # use metadata_group for CPU tensors
+                    handle = torch.distributed.broadcast(
+                        tensor, src=self.ranks[src], group=metadata_group, async_op=True
+                    )
+                else:
+                    # use group for GPU tensors
+                    handle = torch.distributed.broadcast(
+                        tensor, src=self.ranks[src], group=group, async_op=True
+                    )
+                async_handles.append(handle)
+            for async_handle in async_handles:
+                async_handle.wait()
+
+        else:
+            metadata_list = self.broadcast_object(None, src=src)
+            tensor_dict = {}
+            async_handles = []
+            for key, value in metadata_list:
+                if isinstance(value, TensorMetadata):
+                    tensor = torch.empty(
+                        value.size, dtype=value.dtype, device=value.device
+                    )
+                    if tensor.numel() == 0:
+                        # Skip broadcasting empty tensors.
+                        tensor_dict[key] = tensor
+                        continue
+                    if tensor.is_cpu:
+                        # use metadata_group for CPU tensors
+                        handle = torch.distributed.broadcast(
+                            tensor,
+                            src=self.ranks[src],
+                            group=metadata_group,
+                            async_op=True,
+                        )
+                    else:
+                        # use group for GPU tensors
+                        handle = torch.distributed.broadcast(
+                            tensor, src=self.ranks[src], group=group, async_op=True
+                        )
+                    async_handles.append(handle)
+                    tensor_dict[key] = tensor
+                else:
+                    tensor_dict[key] = value
+            for async_handle in async_handles:
+                async_handle.wait()
+        return tensor_dict
+
+    def send_tensor_dict(
+        self,
+        tensor_dict: Dict[str, Union[torch.Tensor, Any]],
+        dst: Optional[int] = None,
+        all_gather_group: Optional["GroupCoordinator"] = None,
+    ) -> Optional[Dict[str, Union[torch.Tensor, Any]]]:
+        """Send the input tensor dictionary.
+        NOTE: `dst` is the local rank of the source rank.
+        """
+        # Bypass the function if we are using only 1 GPU.
+        if not torch.distributed.is_initialized() or self.world_size == 1:
+            return tensor_dict
+
+        all_gather_size = 1 if all_gather_group is None else all_gather_group.world_size
+        all_gather_rank = (
+            0 if all_gather_group is None else all_gather_group.rank_in_group
+        )
+
+        group = self.device_group
+        metadata_group = self.cpu_group
+
+        if dst is None:
+            dst = (self.rank_in_group + 1) % self.world_size
+        assert dst < self.world_size, f"Invalid dst rank ({dst})"
+
+        metadata_list: List[Tuple[Any, Any]] = []
+        assert isinstance(
+            tensor_dict, dict
+        ), f"Expecting a dictionary, got {type(tensor_dict)}"
+        metadata_list, tensor_list = _split_tensor_dict(tensor_dict)
+        # `metadata_list` lives in CPU memory.
+        # `send_object_list` has serialization & deserialization,
+        # all happening on CPU. Therefore, we can use the CPU group.
+        self.send_object(metadata_list, dst=dst)
+        for tensor in tensor_list:
+            if tensor.numel() == 0:
+                # Skip sending empty tensors.
+                continue
+
+            # send-allgather: send only a slice, then do allgather.
+            if all_gather_group is not None and tensor.numel() % all_gather_size == 0:
+                tensor = tensor.reshape(all_gather_size, -1)[all_gather_rank]
+
+            if tensor.is_cpu:
+                # use metadata_group for CPU tensors
+                torch.distributed.send(
+                    tensor, dst=self.ranks[dst], group=metadata_group
+                )
+            else:
+                # use group for GPU tensors
+                torch.distributed.send(tensor, dst=self.ranks[dst], group=group)
+        return None
+
+    def recv_tensor_dict(
+        self,
+        src: Optional[int] = None,
+        all_gather_group: Optional["GroupCoordinator"] = None,
+    ) -> Optional[Dict[str, Union[torch.Tensor, Any]]]:
+        """Recv the input tensor dictionary.
+        NOTE: `src` is the local rank of the source rank.
+        """
+        # Bypass the function if we are using only 1 GPU.
+        if not torch.distributed.is_initialized() or self.world_size == 1:
+            return None
+
+        all_gather_size = 1 if all_gather_group is None else all_gather_group.world_size
+        all_gather_rank = (
+            0 if all_gather_group is None else all_gather_group.rank_in_group
+        )
+
+        group = self.device_group
+        metadata_group = self.cpu_group
+
+        if src is None:
+            src = (self.rank_in_group - 1) % self.world_size
+        assert src < self.world_size, f"Invalid src rank ({src})"
+
+        recv_metadata_list = self.recv_object(src=src)
+        tensor_dict: Dict[str, Any] = {}
+        for key, value in recv_metadata_list:
+            if isinstance(value, TensorMetadata):
+                tensor = torch.empty(value.size, dtype=value.dtype, device=value.device)
+                if tensor.numel() == 0:
+                    # Skip broadcasting empty tensors.
+                    tensor_dict[key] = tensor
+                    continue
+
+                # send-allgather: send only a slice, then do allgather.
+                use_all_gather = (
+                    all_gather_group is not None
+                    and tensor.numel() % all_gather_size == 0
+                )
+
+                if use_all_gather:
+                    orig_shape = tensor.shape
+                    tensor = tensor.reshape(all_gather_size, -1)[all_gather_rank]
+
+                if tensor.is_cpu:
+                    # use metadata_group for CPU tensors
+                    torch.distributed.recv(
+                        tensor, src=self.ranks[src], group=metadata_group
+                    )
+                else:
+                    # use group for GPU tensors
+                    torch.distributed.recv(tensor, src=self.ranks[src], group=group)
+                if use_all_gather:
+                    # do the allgather
+                    tensor = all_gather_group.all_gather(tensor, dim=0)  # type: ignore
+                    tensor = tensor.reshape(orig_shape)
+
+                tensor_dict[key] = tensor
+            else:
+                tensor_dict[key] = value
+        return tensor_dict
+
+    def barrier(self):
+        """Barrier synchronization among the group.
+        NOTE: don't use `device_group` here! `barrier` in NCCL is
+        terrible because it is internally a broadcast operation with
+        secretly created GPU tensors. It is easy to mess up the current
+        device. Use the CPU group instead.
+        """
+        torch.distributed.barrier(group=self.cpu_group)
+
+    def send(self, tensor: torch.Tensor, dst: Optional[int] = None) -> None:
+        """Sends a tensor to the destination rank in a non-blocking way"""
+        """NOTE: `dst` is the local rank of the destination rank."""
+        if dst is None:
+            dst = (self.rank_in_group + 1) % self.world_size
+
+        pynccl_comm = self.pynccl_comm
+        if pynccl_comm is not None and not pynccl_comm.disabled:
+            pynccl_comm.send(tensor, dst)
+        else:
+            torch.distributed.send(tensor, self.ranks[dst], self.device_group)
+
+    def recv(
+        self, size: torch.Size, dtype: torch.dtype, src: Optional[int] = None
+    ) -> torch.Tensor:
+        """Receives a tensor from the source rank."""
+        """NOTE: `src` is the local rank of the source rank."""
+        if src is None:
+            src = (self.rank_in_group - 1) % self.world_size
+
+        tensor = torch.empty(size, dtype=dtype, device=self.device)
+        pynccl_comm = self.pynccl_comm
+        if pynccl_comm is not None and not pynccl_comm.disabled:
+            pynccl_comm.recv(tensor, src)
+        else:
+            torch.distributed.recv(tensor, self.ranks[src], self.device_group)
+        return tensor
+
+    def destroy(self):
+        if self.device_group is not None:
+            torch.distributed.destroy_process_group(self.device_group)
+            self.device_group = None
+        if self.cpu_group is not None:
+            torch.distributed.destroy_process_group(self.cpu_group)
+            self.cpu_group = None
+        if self.pynccl_comm is not None:
+            self.pynccl_comm = None
+        if self.ca_comm is not None:
+            self.ca_comm = None
+        if self.mq_broadcaster is not None:
+            self.mq_broadcaster = None
+
+
+_WORLD: Optional[GroupCoordinator] = None
+
+
+def get_world_group() -> GroupCoordinator:
+    assert _WORLD is not None, "world group is not initialized"
+    return _WORLD
+
+
+def init_world_group(
+    ranks: List[int], local_rank: int, backend: str
+) -> GroupCoordinator:
+    return GroupCoordinator(
+        group_ranks=[ranks],
+        local_rank=local_rank,
+        torch_distributed_backend=backend,
+        use_pynccl=False,
+        use_custom_allreduce=False,
+        use_hpu_communicator=False,
+        use_xpu_communicator=False,
+        group_name="world",
+    )
+
+
+def init_model_parallel_group(
+    group_ranks: List[List[int]],
+    local_rank: int,
+    backend: str,
+    use_custom_allreduce: Optional[bool] = None,
+    use_message_queue_broadcaster: bool = False,
+    group_name: Optional[str] = None,
+) -> GroupCoordinator:
+    if use_custom_allreduce is None:
+        use_custom_allreduce = _ENABLE_CUSTOM_ALL_REDUCE
+    return GroupCoordinator(
+        group_ranks=group_ranks,
+        local_rank=local_rank,
+        torch_distributed_backend=backend,
+        use_pynccl=True,
+        use_custom_allreduce=use_custom_allreduce,
+        use_hpu_communicator=True,
+        use_xpu_communicator=True,
+        use_message_queue_broadcaster=use_message_queue_broadcaster,
+        group_name=group_name,
+    )
+
+
+_TP: Optional[GroupCoordinator] = None
+
+
+def get_tp_group() -> GroupCoordinator:
+    assert _TP is not None, "tensor model parallel group is not initialized"
+    return _TP
+
+
+# kept for backward compatibility
+get_tensor_model_parallel_group = get_tp_group
+
+_PP: Optional[GroupCoordinator] = None
+
+
+def get_pp_group() -> GroupCoordinator:
+    assert _PP is not None, "pipeline model parallel group is not initialized"
+    return _PP
+
+
+# kept for backward compatibility
+get_pipeline_model_parallel_group = get_pp_group
+
+
+@contextmanager
+def graph_capture():
+    """
+    `graph_capture` is a context manager which should surround the code that
+    is capturing the CUDA graph. Its main purpose is to ensure that the
+    some operations will be run after the graph is captured, before the graph
+    is replayed. It returns a `GraphCaptureContext` object which contains the
+    necessary data for the graph capture. Currently, it only contains the
+    stream that the graph capture is running on. This stream is set to the
+    current CUDA stream when the context manager is entered and reset to the
+    default stream when the context manager is exited. This is to ensure that
+    the graph capture is running on a separate stream from the default stream,
+    in order to explicitly distinguish the kernels to capture
+    from other kernels possibly launched on background in the default stream.
+    """
+    with get_tp_group().graph_capture() as context, get_pp_group().graph_capture(
+        context
+    ):
+        yield context
+
+
+logger = logging.getLogger(__name__)
+
+_ENABLE_CUSTOM_ALL_REDUCE = True
+
+
+def set_custom_all_reduce(enable: bool):
+    global _ENABLE_CUSTOM_ALL_REDUCE
+    _ENABLE_CUSTOM_ALL_REDUCE = enable
+
+
+def init_distributed_environment(
+    world_size: int = -1,
+    rank: int = -1,
+    distributed_init_method: str = "env://",
+    local_rank: int = -1,
+    backend: str = "nccl",
+    timeout: Optional[int] = None,
+):
+    logger.debug(
+        "world_size=%d rank=%d local_rank=%d " "distributed_init_method=%s backend=%s",
+        world_size,
+        rank,
+        local_rank,
+        distributed_init_method,
+        backend,
+    )
+    if not torch.distributed.is_initialized():
+        assert distributed_init_method is not None, (
+            "distributed_init_method must be provided when initializing "
+            "distributed environment"
+        )
+        if timeout is not None:
+            assert isinstance(timeout, (int)), "timeout must be a number"
+            assert timeout > 0, "timeout must be positive"
+            timeout = timedelta(seconds=timeout)
+
+        # this backend is used for WORLD
+        torch.distributed.init_process_group(
+            backend=backend,
+            init_method=distributed_init_method,
+            world_size=world_size,
+            rank=rank,
+            timeout=timeout,
+        )
+
+    # set the local rank
+    # local_rank is not available in torch ProcessGroup,
+    # see https://github.com/pytorch/pytorch/issues/122816
+    if local_rank == -1:
+        # local rank not set, this usually happens in single-node
+        # setting, where we can use rank as local rank
+        if distributed_init_method == "env://":
+            local_rank = int(os.environ.get("LOCAL_RANK", "0"))
+        else:
+            local_rank = rank
+    global _WORLD
+    if _WORLD is None:
+        ranks = list(range(torch.distributed.get_world_size()))
+        _WORLD = init_world_group(ranks, local_rank, backend)
+    else:
+        assert (
+            _WORLD.world_size == torch.distributed.get_world_size()
+        ), "world group already initialized with a different world size"
+
+
+def initialize_model_parallel(
+    tensor_model_parallel_size: int = 1,
+    pipeline_model_parallel_size: int = 1,
+    backend: Optional[str] = None,
+) -> None:
+    """
+    Initialize model parallel groups.
+
+    Arguments:
+        tensor_model_parallel_size: number of GPUs used for tensor model
+            parallelism.
+        pipeline_model_parallel_size: number of GPUs used for pipeline model
+            parallelism.
+
+    Let's say we have a total of 8 GPUs denoted by g0 ... g7 and we
+    use 2 GPUs to parallelize the model tensor, and 4 GPUs to parallelize
+    the model pipeline. The present function will
+    create 4 tensor model-parallel groups and 2 pipeline model-parallel groups:
+        4 tensor model-parallel groups:
+            [g0, g1], [g2, g3], [g4, g5], [g6, g7]
+        2 pipeline model-parallel groups:
+            [g0, g2, g4, g6], [g1, g3, g5, g7]
+    Note that for efficiency, the caller should make sure adjacent ranks
+    are on the same DGX box. For example if we are using 2 DGX-1 boxes
+    with a total of 16 GPUs, rank 0 to 7 belong to the first box and
+    ranks 8 to 15 belong to the second box.
+    """
+    # Get world size and rank. Ensure some consistencies.
+    assert torch.distributed.is_initialized()
+    world_size: int = torch.distributed.get_world_size()
+    backend = backend or torch.distributed.get_backend(get_world_group().device_group)
+
+    if world_size != tensor_model_parallel_size * pipeline_model_parallel_size:
+        raise RuntimeError(
+            f"world_size ({world_size}) is not equal to "
+            f"tensor_model_parallel_size ({tensor_model_parallel_size}) x "
+            f"pipeline_model_parallel_size ({pipeline_model_parallel_size})"
+        )
+
+    # Build the tensor model-parallel groups.
+    num_tensor_model_parallel_groups: int = world_size // tensor_model_parallel_size
+    global _TP
+    assert _TP is None, "tensor model parallel group is already initialized"
+    group_ranks = []
+    for i in range(num_tensor_model_parallel_groups):
+        ranks = list(
+            range(i * tensor_model_parallel_size, (i + 1) * tensor_model_parallel_size)
+        )
+        group_ranks.append(ranks)
+
+    # message queue broadcaster is only used in tensor model parallel group
+    _TP = init_model_parallel_group(
+        group_ranks,
+        get_world_group().local_rank,
+        backend,
+        use_message_queue_broadcaster=True,
+        group_name="tp",
+    )
+
+    # Build the pipeline model-parallel groups.
+    num_pipeline_model_parallel_groups: int = world_size // pipeline_model_parallel_size
+    global _PP
+    assert _PP is None, "pipeline model parallel group is already initialized"
+    group_ranks = []
+    for i in range(num_pipeline_model_parallel_groups):
+        ranks = list(range(i, world_size, num_pipeline_model_parallel_groups))
+        group_ranks.append(ranks)
+    # pipeline parallel does not need custom allreduce
+    _PP = init_model_parallel_group(
+        group_ranks,
+        get_world_group().local_rank,
+        backend,
+        use_custom_allreduce=False,
+        group_name="pp",
+    )
+
+
+def ensure_model_parallel_initialized(
+    tensor_model_parallel_size: int,
+    pipeline_model_parallel_size: int,
+    backend: Optional[str] = None,
+) -> None:
+    """Helper to initialize model parallel groups if they are not initialized,
+    or ensure tensor-parallel and pipeline-parallel sizes are equal to expected
+    values if the model parallel groups are initialized.
+    """
+    backend = backend or torch.distributed.get_backend(get_world_group().device_group)
+    if not model_parallel_is_initialized():
+        initialize_model_parallel(
+            tensor_model_parallel_size, pipeline_model_parallel_size, backend
+        )
+        return
+
+    assert get_tensor_model_parallel_world_size() == tensor_model_parallel_size, (
+        "tensor parallel group already initialized, but of unexpected size: "
+        f"{get_tensor_model_parallel_world_size()=} vs. "
+        f"{tensor_model_parallel_size=}"
+    )
+    pp_world_size = get_pp_group().world_size
+    assert pp_world_size == pipeline_model_parallel_size, (
+        "pipeline parallel group already initialized, but of unexpected size: "
+        f"{pp_world_size=} vs. "
+        f"{pipeline_model_parallel_size=}"
+    )
+
+
+def model_parallel_is_initialized():
+    """Check if tensor and pipeline parallel groups are initialized."""
+    return _TP is not None and _PP is not None
+
+
+_TP_STATE_PATCHED = False
+
+
+@contextmanager
+def patch_tensor_parallel_group(tp_group: GroupCoordinator):
+    """Patch the tp group temporarily until this function ends.
+
+    This method is for draft workers of speculative decoding to run draft model
+    with different tp degree from that of target model workers.
+
+    Args:
+        tp_group (GroupCoordinator): the tp group coordinator
+    """
+    global _TP_STATE_PATCHED
+    assert not _TP_STATE_PATCHED, "Should not call when it's already patched"
+
+    _TP_STATE_PATCHED = True
+    old_tp_group = get_tp_group()
+    global _TP
+    _TP = tp_group
+    try:
+        yield
+    finally:
+        # restore the original state
+        _TP_STATE_PATCHED = False
+        _TP = old_tp_group
+
+
+def get_tensor_model_parallel_world_size():
+    """Return world size for the tensor model parallel group."""
+    return get_tp_group().world_size
+
+
+def get_tensor_model_parallel_rank():
+    """Return my rank for the tensor model parallel group."""
+    return get_tp_group().rank_in_group
+
+
+def destroy_model_parallel():
+    """Set the groups to none and destroy them."""
+    global _TP
+    if _TP:
+        _TP.destroy()
+    _TP = None
+
+    global _PP
+    if _PP:
+        _PP.destroy()
+    _PP = None
+
+
+def destroy_distributed_environment():
+    global _WORLD
+    if _WORLD:
+        _WORLD.destroy()
+    _WORLD = None
+    if torch.distributed.is_initialized():
+        torch.distributed.destroy_process_group()
+
+
+def cleanup_dist_env_and_memory(shutdown_ray: bool = False):
+    destroy_model_parallel()
+    destroy_distributed_environment()
+    with contextlib.suppress(AssertionError):
+        torch.distributed.destroy_process_group()
+    if shutdown_ray:
+        import ray  # Lazy import Ray
+
+        ray.shutdown()
+    gc.collect()
+    if not current_platform.is_cpu():
+        if hasattr(torch, "cuda") and torch.cuda.is_available():
+            torch.cuda.empty_cache()
+            if hasattr(torch._C, "_host_emptyCache"):
+                torch._C._host_emptyCache()
+            else:
+                logger.warning(
+                    "torch._C._host_emptyCache() only available in Pytorch >=2.5"
+                )
+        elif hasattr(torch, "xpu") and torch.xpu.is_available():
+            torch.xpu.empty_cache()
+
+
+def in_the_same_node_as(pg: ProcessGroup, source_rank: int = 0) -> List[bool]:
+    """
+    This is a collective operation that returns if each rank is in the same node
+    as the source rank. It tests if processes are attached to the same
+    memory system (shared access to shared memory).
+    """
+    assert (
+        torch.distributed.get_backend(pg) != torch.distributed.Backend.NCCL
+    ), "in_the_same_node_as should be tested with a non-NCCL group."
+    # local rank inside the group
+    rank = torch.distributed.get_rank(group=pg)
+    world_size = torch.distributed.get_world_size(group=pg)
+
+    # local tensor in each process to store the result
+    is_in_the_same_node = torch.tensor([0] * world_size, dtype=torch.int32)
+
+    # global ranks of the processes in the group
+    ranks = torch.distributed.get_process_group_ranks(pg)
+
+    magic_message = b"magic_message"
+    shm = None
+
+    try:
+        with contextlib.suppress(OSError):
+            if rank == source_rank:
+                # create a shared memory segment
+                shm = shared_memory.SharedMemory(create=True, size=128)
+                shm.buf[: len(magic_message)] = magic_message
+                torch.distributed.broadcast_object_list(
+                    [shm.name], src=ranks[source_rank], group=pg
+                )
+                is_in_the_same_node[rank] = 1
+            else:
+                # try to open the shared memory segment
+                recv = [None]
+                torch.distributed.broadcast_object_list(
+                    recv, src=ranks[source_rank], group=pg
+                )
+                name = recv[0]
+                # fix to https://stackoverflow.com/q/62748654/9191338
+                # Python incorrectly tracks shared memory even if it is not
+                # created by the process. The following patch is a workaround.
+                with patch(
+                    "multiprocessing.resource_tracker.register",
+                    lambda *args, **kwargs: None,
+                ):
+                    shm = shared_memory.SharedMemory(name=name)
+                if shm.buf[: len(magic_message)] == magic_message:
+                    is_in_the_same_node[rank] = 1
+    except Exception as e:
+        logger.error("Error ignored in is_in_the_same_node: %s", e)
+    finally:
+        if shm:
+            shm.close()
+
+    torch.distributed.barrier(group=pg)
+
+    # clean up the shared memory segment
+    with contextlib.suppress(OSError):
+        if rank == source_rank and shm:
+            shm.unlink()
+    torch.distributed.all_reduce(is_in_the_same_node, group=pg)
+
+    return [x == 1 for x in is_in_the_same_node.tolist()]
+
+
+vllm_get_pp_group = None
+vllm_get_tp_group = None
+vllm_get_world_group = None
+
+
+def monkey_patch_vllm_parallel_state(reverse: bool = False):
+    try:
+        import vllm.distributed.parallel_state as vllm_parrlel_state
+    except ImportError:
+        return
+
+    global vllm_get_pp_group, vllm_get_tp_group, vllm_get_world_group
+    if vllm_get_pp_group is None:
+        vllm_get_pp_group = vllm_parrlel_state.get_pp_group
+        vllm_get_tp_group = vllm_parrlel_state.get_tp_group
+        vllm_get_world_group = vllm_parrlel_state.get_world_group
+    if reverse:
+        setattr(vllm_parrlel_state, "get_pp_group", vllm_get_pp_group)
+        setattr(vllm_parrlel_state, "get_tp_group", vllm_get_tp_group)
+        setattr(vllm_parrlel_state, "get_world_group", vllm_get_world_group)
+    else:
+        setattr(vllm_parrlel_state, "get_pp_group", get_pp_group)
+        setattr(vllm_parrlel_state, "get_tp_group", get_tp_group)
+        setattr(vllm_parrlel_state, "get_world_group", get_world_group)
diff --git a/lib/python3.12/site-packages/sglang/srt/distributed/utils.py b/lib/python3.12/site-packages/sglang/srt/distributed/utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..e117aa30d073599211f84a880fe2ddcdff944732
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/distributed/utils.py
@@ -0,0 +1,224 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/distributed/utils.py
+
+# Copyright 2023 The vLLM team.
+# Adapted from
+# https://github.com/NVIDIA/Megatron-LM/blob/main/megatron/core/tensor_parallel/utils.py
+# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved.
+import dataclasses
+import logging
+import os
+import pickle
+import time
+from collections import deque
+from typing import Any, Deque, Dict, Optional, Sequence, Tuple
+
+import torch
+from torch.distributed import TCPStore
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_divisibility(numerator, denominator):
+    """Ensure that numerator is divisible by the denominator."""
+    assert numerator % denominator == 0, "{} is not divisible by {}".format(
+        numerator, denominator
+    )
+
+
+def divide(numerator, denominator):
+    """Ensure that numerator is divisible by the denominator and return
+    the division value."""
+    ensure_divisibility(numerator, denominator)
+    return numerator // denominator
+
+
+def split_tensor_along_last_dim(
+    tensor: torch.Tensor,
+    num_partitions: int,
+    contiguous_split_chunks: bool = False,
+) -> Sequence[torch.Tensor]:
+    """Split a tensor along its last dimension.
+
+    Arguments:
+        tensor: input tensor.
+        num_partitions: number of partitions to split the tensor
+        contiguous_split_chunks: If True, make each chunk contiguous
+                                 in memory.
+
+    Returns:
+        A list of Tensors
+    """
+    # Get the size and dimension.
+    last_dim = tensor.dim() - 1
+    last_dim_size = divide(tensor.size()[last_dim], num_partitions)
+    # Split.
+    tensor_list = torch.split(tensor, last_dim_size, dim=last_dim)
+    # NOTE: torch.split does not create contiguous tensors by default.
+    if contiguous_split_chunks:
+        return tuple(chunk.contiguous() for chunk in tensor_list)
+
+    return tensor_list
+
+
+def get_pp_indices(
+    num_hidden_layers: int, pp_rank: int, pp_size: int
+) -> Tuple[int, int]:
+    """Try to evenly distribute layers across partitions.
+    If the number of layers is not divisible by the number of partitions,
+    the last partition will have the remaining layers.
+    """
+    # partition_list_str can be set to None in sglang
+    partition_list_str = os.getenv("SGLANG_PP_LAYER_PARTITION", None)
+    if partition_list_str is not None:
+        try:
+            partitions = [int(layer) for layer in partition_list_str.split(",")]
+        except ValueError as err:
+            raise ValueError(
+                "Invalid partition string: {}".format(partition_list_str)
+            ) from err
+        if len(partitions) != pp_size:
+            raise ValueError(f"{len(partitions)=} does not match {pp_size=}.")
+        if sum(partitions) != num_hidden_layers:
+            raise ValueError(f"{sum(partitions)=} does not match {num_hidden_layers=}.")
+        start_layer = sum(partitions[:pp_rank])
+        end_layer = start_layer + partitions[pp_rank]
+    else:
+        layers_per_partition = num_hidden_layers // pp_size
+        start_layer = pp_rank * layers_per_partition
+        end_layer = start_layer + layers_per_partition
+
+        if pp_rank == pp_size - 1:
+            end_layer = num_hidden_layers
+
+    return (start_layer, end_layer)
+
+
+@dataclasses.dataclass
+class StatelessProcessGroup:
+    """A dataclass to hold a metadata store, and the rank, world_size of the
+    group. Only use it to communicate metadata between processes.
+    For data-plane communication, create NCCL-related objects.
+    """
+
+    rank: int
+    world_size: int
+    store: torch._C._distributed_c10d.Store
+    data_expiration_seconds: int = 3600  # 1 hour
+
+    # dst rank -> counter
+    send_dst_counter: Dict[int, int] = dataclasses.field(default_factory=dict)
+    # src rank -> counter
+    recv_src_counter: Dict[int, int] = dataclasses.field(default_factory=dict)
+    broadcast_send_counter: int = 0
+    broadcast_recv_src_counter: Dict[int, int] = dataclasses.field(default_factory=dict)
+
+    # A deque to store the data entries, with key and timestamp.
+    entries: Deque[Tuple[str, float]] = dataclasses.field(default_factory=deque)
+
+    def __post_init__(self):
+        assert self.rank < self.world_size
+        self.send_dst_counter = {i: 0 for i in range(self.world_size)}
+        self.recv_src_counter = {i: 0 for i in range(self.world_size)}
+        self.broadcast_recv_src_counter = {i: 0 for i in range(self.world_size)}
+
+    def send_obj(self, obj: Any, dst: int):
+        """Send an object to a destination rank."""
+        self.expire_data()
+        key = f"send_to/{dst}/{self.send_dst_counter[dst]}"
+        self.store.set(key, pickle.dumps(obj))
+        self.send_dst_counter[dst] += 1
+        self.entries.append((key, time.time()))
+
+    def expire_data(self):
+        """Expire data that is older than `data_expiration_seconds` seconds."""
+        while self.entries:
+            # check the oldest entry
+            key, timestamp = self.entries[0]
+            if time.time() - timestamp > self.data_expiration_seconds:
+                self.store.delete_key(key)
+                self.entries.popleft()
+            else:
+                break
+
+    def recv_obj(self, src: int) -> Any:
+        """Receive an object from a source rank."""
+        obj = pickle.loads(
+            self.store.get(f"send_to/{self.rank}/{self.recv_src_counter[src]}")
+        )
+        self.recv_src_counter[src] += 1
+        return obj
+
+    def broadcast_obj(self, obj: Optional[Any], src: int) -> Any:
+        """Broadcast an object from a source rank to all other ranks.
+        It does not clean up after all ranks have received the object.
+        Use it for limited times, e.g., for initialization.
+        """
+        if self.rank == src:
+            self.expire_data()
+            key = f"broadcast_from/{src}/" f"{self.broadcast_send_counter}"
+            self.store.set(key, pickle.dumps(obj))
+            self.broadcast_send_counter += 1
+            self.entries.append((key, time.time()))
+            return obj
+        else:
+            key = f"broadcast_from/{src}/" f"{self.broadcast_recv_src_counter[src]}"
+            recv_obj = pickle.loads(self.store.get(key))
+            self.broadcast_recv_src_counter[src] += 1
+            return recv_obj
+
+    def all_gather_obj(self, obj: Any) -> list[Any]:
+        """All gather an object from all ranks."""
+        gathered_objs = []
+        for i in range(self.world_size):
+            if i == self.rank:
+                gathered_objs.append(obj)
+                self.broadcast_obj(obj, src=self.rank)
+            else:
+                recv_obj = self.broadcast_obj(None, src=i)
+                gathered_objs.append(recv_obj)
+        return gathered_objs
+
+    def barrier(self):
+        """A barrier to synchronize all ranks."""
+        for i in range(self.world_size):
+            if i == self.rank:
+                self.broadcast_obj(None, src=self.rank)
+            else:
+                self.broadcast_obj(None, src=i)
+
+    @staticmethod
+    def create(
+        host: str,
+        port: int,
+        rank: int,
+        world_size: int,
+        data_expiration_seconds: int = 3600,
+    ) -> "StatelessProcessGroup":
+        """A replacement for `torch.distributed.init_process_group` that does not
+        pollute the global state.
+
+        If we have process A and process B called `torch.distributed.init_process_group`
+        to form a group, and then we want to form another group with process A, B, C,
+        D, it is not possible in PyTorch, because process A and process B have already
+        formed a group, and process C and process D cannot join that group. This
+        function is a workaround for this issue.
+
+        `torch.distributed.init_process_group` is a global call, while this function
+        is a stateless call. It will return a `StatelessProcessGroup` object that can be
+        used for exchanging metadata. With this function, process A and process B
+        can call `StatelessProcessGroup.create` to form a group, and then process A, B,
+        C, and D can call `StatelessProcessGroup.create` to form another group.
+        """  # noqa
+        store = TCPStore(
+            host_name=host,
+            port=port,
+            world_size=world_size,
+            is_master=(rank == 0),
+        )
+
+        return StatelessProcessGroup(
+            rank=rank,
+            world_size=world_size,
+            store=store,
+            data_expiration_seconds=data_expiration_seconds,
+        )
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/EngineBase.py b/lib/python3.12/site-packages/sglang/srt/entrypoints/EngineBase.py
new file mode 100644
index 0000000000000000000000000000000000000000..894a6f0651971d6e37a43eab60a3b28228aef0a6
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/entrypoints/EngineBase.py
@@ -0,0 +1,53 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Iterator, List, Optional, Tuple, Union
+
+import torch
+
+
+class EngineBase(ABC):
+    """
+    Abstract base class for engine interfaces that support generation, weight updating, and memory control.
+    This base class provides a unified API for both HTTP-based engines and engines.
+    """
+
+    @abstractmethod
+    def generate(
+        self,
+        prompt: Optional[Union[List[str], str]] = None,
+        sampling_params: Optional[Union[List[Dict], Dict]] = None,
+        input_ids: Optional[Union[List[List[int]], List[int]]] = None,
+        image_data: Optional[Union[List[str], str]] = None,
+        return_logprob: Optional[Union[List[bool], bool]] = False,
+        logprob_start_len: Optional[Union[List[int], int]] = None,
+        top_logprobs_num: Optional[Union[List[int], int]] = None,
+        token_ids_logprob: Optional[Union[List[List[int]], List[int]]] = None,
+        lora_path: Optional[Union[List[Optional[str]], Optional[str]]] = None,
+        custom_logit_processor: Optional[Union[List[str], str]] = None,
+    ) -> Union[Dict, Iterator[Dict]]:
+        """Generate outputs based on given inputs."""
+        pass
+
+    @abstractmethod
+    def update_weights_from_tensor(
+        self,
+        named_tensors: List[Tuple[str, torch.Tensor]],
+        load_format: Optional[str] = None,
+        flush_cache: bool = True,
+    ):
+        """Update model weights with in-memory tensor data."""
+        pass
+
+    @abstractmethod
+    def release_memory_occupation(self):
+        """Release GPU memory occupation temporarily."""
+        pass
+
+    @abstractmethod
+    def resume_memory_occupation(self):
+        """Resume GPU memory occupation which is previously released."""
+        pass
+
+    @abstractmethod
+    def shutdown(self):
+        """Shutdown the engine and clean up resources."""
+        pass
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/EngineBase.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/EngineBase.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..5e3ba31a5f8880deea55c6768f879a07d093cdfd
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/EngineBase.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/engine.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/engine.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..2c0effb7fc20357aba0ecac56880e0c5277fe879
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/engine.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..b1f3dbb821f293257787b5ba81b176152f72a9eb
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server_engine.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server_engine.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..a4856e71fc1316259c9f2a1abbaea22e2ec76eb2
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/http_server_engine.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/verl_engine.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/verl_engine.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..0694e902ad890d6acbae87470c53db640b1a8094
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/entrypoints/__pycache__/verl_engine.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/engine.py b/lib/python3.12/site-packages/sglang/srt/entrypoints/engine.py
new file mode 100644
index 0000000000000000000000000000000000000000..b03e3a494b5fdcf82f4c8b32c739646f39fe4579
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/entrypoints/engine.py
@@ -0,0 +1,613 @@
+# Copyright 2023-2024 SGLang Team
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""
+The entry point of inference server. (SRT = SGLang Runtime)
+
+This file implements python APIs for the inference engine.
+"""
+
+import asyncio
+import atexit
+import dataclasses
+import logging
+import multiprocessing as mp
+import os
+import signal
+import threading
+from typing import AsyncIterator, Dict, Iterator, List, Optional, Tuple, Union
+
+import zmq
+import zmq.asyncio
+from PIL.Image import Image
+
+# Fix a bug of Python threading
+setattr(threading, "_register_atexit", lambda *args, **kwargs: None)
+
+import torch
+import uvloop
+
+from sglang.srt.code_completion_parser import load_completion_template_for_openai_api
+from sglang.srt.entrypoints.EngineBase import EngineBase
+from sglang.srt.managers.data_parallel_controller import (
+    run_data_parallel_controller_process,
+)
+from sglang.srt.managers.detokenizer_manager import run_detokenizer_process
+from sglang.srt.managers.io_struct import (
+    EmbeddingReqInput,
+    GenerateReqInput,
+    GetWeightsByNameReqInput,
+    InitWeightsUpdateGroupReqInput,
+    ReleaseMemoryOccupationReqInput,
+    ResumeMemoryOccupationReqInput,
+    RpcReqInput,
+    RpcReqOutput,
+    UpdateWeightFromDiskReqInput,
+    UpdateWeightsFromDistributedReqInput,
+    UpdateWeightsFromTensorReqInput,
+)
+from sglang.srt.managers.scheduler import run_scheduler_process
+from sglang.srt.managers.tokenizer_manager import TokenizerManager
+from sglang.srt.openai_api.adapter import load_chat_template_for_openai_api
+from sglang.srt.server_args import PortArgs, ServerArgs
+from sglang.srt.torch_memory_saver_adapter import TorchMemorySaverAdapter
+from sglang.srt.utils import (
+    MultiprocessingSerializer,
+    assert_pkg_version,
+    configure_logger,
+    get_zmq_socket,
+    is_cuda,
+    kill_process_tree,
+    launch_dummy_health_check_server,
+    maybe_set_triton_cache_manager,
+    prepare_model_and_tokenizer,
+    set_prometheus_multiproc_dir,
+    set_ulimit,
+)
+from sglang.version import __version__
+
+logger = logging.getLogger(__name__)
+asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+
+_is_cuda = is_cuda()
+
+
+class Engine(EngineBase):
+    """
+    The entry point to the inference engine.
+
+    - The engine consists of three components:
+        1. TokenizerManager: Tokenizes the requests and sends them to the scheduler.
+        2. Scheduler (subprocess): Receives requests from the Tokenizer Manager, schedules batches, forwards them, and sends the output tokens to the Detokenizer Manager.
+        3. DetokenizerManager (subprocess): Detokenizes the output tokens and sends the result back to the Tokenizer Manager.
+
+    Note:
+    1. The HTTP server, Engine, and TokenizerManager both run in the main process.
+    2. Inter-process communication is done through ICP (each process uses a different port) via the ZMQ library.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        The arguments of this function is the same as `sglang/srt/server_args.py::ServerArgs`.
+        Please refer to `ServerArgs` for the documentation.
+        """
+        if "server_args" in kwargs:
+            # Directly load server_args
+            server_args = kwargs["server_args"]
+        else:
+            # Construct server_args from kwargs
+            if "log_level" not in kwargs:
+                # Do not print logs by default
+                kwargs["log_level"] = "error"
+            server_args = ServerArgs(**kwargs)
+
+        # Shutdown the subprocesses automatically when the program exits
+        atexit.register(self.shutdown)
+
+        # Allocate ports for inter-process communications
+        port_args = PortArgs.init_new(server_args)
+        logger.info(f"{server_args=}")
+
+        # Launch subprocesses
+        tokenizer_manager, scheduler_info = _launch_subprocesses(
+            server_args=server_args,
+            port_args=port_args,
+        )
+
+        self.server_args = server_args
+        self.tokenizer_manager = tokenizer_manager
+        self.scheduler_info = scheduler_info
+
+        context = zmq.Context(2)
+        self.send_to_rpc = get_zmq_socket(
+            context, zmq.DEALER, port_args.rpc_ipc_name, True
+        )
+
+    def generate(
+        self,
+        # The input prompt. It can be a single prompt or a batch of prompts.
+        prompt: Optional[Union[List[str], str]] = None,
+        sampling_params: Optional[Union[List[Dict], Dict]] = None,
+        # The token ids for text; one can either specify text or input_ids.
+        input_ids: Optional[Union[List[List[int]], List[int]]] = None,
+        # The image input. It can be an image instance, file name, URL, or base64 encoded string.
+        # Can be formatted as:
+        # - Single image for a single request
+        # - List of images (one per request in a batch)
+        # - List of lists of images (multiple images per request)
+        # See also python/sglang/srt/utils.py:load_image for more details.
+        image_data: Optional[
+            Union[
+                List[List[Union[Image, str]]],
+                List[Union[Image, str]],
+                Union[Image, str],
+            ]
+        ] = None,
+        return_logprob: Optional[Union[List[bool], bool]] = False,
+        logprob_start_len: Optional[Union[List[int], int]] = None,
+        top_logprobs_num: Optional[Union[List[int], int]] = None,
+        token_ids_logprob: Optional[Union[List[List[int]], List[int]]] = None,
+        lora_path: Optional[List[Optional[str]]] = None,
+        custom_logit_processor: Optional[Union[List[str], str]] = None,
+        return_hidden_states: bool = False,
+        stream: bool = False,
+    ) -> Union[Dict, Iterator[Dict]]:
+        """
+        The arguments of this function is the same as `sglang/srt/managers/io_struct.py::GenerateReqInput`.
+        Please refer to `GenerateReqInput` for the documentation.
+        """
+        obj = GenerateReqInput(
+            text=prompt,
+            input_ids=input_ids,
+            sampling_params=sampling_params,
+            image_data=image_data,
+            return_logprob=return_logprob,
+            logprob_start_len=logprob_start_len,
+            top_logprobs_num=top_logprobs_num,
+            token_ids_logprob=token_ids_logprob,
+            lora_path=lora_path,
+            custom_logit_processor=custom_logit_processor,
+            return_hidden_states=return_hidden_states,
+            stream=stream,
+        )
+        loop = asyncio.get_event_loop()
+        generator = self.tokenizer_manager.generate_request(obj, None)
+
+        if stream:
+
+            def generator_wrapper():
+                while True:
+                    try:
+                        chunk = loop.run_until_complete(generator.__anext__())
+                        yield chunk
+                    except StopAsyncIteration:
+                        break
+
+            return generator_wrapper()
+        else:
+            ret = loop.run_until_complete(generator.__anext__())
+            return ret
+
+    async def async_generate(
+        self,
+        # The input prompt. It can be a single prompt or a batch of prompts.
+        prompt: Optional[Union[List[str], str]] = None,
+        sampling_params: Optional[Union[List[Dict], Dict]] = None,
+        # The token ids for text; one can either specify text or input_ids.
+        input_ids: Optional[Union[List[List[int]], List[int]]] = None,
+        # The image input. It can be an image instance, file name, URL, or base64 encoded string.
+        # Can be formatted as:
+        # - Single image for a single request
+        # - List of images (one per request in a batch)
+        # - List of lists of images (multiple images per request)
+        # See also python/sglang/srt/utils.py:load_image for more details.
+        image_data: Optional[
+            Union[
+                List[List[Union[Image, str]]],
+                List[Union[Image, str]],
+                Union[Image, str],
+            ]
+        ] = None,
+        return_logprob: Optional[Union[List[bool], bool]] = False,
+        logprob_start_len: Optional[Union[List[int], int]] = None,
+        top_logprobs_num: Optional[Union[List[int], int]] = None,
+        token_ids_logprob: Optional[Union[List[List[int]], List[int]]] = None,
+        lora_path: Optional[List[Optional[str]]] = None,
+        custom_logit_processor: Optional[Union[List[str], str]] = None,
+        stream: bool = False,
+    ) -> Union[Dict, AsyncIterator[Dict]]:
+        """
+        The arguments of this function is the same as `sglang/srt/managers/io_struct.py::GenerateReqInput`.
+        Please refer to `GenerateReqInput` for the documentation.
+        """
+        obj = GenerateReqInput(
+            text=prompt,
+            input_ids=input_ids,
+            sampling_params=sampling_params,
+            image_data=image_data,
+            return_logprob=return_logprob,
+            logprob_start_len=logprob_start_len,
+            top_logprobs_num=top_logprobs_num,
+            token_ids_logprob=token_ids_logprob,
+            lora_path=lora_path,
+            stream=stream,
+            custom_logit_processor=custom_logit_processor,
+        )
+        generator = self.tokenizer_manager.generate_request(obj, None)
+
+        if stream is True:
+            return generator
+        else:
+            return await generator.__anext__()
+
+    def encode(
+        self,
+        prompt: Union[str, List[str], List[Dict], List[List[Dict]]],
+        image_data: Optional[
+            Union[
+                List[List[Union[Image, str]]],
+                List[Union[Image, str]],
+                Union[Image, str],
+            ]
+        ] = None,
+    ) -> Dict:
+        """
+        The arguments of this function is the same as `sglang/srt/managers/io_struct.py::EmbeddingReqInput`.
+        Please refer to `EmbeddingReqInput` for the documentation.
+        """
+        obj = EmbeddingReqInput(text=prompt, image_data=image_data)
+        loop = asyncio.get_event_loop()
+        generator = self.tokenizer_manager.generate_request(obj, None)
+        ret = loop.run_until_complete(generator.__anext__())
+        return ret
+
+    def shutdown(self):
+        """Shutdown the engine"""
+        kill_process_tree(os.getpid(), include_parent=False)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.shutdown()
+        return False
+
+    def flush_cache(self):
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(self.tokenizer_manager.flush_cache())
+
+    def start_profile(self):
+        loop = asyncio.get_event_loop()
+        loop.run_until_complete(self.tokenizer_manager.start_profile())
+
+    def stop_profile(self):
+        self.tokenizer_manager.stop_profile()
+
+    def get_server_info(self):
+        loop = asyncio.get_event_loop()
+        internal_states = loop.run_until_complete(
+            self.tokenizer_manager.get_internal_state()
+        )
+
+        return {
+            **dataclasses.asdict(self.tokenizer_manager.server_args),
+            **self.scheduler_info,
+            **internal_states,
+            "version": __version__,
+        }
+
+    def init_weights_update_group(
+        self,
+        master_address: str,
+        master_port: int,
+        rank_offset: int,
+        world_size: int,
+        group_name: str,
+        backend: str = "nccl",
+    ):
+        """Initialize parameter update group."""
+        obj = InitWeightsUpdateGroupReqInput(
+            master_address=master_address,
+            master_port=master_port,
+            rank_offset=rank_offset,
+            world_size=world_size,
+            group_name=group_name,
+            backend=backend,
+        )
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.init_weights_update_group(obj, None)
+        )
+
+    def update_weights_from_distributed(self, name: str, dtype, shape):
+        """Update weights from distributed source."""
+        obj = UpdateWeightsFromDistributedReqInput(
+            name=name,
+            dtype=dtype,
+            shape=shape,
+        )
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.update_weights_from_distributed(obj, None)
+        )
+
+    def update_weights_from_tensor(
+        self,
+        named_tensors: List[Tuple[str, torch.Tensor]],
+        load_format: Optional[str] = None,
+        flush_cache: bool = True,
+    ):
+        """Update weights from distributed source. If there are going to be more updates, set `flush_cache` to be true
+        to avoid duplicated operations such as clearing cache."""
+        obj = UpdateWeightsFromTensorReqInput(
+            serialized_named_tensors=[
+                MultiprocessingSerializer.serialize(named_tensors)
+                for _ in range(self.server_args.tp_size)
+            ],
+            load_format=load_format,
+            flush_cache=flush_cache,
+        )
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.update_weights_from_tensor(obj, None)
+        )
+
+    def update_weights_from_disk(
+        self,
+        model_path: str,
+        load_format: Optional[str] = None,
+    ):
+        """Update the weights from disk inplace without re-launching the engine.
+
+        This method allows updating the model weights from disk without restarting
+        the engine. It can be used to load a different model or update weights with
+        new training.
+        """
+        obj = UpdateWeightFromDiskReqInput(
+            model_path=model_path,
+            load_format=load_format,
+        )
+
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.update_weights_from_disk(obj, None)
+        )
+
+    def get_weights_by_name(self, name: str, truncate_size: int = 100):
+        """Get weights by parameter name."""
+        obj = GetWeightsByNameReqInput(name=name, truncate_size=truncate_size)
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.get_weights_by_name(obj, None)
+        )
+
+    def release_memory_occupation(self):
+        """Release GPU occupation temporarily."""
+        obj = ReleaseMemoryOccupationReqInput()
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.release_memory_occupation(obj, None)
+        )
+
+    def resume_memory_occupation(self):
+        """Resume GPU occupation."""
+        obj = ResumeMemoryOccupationReqInput()
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(
+            self.tokenizer_manager.resume_memory_occupation(obj, None)
+        )
+
+    """
+    Execute an RPC call on all scheduler processes.
+    """
+
+    def collective_rpc(self, method: str, **kwargs):
+        obj = RpcReqInput(method=method, parameters=kwargs)
+        self.send_to_rpc.send_pyobj(obj)
+        recv_req = self.send_to_rpc.recv_pyobj(zmq.BLOCKY)
+        assert isinstance(recv_req, RpcReqOutput)
+        assert recv_req.success, recv_req.message
+
+    def save_remote_model(self, **kwargs):
+        self.collective_rpc("save_remote_model", **kwargs)
+
+    def save_sharded_model(self, **kwargs):
+        self.collective_rpc("save_sharded_model", **kwargs)
+
+
+def _set_envs_and_config(server_args: ServerArgs):
+    # Set global environments
+    os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
+    os.environ["NCCL_CUMEM_ENABLE"] = "0"
+    os.environ["NCCL_NVLS_ENABLE"] = str(int(server_args.enable_nccl_nvls))
+    os.environ["TORCH_NCCL_AVOID_RECORD_STREAMS"] = "1"
+    os.environ["CUDA_DEVICE_MAX_CONNECTIONS"] = "4"
+    os.environ["CUDA_MODULE_LOADING"] = "AUTO"
+
+    # Set prometheus env vars
+    if server_args.enable_metrics:
+        set_prometheus_multiproc_dir()
+
+    # Set ulimit
+    set_ulimit()
+
+    # Fix triton bugs
+    if server_args.tp_size * server_args.dp_size > 1:
+        # FIXME: remove this after https://github.com/triton-lang/triton/pull/4295 is used as a dependency.
+        maybe_set_triton_cache_manager()
+
+    # Check flashinfer version
+    if server_args.attention_backend == "flashinfer":
+        assert_pkg_version(
+            "flashinfer_python",
+            "0.2.3",
+            "Please uninstall the old version and "
+            "reinstall the latest version by following the instructions "
+            "at https://docs.flashinfer.ai/installation.html.",
+        )
+    if _is_cuda:
+        assert_pkg_version(
+            "sgl-kernel",
+            "0.1.0",
+            "Please reinstall the latest version with `pip install sgl-kernel --force-reinstall`",
+        )
+
+    def sigchld_handler(signum, frame):
+        pid, exitcode = os.waitpid(0, os.WNOHANG)
+        if exitcode != 0:
+            logger.warning(
+                "Child process unexpectedly failed with an exit code %d. pid=%d",
+                exitcode,
+                pid,
+            )
+
+    signal.signal(signal.SIGCHLD, sigchld_handler)
+
+    # Register the signal handler.
+    # The child processes will send SIGQUIT to this process when any error happens
+    # This process then clean up the whole process tree
+    def sigquit_handler(signum, frame):
+        logger.error(
+            "Received sigquit from a child process. It usually means the child failed."
+        )
+        kill_process_tree(os.getpid())
+
+    signal.signal(signal.SIGQUIT, sigquit_handler)
+
+    # Set mp start method
+    mp.set_start_method("spawn", force=True)
+
+
+def _launch_subprocesses(
+    server_args: ServerArgs, port_args: Optional[PortArgs] = None
+) -> Tuple[TokenizerManager, Dict]:
+    """
+    Launch the TokenizerManager in the main process, the Scheduler in a subprocess, and the DetokenizerManager in another subprocess.
+    """
+    # Configure global environment
+    configure_logger(server_args)
+    server_args.check_server_args()
+    _set_envs_and_config(server_args)
+
+    # Allocate ports for inter-process communications
+    if port_args is None:
+        port_args = PortArgs.init_new(server_args)
+        logger.info(f"{server_args=}")
+
+    # If using model from www.modelscope.cn, first download the model.
+    server_args.model_path, server_args.tokenizer_path = prepare_model_and_tokenizer(
+        server_args.model_path, server_args.tokenizer_path
+    )
+
+    scheduler_procs = []
+    if server_args.dp_size == 1:
+        # Launch tensor parallel scheduler processes
+        memory_saver_adapter = TorchMemorySaverAdapter.create(
+            enable=server_args.enable_memory_saver
+        )
+
+        scheduler_pipe_readers = []
+        tp_size_per_node = server_args.tp_size // server_args.nnodes
+        tp_rank_range = range(
+            tp_size_per_node * server_args.node_rank,
+            tp_size_per_node * (server_args.node_rank + 1),
+        )
+        for tp_rank in tp_rank_range:
+            reader, writer = mp.Pipe(duplex=False)
+            gpu_id = (
+                server_args.base_gpu_id
+                + (tp_rank % tp_size_per_node) * server_args.gpu_id_step
+            )
+            proc = mp.Process(
+                target=run_scheduler_process,
+                args=(server_args, port_args, gpu_id, tp_rank, None, writer),
+            )
+            with memory_saver_adapter.configure_subprocess():
+                proc.start()
+            scheduler_procs.append(proc)
+            scheduler_pipe_readers.append(reader)
+    else:
+        # Launch the data parallel controller
+        reader, writer = mp.Pipe(duplex=False)
+        scheduler_pipe_readers = [reader]
+        proc = mp.Process(
+            target=run_data_parallel_controller_process,
+            args=(server_args, port_args, writer),
+        )
+        proc.start()
+        scheduler_procs.append(proc)
+
+    if server_args.node_rank >= 1:
+        # In multi-node cases, non-zero rank nodes do not need to run tokenizer or detokenizer,
+        # so they can just wait here.
+
+        for reader in scheduler_pipe_readers:
+            data = reader.recv()
+            assert data["status"] == "ready"
+
+        if os.getenv("SGLANG_BLOCK_NONZERO_RANK_CHILDREN") == "0":
+            # When using `Engine` as a Python API, we don't want to block here.
+            return None, None
+
+        launch_dummy_health_check_server(server_args.host, server_args.port)
+
+        for proc in scheduler_procs:
+            proc.join()
+            logger.error(
+                f"Scheduler or DataParallelController {proc.pid} terminated with {proc.exitcode}"
+            )
+        return None, None
+
+    # Launch detokenizer process
+    detoken_proc = mp.Process(
+        target=run_detokenizer_process,
+        args=(
+            server_args,
+            port_args,
+        ),
+    )
+    detoken_proc.start()
+
+    # Launch tokenizer process
+    tokenizer_manager = TokenizerManager(server_args, port_args)
+    if server_args.chat_template:
+        load_chat_template_for_openai_api(
+            tokenizer_manager, server_args.chat_template, server_args.model_path
+        )
+
+    if server_args.completion_template:
+        load_completion_template_for_openai_api(server_args.completion_template)
+
+    # Wait for the model to finish loading
+    scheduler_infos = []
+    for i in range(len(scheduler_pipe_readers)):
+        try:
+            data = scheduler_pipe_readers[i].recv()
+        except EOFError:
+            logger.error(
+                f"Rank {i} scheduler is dead. Please check if there are relevant logs."
+            )
+            scheduler_procs[i].join()
+            logger.error(f"Exit code: {scheduler_procs[i].exitcode}")
+            raise
+
+        if data["status"] != "ready":
+            raise RuntimeError(
+                "Initialization failed. Please see the error messages above."
+            )
+        scheduler_infos.append(data)
+
+    # Assume all schedulers have the same scheduler_info
+    scheduler_info = scheduler_infos[0]
+    tokenizer_manager.max_req_input_len = scheduler_info["max_req_input_len"]
+    return tokenizer_manager, scheduler_info
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server.py b/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server.py
new file mode 100644
index 0000000000000000000000000000000000000000..147ab4131520b268e2449d3da7b1972097ba5bde
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server.py
@@ -0,0 +1,873 @@
+# Copyright 2023-2024 SGLang Team
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""
+The entry point of inference server. (SRT = SGLang Runtime)
+
+This file implements HTTP APIs for the inference engine via fastapi.
+"""
+
+import asyncio
+import dataclasses
+import json
+import logging
+import multiprocessing as multiprocessing
+import os
+import threading
+import time
+from http import HTTPStatus
+from typing import AsyncIterator, Callable, Dict, Optional
+
+# Fix a bug of Python threading
+setattr(threading, "_register_atexit", lambda *args, **kwargs: None)
+
+from contextlib import asynccontextmanager
+
+import numpy as np
+import orjson
+import requests
+import uvicorn
+import uvloop
+from fastapi import FastAPI, File, Form, Request, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import ORJSONResponse, Response, StreamingResponse
+
+from sglang.srt.disaggregation.utils import FakeBootstrapHost
+from sglang.srt.entrypoints.engine import _launch_subprocesses
+from sglang.srt.function_call_parser import FunctionCallParser
+from sglang.srt.managers.io_struct import (
+    CloseSessionReqInput,
+    ConfigureLoggingReq,
+    EmbeddingReqInput,
+    GenerateReqInput,
+    GetWeightsByNameReqInput,
+    InitWeightsUpdateGroupReqInput,
+    OpenSessionReqInput,
+    ParseFunctionCallReq,
+    ProfileReqInput,
+    ReleaseMemoryOccupationReqInput,
+    ResumeMemoryOccupationReqInput,
+    SeparateReasoningReqInput,
+    SetInternalStateReq,
+    UpdateWeightFromDiskReqInput,
+    UpdateWeightsFromDistributedReqInput,
+    UpdateWeightsFromTensorReqInput,
+    VertexGenerateReqInput,
+)
+from sglang.srt.managers.tokenizer_manager import TokenizerManager
+from sglang.srt.metrics.func_timer import enable_func_timer
+from sglang.srt.openai_api.adapter import (
+    v1_batches,
+    v1_cancel_batch,
+    v1_chat_completions,
+    v1_completions,
+    v1_delete_file,
+    v1_embeddings,
+    v1_files_create,
+    v1_retrieve_batch,
+    v1_retrieve_file,
+    v1_retrieve_file_content,
+)
+from sglang.srt.openai_api.protocol import ModelCard, ModelList
+from sglang.srt.reasoning_parser import ReasoningParser
+from sglang.srt.server_args import ServerArgs
+from sglang.srt.utils import (
+    add_api_key_middleware,
+    add_prometheus_middleware,
+    delete_directory,
+    get_bool_env_var,
+    kill_process_tree,
+    set_uvicorn_logging_configs,
+)
+from sglang.srt.warmup import execute_warmups
+from sglang.utils import get_exception_traceback
+from sglang.version import __version__
+
+logger = logging.getLogger(__name__)
+asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+
+
+# Store global states
+@dataclasses.dataclass
+class _GlobalState:
+    tokenizer_manager: TokenizerManager
+    scheduler_info: Dict
+
+
+_global_state: Optional[_GlobalState] = None
+
+
+def set_global_state(global_state: _GlobalState):
+    global _global_state
+    _global_state = global_state
+
+
+@asynccontextmanager
+async def lifespan(fast_api_app: FastAPI):
+    server_args: ServerArgs = fast_api_app.server_args
+    if server_args.warmups is not None:
+        await execute_warmups(
+            server_args.warmups.split(","), _global_state.tokenizer_manager
+        )
+        logger.info("Warmup ended")
+
+    warmup_thread = getattr(fast_api_app, "warmup_thread", None)
+    if warmup_thread is not None:
+        warmup_thread.start()
+    yield
+
+
+# Fast API
+app = FastAPI(
+    lifespan=lifespan,
+    openapi_url=None if get_bool_env_var("DISABLE_OPENAPI_DOC") else "/openapi.json",
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+HEALTH_CHECK_TIMEOUT = int(os.getenv("SGLANG_HEALTH_CHECK_TIMEOUT", 20))
+
+
+##### Native API endpoints #####
+
+
+@app.get("/health")
+async def health() -> Response:
+    """Check the health of the http server."""
+    return Response(status_code=200)
+
+
+@app.get("/health_generate")
+async def health_generate(request: Request) -> Response:
+    """Check the health of the inference server by generating one token."""
+
+    sampling_params = {"max_new_tokens": 1, "temperature": 0.0}
+    rid = f"HEALTH_CHECK_{time.time()}"
+
+    if _global_state.tokenizer_manager.is_image_gen:
+        raise NotImplementedError()
+    elif _global_state.tokenizer_manager.is_generation:
+        gri = GenerateReqInput(
+            rid=rid,
+            input_ids=[0],
+            sampling_params=sampling_params,
+            log_metrics=False,
+        )
+    else:
+        gri = EmbeddingReqInput(
+            rid=rid, input_ids=[0], sampling_params=sampling_params, log_metrics=False
+        )
+
+    async def gen():
+        async for _ in _global_state.tokenizer_manager.generate_request(gri, request):
+            break
+
+    tic = time.time()
+    task = asyncio.create_task(gen())
+    while time.time() < tic + HEALTH_CHECK_TIMEOUT:
+        await asyncio.sleep(1)
+        if _global_state.tokenizer_manager.last_receive_tstamp > tic:
+            task.cancel()
+            _global_state.tokenizer_manager.rid_to_state.pop(rid, None)
+            return Response(status_code=200)
+
+    task.cancel()
+    tic_time = time.strftime("%H:%M:%S", time.localtime(tic))
+    last_receive_time = time.strftime(
+        "%H:%M:%S", time.localtime(_global_state.tokenizer_manager.last_receive_tstamp)
+    )
+    logger.error(
+        f"Health check failed. Server couldn't get a response from detokenizer for last "
+        f"{HEALTH_CHECK_TIMEOUT} seconds. tic start time: {tic_time}. "
+        f"last_heartbeat time: {last_receive_time}"
+    )
+    _global_state.tokenizer_manager.rid_to_state.pop(rid, None)
+    return Response(status_code=503)
+
+
+@app.get("/get_model_info")
+async def get_model_info():
+    """Get the model information."""
+    result = {
+        "model_path": _global_state.tokenizer_manager.model_path,
+        "tokenizer_path": _global_state.tokenizer_manager.server_args.tokenizer_path,
+        "is_generation": _global_state.tokenizer_manager.is_generation,
+    }
+    return result
+
+
+@app.get("/get_server_info")
+async def get_server_info():
+    internal_states = await _global_state.tokenizer_manager.get_internal_state()
+    return {
+        **dataclasses.asdict(_global_state.tokenizer_manager.server_args),
+        **_global_state.scheduler_info,
+        **internal_states,
+        "version": __version__,
+    }
+
+
+@app.api_route("/set_internal_state", methods=["POST", "PUT"])
+async def set_internal_state(obj: SetInternalStateReq, request: Request):
+    res = await _global_state.tokenizer_manager.set_internal_state(obj)
+    return res
+
+
+# fastapi implicitly converts json in the request to obj (dataclass)
+@app.api_route("/generate", methods=["POST", "PUT"])
+async def generate_request(obj: GenerateReqInput, request: Request):
+    """Handle a generate request."""
+    if obj.stream:
+
+        async def stream_results() -> AsyncIterator[bytes]:
+            try:
+                async for out in _global_state.tokenizer_manager.generate_request(
+                    obj, request
+                ):
+                    yield b"data: " + orjson.dumps(
+                        out, option=orjson.OPT_NON_STR_KEYS
+                    ) + b"\n\n"
+            except ValueError as e:
+                out = {"error": {"message": str(e)}}
+                logger.error(f"Error: {e}")
+                yield b"data: " + orjson.dumps(
+                    out, option=orjson.OPT_NON_STR_KEYS
+                ) + b"\n\n"
+            yield b"data: [DONE]\n\n"
+
+        return StreamingResponse(
+            stream_results(),
+            media_type="text/event-stream",
+            background=_global_state.tokenizer_manager.create_abort_task(obj),
+        )
+    else:
+        try:
+            ret = await _global_state.tokenizer_manager.generate_request(
+                obj, request
+            ).__anext__()
+            return ret
+        except ValueError as e:
+            logger.error(f"Error: {e}")
+            return _create_error_response(e)
+
+
+@app.api_route("/generate_from_file", methods=["POST"])
+async def generate_from_file_request(file: UploadFile, request: Request):
+    """Handle a generate request, this is purely to work with input_embeds."""
+    content = await file.read()
+    input_embeds = json.loads(content.decode("utf-8"))
+
+    obj = GenerateReqInput(
+        input_embeds=input_embeds,
+        sampling_params={
+            "repetition_penalty": 1.2,
+            "temperature": 0.2,
+            "max_new_tokens": 512,
+        },
+    )
+
+    try:
+        ret = await _global_state.tokenizer_manager.generate_request(
+            obj, request
+        ).__anext__()
+        return ret
+    except ValueError as e:
+        logger.error(f"Error: {e}")
+        return _create_error_response(e)
+
+
+@app.api_route("/encode", methods=["POST", "PUT"])
+async def encode_request(obj: EmbeddingReqInput, request: Request):
+    """Handle an embedding request."""
+    try:
+        ret = await _global_state.tokenizer_manager.generate_request(
+            obj, request
+        ).__anext__()
+        return ret
+    except ValueError as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/classify", methods=["POST", "PUT"])
+async def classify_request(obj: EmbeddingReqInput, request: Request):
+    """Handle a reward model request. Now the arguments and return values are the same as embedding models."""
+    try:
+        ret = await _global_state.tokenizer_manager.generate_request(
+            obj, request
+        ).__anext__()
+        return ret
+    except ValueError as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/flush_cache", methods=["GET", "POST"])
+async def flush_cache():
+    """Flush the radix cache."""
+    ret = await _global_state.tokenizer_manager.flush_cache()
+    return Response(
+        content="Cache flushed.\nPlease check backend logs for more details. "
+        "(When there are running or waiting requests, the operation will not be performed.)\n",
+        status_code=200 if ret.success else HTTPStatus.BAD_REQUEST,
+    )
+
+
+@app.api_route("/start_profile", methods=["GET", "POST"])
+async def start_profile_async(obj: Optional[ProfileReqInput] = None):
+    """Start profiling."""
+    if obj is None:
+        obj = ProfileReqInput()
+
+    await _global_state.tokenizer_manager.start_profile(
+        obj.output_dir, obj.num_steps, obj.activities
+    )
+    return Response(
+        content="Start profiling.\n",
+        status_code=200,
+    )
+
+
+@app.api_route("/stop_profile", methods=["GET", "POST"])
+async def stop_profile_async():
+    """Stop profiling."""
+    _global_state.tokenizer_manager.stop_profile()
+    return Response(
+        content="Stop profiling. This will take some time.\n",
+        status_code=200,
+    )
+
+
+@app.api_route("/start_expert_distribution_record", methods=["GET", "POST"])
+async def start_expert_distribution_record_async():
+    """Start recording the expert distribution. Clear the previous record if any."""
+    await _global_state.tokenizer_manager.start_expert_distribution_record()
+    return Response(
+        content="Start recording the expert distribution.\n",
+        status_code=200,
+    )
+
+
+@app.api_route("/stop_expert_distribution_record", methods=["GET", "POST"])
+async def stop_expert_distribution_record_async():
+    """Stop recording the expert distribution."""
+    await _global_state.tokenizer_manager.stop_expert_distribution_record()
+    return Response(
+        content="Stop recording the expert distribution.\n",
+        status_code=200,
+    )
+
+
+@app.api_route("/dump_expert_distribution_record", methods=["GET", "POST"])
+async def dump_expert_distribution_record_async():
+    """Dump expert distribution record."""
+    await _global_state.tokenizer_manager.dump_expert_distribution_record()
+    return Response(
+        content="Dump expert distribution record.\n",
+        status_code=200,
+    )
+
+
+@app.post("/update_weights_from_disk")
+async def update_weights_from_disk(obj: UpdateWeightFromDiskReqInput, request: Request):
+    """Update the weights from disk inplace without re-launching the server."""
+    success, message, num_paused_requests = (
+        await _global_state.tokenizer_manager.update_weights_from_disk(obj, request)
+    )
+    content = {
+        "success": success,
+        "message": message,
+        "num_paused_requests": num_paused_requests,
+    }
+    if success:
+        return ORJSONResponse(
+            content,
+            status_code=HTTPStatus.OK,
+        )
+    else:
+        return ORJSONResponse(
+            content,
+            status_code=HTTPStatus.BAD_REQUEST,
+        )
+
+
+@app.post("/init_weights_update_group")
+async def init_weights_update_group(
+    obj: InitWeightsUpdateGroupReqInput, request: Request
+):
+    """Initialize the parameter update group."""
+    success, message = await _global_state.tokenizer_manager.init_weights_update_group(
+        obj, request
+    )
+    content = {"success": success, "message": message}
+    if success:
+        return ORJSONResponse(content, status_code=200)
+    else:
+        return ORJSONResponse(content, status_code=HTTPStatus.BAD_REQUEST)
+
+
+@app.post("/update_weights_from_tensor")
+async def update_weights_from_tensor(
+    obj: UpdateWeightsFromTensorReqInput, request: Request
+):
+    """Update the weights from tensor inplace without re-launching the server.
+    Notes:
+    1. Ensure that the model is on the correct device (e.g., GPU) before calling this endpoint. If the model is moved to the CPU unexpectedly, it may cause performance issues or runtime errors.
+    2. HTTP will transmit only the metadata of the tensor, while the tensor itself will be directly copied to the model.
+    3. Any binary data in the named tensors should be base64 encoded.
+    """
+
+    success, message = await _global_state.tokenizer_manager.update_weights_from_tensor(
+        obj, request
+    )
+    content = {"success": success, "message": message}
+    return ORJSONResponse(
+        content, status_code=200 if success else HTTPStatus.BAD_REQUEST
+    )
+
+
+@app.post("/update_weights_from_distributed")
+async def update_weights_from_distributed(
+    obj: UpdateWeightsFromDistributedReqInput, request: Request
+):
+    """Update model parameter from distributed online."""
+    success, message = (
+        await _global_state.tokenizer_manager.update_weights_from_distributed(
+            obj, request
+        )
+    )
+    content = {"success": success, "message": message}
+    if success:
+        return ORJSONResponse(content, status_code=200)
+    else:
+        return ORJSONResponse(content, status_code=HTTPStatus.BAD_REQUEST)
+
+
+@app.api_route("/get_weights_by_name", methods=["GET", "POST"])
+async def get_weights_by_name(obj: GetWeightsByNameReqInput, request: Request):
+    """Get model parameter by name."""
+    try:
+        ret = await _global_state.tokenizer_manager.get_weights_by_name(obj, request)
+        if ret is None:
+            return _create_error_response("Get parameter by name failed")
+        else:
+            return ORJSONResponse(ret, status_code=200)
+    except Exception as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/release_memory_occupation", methods=["GET", "POST"])
+async def release_memory_occupation(
+    obj: ReleaseMemoryOccupationReqInput, request: Request
+):
+    """Release GPU memory occupation temporarily."""
+    try:
+        await _global_state.tokenizer_manager.release_memory_occupation(obj, request)
+    except Exception as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/resume_memory_occupation", methods=["GET", "POST"])
+async def resume_memory_occupation(
+    obj: ResumeMemoryOccupationReqInput, request: Request
+):
+    """Resume GPU memory occupation."""
+    try:
+        await _global_state.tokenizer_manager.resume_memory_occupation(obj, request)
+    except Exception as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/open_session", methods=["GET", "POST"])
+async def open_session(obj: OpenSessionReqInput, request: Request):
+    """Open a session, and return its unique session id."""
+    try:
+        session_id = await _global_state.tokenizer_manager.open_session(obj, request)
+        if session_id is None:
+            raise Exception(
+                "Failed to open the session. Check if a session with the same id is still open."
+            )
+        return session_id
+    except Exception as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/close_session", methods=["GET", "POST"])
+async def close_session(obj: CloseSessionReqInput, request: Request):
+    """Close the session."""
+    try:
+        await _global_state.tokenizer_manager.close_session(obj, request)
+        return Response(status_code=200)
+    except Exception as e:
+        return _create_error_response(e)
+
+
+@app.api_route("/configure_logging", methods=["GET", "POST"])
+async def configure_logging(obj: ConfigureLoggingReq, request: Request):
+    """Configure the request logging options."""
+    _global_state.tokenizer_manager.configure_logging(obj)
+    return Response(status_code=200)
+
+
+@app.post("/parse_function_call")
+async def parse_function_call_request(obj: ParseFunctionCallReq, request: Request):
+    """
+    A native API endpoint to parse function calls from a text.
+    """
+    # 1) Initialize the parser based on the request body
+    parser = FunctionCallParser(tools=obj.tools, tool_call_parser=obj.tool_call_parser)
+
+    # 2) Call the non-stream parsing method (non-stream)
+    normal_text, calls = parser.parse_non_stream(obj.text)
+
+    # 3) Organize the response content
+    response_data = {
+        "normal_text": normal_text,
+        "calls": [
+            call.model_dump() for call in calls
+        ],  # Convert pydantic objects to dictionaries
+    }
+
+    return ORJSONResponse(content=response_data, status_code=200)
+
+
+@app.post("/separate_reasoning")
+async def separate_reasoning_request(obj: SeparateReasoningReqInput, request: Request):
+    """
+    A native API endpoint to separate reasoning from a text.
+    """
+    # 1) Initialize the parser based on the request body
+    parser = ReasoningParser(model_type=obj.reasoning_parser)
+
+    # 2) Call the non-stream parsing method (non-stream)
+    reasoning_text, normal_text = parser.parse_non_stream(obj.text)
+
+    # 3) Organize the response content
+    response_data = {
+        "reasoning_text": reasoning_text,
+        "text": normal_text,
+    }
+
+    return ORJSONResponse(content=response_data, status_code=200)
+
+
+##### OpenAI-compatible API endpoints #####
+
+
+@app.post("/v1/completions")
+async def openai_v1_completions(raw_request: Request):
+    return await v1_completions(_global_state.tokenizer_manager, raw_request)
+
+
+@app.post("/v1/chat/completions")
+async def openai_v1_chat_completions(raw_request: Request):
+    return await v1_chat_completions(_global_state.tokenizer_manager, raw_request)
+
+
+@app.post("/v1/embeddings", response_class=ORJSONResponse)
+async def openai_v1_embeddings(raw_request: Request):
+    response = await v1_embeddings(_global_state.tokenizer_manager, raw_request)
+    return response
+
+
+@app.get("/v1/models", response_class=ORJSONResponse)
+def available_models():
+    """Show available models."""
+    served_model_names = [_global_state.tokenizer_manager.served_model_name]
+    model_cards = []
+    for served_model_name in served_model_names:
+        model_cards.append(
+            ModelCard(
+                id=served_model_name,
+                root=served_model_name,
+                max_model_len=_global_state.tokenizer_manager.model_config.context_len,
+            )
+        )
+    return ModelList(data=model_cards)
+
+
+@app.post("/v1/files")
+async def openai_v1_files(file: UploadFile = File(...), purpose: str = Form("batch")):
+    return await v1_files_create(
+        file, purpose, _global_state.tokenizer_manager.server_args.file_storage_path
+    )
+
+
+@app.delete("/v1/files/{file_id}")
+async def delete_file(file_id: str):
+    # https://platform.openai.com/docs/api-reference/files/delete
+    return await v1_delete_file(file_id)
+
+
+@app.post("/v1/batches")
+async def openai_v1_batches(raw_request: Request):
+    return await v1_batches(_global_state.tokenizer_manager, raw_request)
+
+
+@app.post("/v1/batches/{batch_id}/cancel")
+async def cancel_batches(batch_id: str):
+    # https://platform.openai.com/docs/api-reference/batch/cancel
+    return await v1_cancel_batch(_global_state.tokenizer_manager, batch_id)
+
+
+@app.get("/v1/batches/{batch_id}")
+async def retrieve_batch(batch_id: str):
+    return await v1_retrieve_batch(batch_id)
+
+
+@app.get("/v1/files/{file_id}")
+async def retrieve_file(file_id: str):
+    # https://platform.openai.com/docs/api-reference/files/retrieve
+    return await v1_retrieve_file(file_id)
+
+
+@app.get("/v1/files/{file_id}/content")
+async def retrieve_file_content(file_id: str):
+    # https://platform.openai.com/docs/api-reference/files/retrieve-contents
+    return await v1_retrieve_file_content(file_id)
+
+
+## SageMaker API
+@app.get("/ping")
+async def sagemaker_health() -> Response:
+    """Check the health of the http server."""
+    return Response(status_code=200)
+
+
+@app.post("/invocations")
+async def sagemaker_chat_completions(raw_request: Request):
+    return await v1_chat_completions(_global_state.tokenizer_manager, raw_request)
+
+
+## Vertex AI API
+@app.post(os.environ.get("AIP_PREDICT_ROUTE", "/vertex_generate"))
+async def vertex_generate(vertex_req: VertexGenerateReqInput, raw_request: Request):
+    if not vertex_req.instances:
+        return []
+    inputs = {}
+    for input_key in ("text", "input_ids", "input_embeds"):
+        if vertex_req.instances[0].get(input_key):
+            inputs[input_key] = [
+                instance.get(input_key) for instance in vertex_req.instances
+            ]
+            break
+    image_data = [
+        instance.get("image_data")
+        for instance in vertex_req.instances
+        if instance.get("image_data") is not None
+    ] or None
+    req = GenerateReqInput(
+        **inputs,
+        image_data=image_data,
+        **(vertex_req.parameters or {}),
+    )
+    ret = await generate_request(req, raw_request)
+    return ORJSONResponse({"predictions": ret})
+
+
+def _create_error_response(e):
+    return ORJSONResponse(
+        {"error": {"message": str(e)}}, status_code=HTTPStatus.BAD_REQUEST
+    )
+
+
+def launch_server(
+    server_args: ServerArgs,
+    pipe_finish_writer: Optional[multiprocessing.connection.Connection] = None,
+    launch_callback: Optional[Callable[[], None]] = None,
+):
+    """
+    Launch SRT (SGLang Runtime) Server.
+
+    The SRT server consists of an HTTP server and an SRT engine.
+
+    - HTTP server: A FastAPI server that routes requests to the engine.
+    - The engine consists of three components:
+        1. TokenizerManager: Tokenizes the requests and sends them to the scheduler.
+        2. Scheduler (subprocess): Receives requests from the Tokenizer Manager, schedules batches, forwards them, and sends the output tokens to the Detokenizer Manager.
+        3. DetokenizerManager (subprocess): Detokenizes the output tokens and sends the result back to the Tokenizer Manager.
+
+    Note:
+    1. The HTTP server, Engine, and TokenizerManager both run in the main process.
+    2. Inter-process communication is done through IPC (each process uses a different port) via the ZMQ library.
+    """
+    tokenizer_manager, scheduler_info = _launch_subprocesses(server_args=server_args)
+    set_global_state(
+        _GlobalState(
+            tokenizer_manager=tokenizer_manager,
+            scheduler_info=scheduler_info,
+        )
+    )
+
+    # Add api key authorization
+    if server_args.api_key:
+        add_api_key_middleware(app, server_args.api_key)
+
+    # Add prometheus middleware
+    if server_args.enable_metrics:
+        add_prometheus_middleware(app)
+        enable_func_timer()
+
+    # Send a warmup request - we will create the thread launch it
+    # in the lifespan after all other warmups have fired.
+    warmup_thread = threading.Thread(
+        target=_wait_and_warmup,
+        args=(
+            server_args,
+            pipe_finish_writer,
+            _global_state.tokenizer_manager.image_token_id,
+            launch_callback,
+        ),
+    )
+    app.warmup_thread = warmup_thread
+
+    try:
+        # Update logging configs
+        set_uvicorn_logging_configs()
+        app.server_args = server_args
+        # Listen for HTTP requests
+        uvicorn.run(
+            app,
+            host=server_args.host,
+            port=server_args.port,
+            log_level=server_args.log_level_http or server_args.log_level,
+            timeout_keep_alive=5,
+            loop="uvloop",
+        )
+    finally:
+        warmup_thread.join()
+
+
+def _wait_and_warmup(
+    server_args: ServerArgs,
+    pipe_finish_writer: Optional[multiprocessing.connection.Connection],
+    image_token_text: str,
+    launch_callback: Optional[Callable[[], None]] = None,
+):
+    headers = {}
+    url = server_args.url()
+    if server_args.api_key:
+        headers["Authorization"] = f"Bearer {server_args.api_key}"
+
+    # Wait until the server is launched
+    success = False
+    for _ in range(120):
+        time.sleep(1)
+        try:
+            res = requests.get(url + "/get_model_info", timeout=5, headers=headers)
+            assert res.status_code == 200, f"{res=}, {res.text=}"
+            success = True
+            break
+        except (AssertionError, requests.exceptions.RequestException):
+            last_traceback = get_exception_traceback()
+            pass
+
+    if not success:
+        if pipe_finish_writer is not None:
+            pipe_finish_writer.send(last_traceback)
+        logger.error(f"Initialization failed. warmup error: {last_traceback}")
+        kill_process_tree(os.getpid())
+        return
+
+    model_info = res.json()
+
+    # Send a warmup request
+    request_name = "/generate" if model_info["is_generation"] else "/encode"
+    max_new_tokens = 8 if model_info["is_generation"] else 1
+    json_data = {
+        "sampling_params": {
+            "temperature": 0,
+            "max_new_tokens": max_new_tokens,
+        },
+    }
+    if server_args.skip_tokenizer_init:
+        json_data["input_ids"] = [[10, 11, 12] for _ in range(server_args.dp_size)]
+        # TODO Workaround the bug that embedding errors for list of size 1
+        if server_args.dp_size == 1:
+            json_data["input_ids"] = json_data["input_ids"][0]
+    else:
+        json_data["text"] = ["The capital city of France is"] * server_args.dp_size
+        # TODO Workaround the bug that embedding errors for list of size 1
+        if server_args.dp_size == 1:
+            json_data["text"] = json_data["text"][0]
+
+    # Debug dumping
+    if server_args.debug_tensor_dump_input_file:
+        json_data.pop("text", None)
+        json_data["input_ids"] = np.load(
+            server_args.debug_tensor_dump_input_file
+        ).tolist()
+        json_data["sampling_params"]["max_new_tokens"] = 0
+
+    try:
+        if server_args.disaggregation_mode == "null":
+            res = requests.post(
+                url + request_name,
+                json=json_data,
+                headers=headers,
+                timeout=600,
+            )
+            assert res.status_code == 200, f"{res}"
+        else:
+            logger.info(f"Start of prefill warmup ...")
+            json_data = {
+                "sampling_params": {
+                    "temperature": 0.0,
+                    "max_new_tokens": 8,
+                    "ignore_eos": True,
+                },
+                "bootstrap_host": [FakeBootstrapHost] * server_args.dp_size,
+                # This is a hack to ensure fake transfer is enabled during prefill warmup
+                # ensure each dp rank has a unique bootstrap_room during prefill warmup
+                "bootstrap_room": [
+                    i * (2**63 // server_args.dp_size) + (i % server_args.tp_size)
+                    for i in range(server_args.dp_size)
+                ],
+                "input_ids": [[0, 1, 2, 3]] * server_args.dp_size,
+            }
+            res = requests.post(
+                url + request_name,
+                json=json_data,
+                headers=headers,
+                timeout=1800,  # because of deep gemm precache is very long if not precache.
+            )
+            logger.info(
+                f"End of prefill warmup with status {res.status_code}, resp: {res.json()}"
+            )
+
+    except Exception:
+        last_traceback = get_exception_traceback()
+        if pipe_finish_writer is not None:
+            pipe_finish_writer.send(last_traceback)
+        logger.error(f"Initialization failed. warmup error: {last_traceback}")
+        kill_process_tree(os.getpid())
+        return
+
+    # Debug print
+    # logger.info(f"{res.json()=}")
+
+    logger.info("The server is fired up and ready to roll!")
+    if pipe_finish_writer is not None:
+        pipe_finish_writer.send("ready")
+
+    if server_args.delete_ckpt_after_loading:
+        delete_directory(server_args.model_path)
+
+    if server_args.debug_tensor_dump_input_file:
+        kill_process_tree(os.getpid())
+
+    if launch_callback is not None:
+        launch_callback()
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server_engine.py b/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server_engine.py
new file mode 100644
index 0000000000000000000000000000000000000000..f4d81a417d773045f07da2a03e11454ef8cd18e9
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/entrypoints/http_server_engine.py
@@ -0,0 +1,142 @@
+import base64
+import copy
+import dataclasses
+import multiprocessing
+import pickle
+import threading
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import requests
+import torch
+import torch.distributed as dist
+
+from sglang.srt.entrypoints.EngineBase import EngineBase
+from sglang.srt.entrypoints.http_server import launch_server
+from sglang.srt.server_args import ServerArgs
+from sglang.srt.utils import MultiprocessingSerializer, kill_process_tree
+
+
+def launch_server_process(server_args: ServerArgs) -> multiprocessing.Process:
+
+    p = multiprocessing.Process(target=launch_server, args=(server_args,))
+    p.start()
+
+    base_url = server_args.url()
+    timeout = 300.0  # Increased timeout to 5 minutes for downloading large models
+    start_time = time.time()
+
+    with requests.Session() as session:
+        while time.time() - start_time < timeout:
+            try:
+                headers = {
+                    "Content-Type": "application/json; charset=utf-8",
+                    "Authorization": f"Bearer {server_args.api_key}",
+                }
+                response = session.get(f"{base_url}/health_generate", headers=headers)
+                if response.status_code == 200:
+                    return p
+            except requests.RequestException:
+                pass
+
+            if not p.is_alive():
+                raise Exception("Server process terminated unexpectedly.")
+
+            time.sleep(2)
+
+    p.terminate()
+    raise TimeoutError("Server failed to start within the timeout period.")
+
+
+class HttpServerEngineAdapter(EngineBase):
+    """
+    You can use this class to launch a server from a VerlEngine instance.
+    We recommend using this class only you need to use http server.
+    Otherwise, you can use Engine directly.
+    """
+
+    def __init__(self, **kwargs):
+        self.server_args = ServerArgs(**kwargs)
+        print(
+            f"Launch HttpServerEngineAdapter at: {self.server_args.host}:{self.server_args.port}"
+        )
+        self.process = launch_server_process(self.server_args)
+
+    def _make_request(self, endpoint: str, payload: Optional[dict] = None):
+        """Make a POST request to the specified endpoint with the given payload.
+
+        Args:
+            endpoint: The API endpoint to call
+            payload: The JSON payload to send (default: empty dict)
+
+        Returns:
+            The JSON response from the server
+        """
+        url = f"http://{self.server_args.host}:{self.server_args.port}/{endpoint}"
+        response = requests.post(url, json=payload or {})
+        response.raise_for_status()
+        return response.json()
+
+    def update_weights_from_tensor(
+        self,
+        named_tensors: List[Tuple[str, torch.Tensor]],
+        load_format: Optional[str] = None,
+        flush_cache: bool = False,
+    ):
+        """
+        Update model weights from tensor data. The HTTP server will only post meta data, and the real weights will be copied directly from GPUs.
+
+        Note: The model should be on GPUs rather than CPU for this functionality to work properly.
+        If you encounter issues, ensure your model is loaded on GPU devices rather than CPU.
+        """
+
+        return self._make_request(
+            "update_weights_from_tensor",
+            {
+                "serialized_named_tensors": [
+                    MultiprocessingSerializer.serialize(named_tensors, output_str=True)
+                    for _ in range(self.server_args.tp_size)
+                ],
+                "load_format": load_format,
+                "flush_cache": flush_cache,
+            },
+        )
+
+    def shutdown(self):
+        kill_process_tree(self.process.pid)
+
+    def generate(
+        self,
+        prompt=None,
+        sampling_params=None,
+        input_ids=None,
+        image_data=None,
+        return_logprob=False,
+        logprob_start_len=None,
+        top_logprobs_num=None,
+        token_ids_logprob=None,
+        lora_path=None,
+        custom_logit_processor=None,
+    ):
+        payload = {
+            "text": prompt,
+            "sampling_params": sampling_params,
+            "input_ids": input_ids,
+            "image_data": image_data,
+            "return_logprob": return_logprob,
+            "logprob_start_len": logprob_start_len,
+            "top_logprobs_num": top_logprobs_num,
+            "token_ids_logprob": token_ids_logprob,
+            "lora_path": lora_path,
+            "custom_logit_processor": custom_logit_processor,
+        }
+        # Filter out None values
+        payload = {k: v for k, v in payload.items() if v is not None}
+
+        return self._make_request("generate", payload)
+
+    def release_memory_occupation(self):
+        return self._make_request("release_memory_occupation")
+
+    def resume_memory_occupation(self):
+        return self._make_request("resume_memory_occupation")
diff --git a/lib/python3.12/site-packages/sglang/srt/entrypoints/verl_engine.py b/lib/python3.12/site-packages/sglang/srt/entrypoints/verl_engine.py
new file mode 100644
index 0000000000000000000000000000000000000000..11cb4a2468e219c1fbe50e33e54c5126ab288c6e
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/entrypoints/verl_engine.py
@@ -0,0 +1,178 @@
+# Copyright 2023-2024 SGLang Team
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+import os
+from typing import Dict, Iterable, List, Literal, Optional, Tuple, Union
+
+import torch
+import torch.distributed as dist
+from PIL.Image import Image
+from torch.distributed.tensor import DeviceMesh, DTensor
+
+from sglang.srt.entrypoints.engine import Engine
+from sglang.srt.entrypoints.http_server_engine import HttpServerEngineAdapter
+from sglang.srt.model_executor.model_runner import LocalSerializedTensor
+from sglang.srt.patch_torch import monkey_patch_torch_reductions
+from sglang.srt.utils import MultiprocessingSerializer, broadcast_pyobj
+
+
+class VerlEngine:
+    def __init__(
+        self,
+        device_mesh_cpu: DeviceMesh,
+        nnodes: int = 1,
+        backend: Literal["engine", "server"] = "engine",
+        **kwargs,
+    ):
+        monkey_patch_torch_reductions()
+        self._device_mesh_cpu = device_mesh_cpu
+        self._tp_rank = device_mesh_cpu.get_local_rank()
+        self._tp_size = device_mesh_cpu.size()
+        tp_size_per_node = self._tp_size // nnodes
+        node_rank = self._tp_rank // tp_size_per_node
+        first_rank_in_node = self._tp_rank % tp_size_per_node == 0
+
+        # Common engine keyword arguments
+        engine_kwargs = dict(
+            **kwargs, tp_size=self._tp_size, node_rank=node_rank, nnodes=nnodes
+        )
+
+        if backend == "engine":
+            if first_rank_in_node:
+                os.environ["SGLANG_BLOCK_NONZERO_RANK_CHILDREN"] = "0"
+                self._engine = Engine(**engine_kwargs)
+            else:
+                self._engine = None
+
+        elif backend == "server":
+            if self._tp_rank == 0:
+                self._engine = HttpServerEngineAdapter(**engine_kwargs)
+            else:
+                self._engine = None
+        else:
+            raise ValueError(f"Unsupported backend: {backend}")
+
+        dist.barrier(group=self._device_mesh_cpu.get_group())
+
+    def generate(
+        self,
+        # The input prompt. It can be a single prompt or a batch of prompts.
+        prompt: Optional[Union[List[str], str]] = None,
+        sampling_params: Optional[Union[List[Dict], Dict]] = None,
+        # The token ids for text; one can either specify text or input_ids.
+        input_ids: Optional[Union[List[List[int]], List[int]]] = None,
+        # The image input. It can be an image instance, file name, URL, or base64 encoded string.
+        # Can be formatted as:
+        # - Single image for a single request
+        # - List of images (one per request in a batch)
+        # - List of lists of images (multiple images per request)
+        # See also python/sglang/srt/utils.py:load_image for more details.
+        image_data: Optional[
+            Union[
+                List[List[Union[Image, str]]],
+                List[Union[Image, str]],
+                Union[Image, str],
+            ]
+        ] = None,
+        return_logprob: Optional[Union[List[bool], bool]] = False,
+        logprob_start_len: Optional[Union[List[int], int]] = None,
+        top_logprobs_num: Optional[Union[List[int], int]] = None,
+        token_ids_logprob: Optional[Union[List[List[int]], List[int]]] = None,
+        lora_path: Optional[List[Optional[str]]] = None,
+        custom_logit_processor: Optional[Union[List[str], str]] = None,
+    ) -> Dict:
+        """
+        The arguments of this function is the same as `sglang/srt/managers/io_struct.py::GenerateReqInput`.
+        Please refer to `GenerateReqInput` for the documentation.
+        """
+        if self._tp_rank == 0:
+            output = self._engine.generate(
+                prompt=prompt,
+                sampling_params=sampling_params,
+                input_ids=input_ids,
+                image_data=image_data,
+                return_logprob=return_logprob,
+                logprob_start_len=logprob_start_len,
+                top_logprobs_num=top_logprobs_num,
+                token_ids_logprob=token_ids_logprob,
+                lora_path=lora_path,
+                custom_logit_processor=custom_logit_processor,
+            )
+        else:
+            output = None
+
+        # Most naive implementation, can extract tensor and send via gloo if too slow
+        [output] = broadcast_pyobj(
+            data=[output],
+            rank=self._tp_rank,
+            dist_group=self._device_mesh_cpu.get_group(),
+            src=self._device_mesh_cpu.mesh[0].item(),
+            force_cpu_device=False,
+        )
+
+        return output
+
+    def update_weights_from_tensor(
+        self,
+        named_tensors: Iterable[Tuple[str, torch.Tensor]],
+        load_format: Optional[str] = None,
+    ):
+        # Most naive implementation, can optimize a lot if it is bottleneck
+        for tensor_index, (name, tensor) in enumerate(named_tensors):
+            serialized_tensor = MultiprocessingSerializer.serialize(
+                _preprocess_tensor_for_update_weights(tensor)
+            )
+
+            if self._tp_rank == 0:
+                gathered_serialized_tensors = [None for _ in range(self._tp_size)]
+            else:
+                gathered_serialized_tensors = None
+            dist.gather_object(
+                obj=serialized_tensor,
+                object_gather_list=gathered_serialized_tensors,
+                dst=self._device_mesh_cpu.mesh.tolist()[0],
+                group=self._device_mesh_cpu.get_group(),
+            )
+
+            if self._tp_rank == 0:
+                self._engine.update_weights_from_tensor(
+                    named_tensors=[
+                        (
+                            name,
+                            LocalSerializedTensor(values=gathered_serialized_tensors),
+                        )
+                    ],
+                    load_format=load_format,
+                    flush_cache=False,
+                )
+
+        if self._tp_rank == 0:
+            self._engine.tokenizer_manager.flush_cache()
+
+    def release_memory_occupation(self):
+        if self._tp_rank == 0:
+            self._engine.release_memory_occupation()
+
+    def resume_memory_occupation(self):
+        if self._tp_rank == 0:
+            self._engine.resume_memory_occupation()
+
+    def shutdown(self):
+        if self._engine is not None:
+            self._engine.shutdown()
+
+
+def _preprocess_tensor_for_update_weights(tensor: torch.Tensor):
+    if isinstance(tensor, DTensor):
+        return tensor.full_tensor()
+    return tensor
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/__init__.py b/lib/python3.12/site-packages/sglang/srt/model_loader/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..fa2386e3a4b79461c9e8f5c15cca110e3352f572
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/model_loader/__init__.py
@@ -0,0 +1,34 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/model_executor/model_loader/__init__.py
+
+from torch import nn
+
+from sglang.srt.configs.device_config import DeviceConfig
+from sglang.srt.configs.load_config import LoadConfig
+from sglang.srt.configs.model_config import ModelConfig
+from sglang.srt.model_loader.loader import BaseModelLoader, get_model_loader
+from sglang.srt.model_loader.utils import (
+    get_architecture_class_name,
+    get_model_architecture,
+)
+
+
+def get_model(
+    *,
+    model_config: ModelConfig,
+    load_config: LoadConfig,
+    device_config: DeviceConfig,
+) -> nn.Module:
+    loader = get_model_loader(load_config)
+    return loader.load_model(
+        model_config=model_config,
+        device_config=device_config,
+    )
+
+
+__all__ = [
+    "get_model",
+    "get_model_loader",
+    "BaseModelLoader",
+    "get_architecture_class_name",
+    "get_model_architecture",
+]
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/__init__.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/__init__.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..09d28210bfe40e8196d00d89326eeb2c90f45f16
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/__init__.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/loader.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/loader.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..052b020b41466b986c50675aa42c622a8f41762b
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/loader.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/utils.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/utils.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..4e38f7b51b440786b89e46faaad405676bc52833
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/utils.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/weight_utils.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/weight_utils.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..7f38502b8fc379d83bb8a9db385f8c1fcf348db2
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/model_loader/__pycache__/weight_utils.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/loader.py b/lib/python3.12/site-packages/sglang/srt/model_loader/loader.py
new file mode 100644
index 0000000000000000000000000000000000000000..94b02c6f57720ef3dba19c52aa80f5dba577961a
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/model_loader/loader.py
@@ -0,0 +1,1431 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.3.post1/vllm/model_executor/model_loader/loader.py
+
+# ruff: noqa: SIM117
+import collections
+import dataclasses
+import fnmatch
+import glob
+import json
+import logging
+import math
+import os
+import time
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from typing import Any, Dict, Generator, Iterable, List, Optional, Tuple, cast
+
+import huggingface_hub
+import numpy as np
+import torch
+from huggingface_hub import HfApi, hf_hub_download
+from torch import nn
+from transformers import AutoModelForCausalLM
+from transformers.utils import SAFE_WEIGHTS_INDEX_NAME
+
+from sglang.srt.configs.device_config import DeviceConfig
+from sglang.srt.configs.load_config import LoadConfig, LoadFormat
+from sglang.srt.configs.model_config import ModelConfig
+from sglang.srt.connector import (
+    ConnectorType,
+    create_remote_connector,
+    get_connector_type,
+)
+from sglang.srt.connector.utils import parse_model_name
+from sglang.srt.distributed import (
+    get_tensor_model_parallel_rank,
+    get_tensor_model_parallel_world_size,
+)
+from sglang.srt.layers.quantization.base_config import QuantizationConfig
+from sglang.srt.model_loader.utils import (
+    get_model_architecture,
+    set_default_torch_dtype,
+)
+from sglang.srt.model_loader.weight_utils import (
+    download_safetensors_index_file_from_hf,
+    download_weights_from_hf,
+    filter_duplicate_safetensors_files,
+    filter_files_not_needed_for_inference,
+    get_gguf_extra_tensor_names,
+    get_quant_config,
+    gguf_quant_weights_iterator,
+    initialize_dummy_weights,
+    np_cache_weights_iterator,
+    pt_weights_iterator,
+    safetensors_weights_iterator,
+    set_runai_streamer_env,
+)
+from sglang.srt.utils import (
+    get_bool_env_var,
+    get_device_capability,
+    is_pin_memory_available,
+    set_weight_attrs,
+)
+
+
+@contextmanager
+def device_loading_context(module: torch.nn.Module, target_device: torch.device):
+    if target_device.type == "cpu":
+        # If target is CPU, no need to move anything
+        yield module
+        return
+
+    original_device_states: Dict[str, torch.device] = {}
+
+    # Store original device states and move parameters to GPU if they're on CPU
+    for name, p in module.named_parameters():
+        if p.device.type == "cpu":
+            original_device_states[name] = p.device
+            p.data = p.data.to(target_device)
+        # Parameters already on target device are not touched
+
+    try:
+        yield module
+
+    finally:
+        # Restore parameters to their original devices, ignoring new parameters
+        pin_memory = is_pin_memory_available()
+        for name, p in module.named_parameters():
+            if name in original_device_states:
+                original_device: torch.device = original_device_states[name]
+                if original_device.type == "cpu":
+                    # `torch.empty_like` does not support `pin_memory` argument
+                    cpu_data = torch.empty_strided(
+                        size=p.data.size(),
+                        stride=p.data.stride(),
+                        dtype=p.data.dtype,
+                        layout=p.data.layout,
+                        device="cpu",
+                        pin_memory=pin_memory,
+                    )
+                    cpu_data.copy_(p.data)
+                    p.data = cpu_data
+                else:
+                    p.data = p.data.to(original_device)
+        # New parameters or parameters already on target device are untouched
+
+
+logger = logging.getLogger(__name__)
+
+
+def _get_quantization_config(
+    model_config: ModelConfig,
+    load_config: LoadConfig,
+    packed_modules_mapping: Dict[str, List[str]],
+) -> Optional[QuantizationConfig]:
+    """Get the quantization config."""
+    if model_config.quantization is not None:
+        quant_config = get_quant_config(
+            model_config, load_config, packed_modules_mapping
+        )
+        major, minor = get_device_capability()
+
+        if major is not None and minor is not None:
+            assert 0 <= minor < 10
+            capability = major * 10 + minor
+            if capability < quant_config.get_min_capability():
+                raise ValueError(
+                    f"The quantization method {model_config.quantization} "
+                    "is not supported for the current GPU. "
+                    f"Minimum capability: {quant_config.get_min_capability()}. "
+                    f"Current capability: {capability}."
+                )
+        supported_dtypes = quant_config.get_supported_act_dtypes()
+        if model_config.dtype not in supported_dtypes:
+            raise ValueError(
+                f"{model_config.dtype} is not supported for quantization "
+                f"method {model_config.quantization}. Supported dtypes: "
+                f"{supported_dtypes}"
+            )
+        return quant_config
+    return None
+
+
+def _initialize_model(
+    model_config: ModelConfig,
+    load_config: LoadConfig,
+) -> nn.Module:
+    """Initialize a model with the given configurations."""
+    model_class, _ = get_model_architecture(model_config)
+    packed_modules_mapping = getattr(model_class, "packed_modules_mapping", {})
+    quant_config = _get_quantization_config(
+        model_config, load_config, packed_modules_mapping
+    )
+    return model_class(
+        config=model_config.hf_config,
+        quant_config=quant_config,
+    )
+
+
+class BaseModelLoader(ABC):
+    """Base class for model loaders."""
+
+    def __init__(self, load_config: LoadConfig):
+        self.load_config = load_config
+
+    @abstractmethod
+    def download_model(self, model_config: ModelConfig) -> None:
+        """Download a model so that it can be immediately loaded."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        """Load a model with the given configurations."""
+        raise NotImplementedError
+
+
+class DefaultModelLoader(BaseModelLoader):
+    """Model loader that can load different file types from disk."""
+
+    @dataclasses.dataclass
+    class Source:
+        """A source for weights."""
+
+        model_or_path: str
+        """The model ID or path."""
+
+        revision: Optional[str]
+        """The optional model revision."""
+
+        prefix: str = ""
+        """A prefix to prepend to all weights."""
+
+        fall_back_to_pt: bool = True
+        """Whether .pt weights can be used."""
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+        if load_config.model_loader_extra_config:
+            raise ValueError(
+                f"Model loader extra config is not supported for "
+                f"load format {load_config.load_format}"
+            )
+
+    def _maybe_download_from_modelscope(
+        self, model: str, revision: Optional[str]
+    ) -> Optional[str]:
+        """Download model from ModelScope hub if SGLANG_USE_MODELSCOPE is True.
+
+        Returns the path to the downloaded model, or None if the model is not
+        downloaded from ModelScope."""
+        if get_bool_env_var("SGLANG_USE_MODELSCOPE"):
+            # download model from ModelScope hub,
+            # lazy import so that modelscope is not required for normal use.
+            # pylint: disable=C.
+            from modelscope.hub.snapshot_download import snapshot_download
+
+            if not os.path.exists(model):
+                model_path = snapshot_download(
+                    model_id=model,
+                    cache_dir=self.load_config.download_dir,
+                    local_files_only=huggingface_hub.constants.HF_HUB_OFFLINE,
+                    revision=revision,
+                    ignore_file_pattern=self.load_config.ignore_patterns,
+                )
+            else:
+                model_path = model
+            return model_path
+        return None
+
+    def _prepare_weights(
+        self, model_name_or_path: str, revision: Optional[str], fall_back_to_pt: bool
+    ) -> Tuple[str, List[str], bool]:
+        """Prepare weights for the model.
+
+        If the model is not local, it will be downloaded."""
+        model_name_or_path = (
+            self._maybe_download_from_modelscope(model_name_or_path, revision)
+            or model_name_or_path
+        )
+
+        is_local = os.path.isdir(model_name_or_path)
+        load_format = self.load_config.load_format
+        use_safetensors = False
+        index_file = SAFE_WEIGHTS_INDEX_NAME
+        # Some quantized models use .pt files for storing the weights.
+        if load_format == LoadFormat.AUTO:
+            allow_patterns = ["*.safetensors", "*.bin"]
+        elif load_format == LoadFormat.SAFETENSORS:
+            use_safetensors = True
+            allow_patterns = ["*.safetensors"]
+        elif load_format == LoadFormat.MISTRAL:
+            use_safetensors = True
+            allow_patterns = ["consolidated*.safetensors"]
+            index_file = "consolidated.safetensors.index.json"
+        elif load_format == LoadFormat.PT:
+            allow_patterns = ["*.pt"]
+        elif load_format == LoadFormat.NPCACHE:
+            allow_patterns = ["*.bin"]
+        else:
+            raise ValueError(f"Unknown load_format: {load_format}")
+
+        if fall_back_to_pt:
+            allow_patterns += ["*.pt"]
+
+        if not is_local:
+            hf_folder = download_weights_from_hf(
+                model_name_or_path,
+                self.load_config.download_dir,
+                allow_patterns,
+                revision,
+                ignore_patterns=self.load_config.ignore_patterns,
+            )
+        else:
+            hf_folder = model_name_or_path
+
+        hf_weights_files: List[str] = []
+        for pattern in allow_patterns:
+            hf_weights_files += glob.glob(os.path.join(hf_folder, pattern))
+            if len(hf_weights_files) > 0:
+                if pattern == "*.safetensors":
+                    use_safetensors = True
+                break
+
+        if use_safetensors:
+            # For models like Mistral-7B-Instruct-v0.3
+            # there are both sharded safetensors files and a consolidated
+            # safetensors file. Using both breaks.
+            # Here, we download the `model.safetensors.index.json` and filter
+            # any files not found in the index.
+            if not is_local:
+                download_safetensors_index_file_from_hf(
+                    model_name_or_path,
+                    index_file,
+                    self.load_config.download_dir,
+                    revision,
+                )
+            hf_weights_files = filter_duplicate_safetensors_files(
+                hf_weights_files, hf_folder, index_file
+            )
+        else:
+            hf_weights_files = filter_files_not_needed_for_inference(hf_weights_files)
+
+        if len(hf_weights_files) == 0:
+            raise RuntimeError(
+                f"Cannot find any model weights with `{model_name_or_path}`"
+            )
+
+        return hf_folder, hf_weights_files, use_safetensors
+
+    def _get_weights_iterator(
+        self, source: "Source"
+    ) -> Generator[Tuple[str, torch.Tensor], None, None]:
+        """Get an iterator for the model weights based on the load format."""
+        hf_folder, hf_weights_files, use_safetensors = self._prepare_weights(
+            source.model_or_path, source.revision, source.fall_back_to_pt
+        )
+        if self.load_config.load_format == LoadFormat.NPCACHE:
+            # Currently np_cache only support *.bin checkpoints
+            assert use_safetensors is False
+            weights_iterator = np_cache_weights_iterator(
+                source.model_or_path,
+                self.load_config.download_dir,
+                hf_folder,
+                hf_weights_files,
+            )
+        elif use_safetensors:
+            weights_iterator = safetensors_weights_iterator(hf_weights_files)
+        else:
+            weights_iterator = pt_weights_iterator(hf_weights_files)
+
+        # Apply the prefix.
+        return ((source.prefix + name, tensor) for (name, tensor) in weights_iterator)
+
+    def _get_all_weights(
+        self,
+        model_config: ModelConfig,
+        model: nn.Module,
+    ) -> Generator[Tuple[str, torch.Tensor], None, None]:
+
+        primary_weights = DefaultModelLoader.Source(
+            model_config.model_path,
+            model_config.revision,
+            prefix="",
+            fall_back_to_pt=getattr(model, "fall_back_to_pt_during_load", True),
+        )
+        yield from self._get_weights_iterator(primary_weights)
+
+        secondary_weights = cast(
+            Iterable[DefaultModelLoader.Source], getattr(model, "secondary_weights", ())
+        )
+        for source in secondary_weights:
+            yield from self._get_weights_iterator(source)
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        self._prepare_weights(
+            model_config.model_path, model_config.revision, fall_back_to_pt=True
+        )
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        target_device = torch.device(device_config.device)
+        with set_default_torch_dtype(model_config.dtype):
+            with target_device:
+                model = _initialize_model(
+                    model_config,
+                    self.load_config,
+                )
+
+            model.load_weights(self._get_all_weights(model_config, model))
+
+            for _, module in model.named_modules():
+                quant_method = getattr(module, "quant_method", None)
+                if quant_method is not None:
+                    # When quant methods need to process weights after loading
+                    # (for repacking, quantizing, etc), they expect parameters
+                    # to be on the global target device. This scope is for the
+                    # case where cpu offloading is used, where we will move the
+                    # parameters onto device for processing and back off after.
+                    with device_loading_context(module, target_device):
+                        quant_method.process_weights_after_loading(module)
+        return model.eval()
+
+
+class LayeredModelLoader(DefaultModelLoader):
+    """Model loader that loads weights layer by layer so that one can quantize a
+    layer before loading another to make the peak memory envelope smaller."""
+
+    def __init__(self, load_config: LoadConfig):
+        # Back to the default load format
+        load_config.load_format = LoadFormat.AUTO
+        super().__init__(load_config)
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        from sglang.srt.layers.torchao_utils import apply_torchao_config_to_model
+        from sglang.srt.managers.schedule_batch import global_server_args_dict
+
+        torchao_config = global_server_args_dict.get("torchao_config")
+        target_device = torch.device(device_config.device)
+
+        with set_default_torch_dtype(model_config.dtype):
+            # Create model on meta device
+            with torch.device("meta"):
+                model = _initialize_model(
+                    model_config,
+                    self.load_config,
+                )
+
+            # Check model's layered load support
+            if not hasattr(model, "load_weights_to_module"):
+                raise ValueError(
+                    "LayeredModelLoader requires the model to have a "
+                    "`load_weights_to_module` method. "
+                    f"{model_config.model_path} does not support it."
+                )
+
+            # Get all weights from disk
+            weights = self._get_all_weights(model_config, model)
+
+            # Helper function to recursively fill the weights of a module
+            def fill_module(module, fqn: List[str], weights):
+                """
+                fqn: list of strings representing the fully qualified name of `module`.
+                """
+                # Layer by layer
+                for name, submod in module.named_children():
+                    fill_module(submod, fqn + [name], weights)
+
+                # First materialize on target device
+                module.to_empty(device=target_device, recurse=False)
+                fqn_path = ".".join(fqn)
+                # Fill weights
+                model.load_weights_to_module(
+                    fqn_path,
+                    weights,
+                )
+                # Quantize weights if applicable
+                if torchao_config and "proj" in fqn_path:
+                    # Note: `None` here is needed to indicate no filter, see
+                    # `apply_torchao_config_to_model` for details.
+                    apply_torchao_config_to_model(module, torchao_config, None)
+
+            # Start calling on root module
+            fill_module(model, [], weights)
+
+        if torchao_config:
+            model.torchao_applied = True
+
+        return model.eval()
+
+
+class DummyModelLoader(BaseModelLoader):
+    """Model loader that will set model weights to random values."""
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+        if load_config.model_loader_extra_config:
+            raise ValueError(
+                f"Model loader extra config is not supported for "
+                f"load format {load_config.load_format}"
+            )
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        pass  # Nothing to download
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        with set_default_torch_dtype(model_config.dtype):
+            with torch.device(device_config.device):
+                model = _initialize_model(
+                    model_config,
+                    self.load_config,
+                )
+
+            for _, module in model.named_modules():
+                quant_method = getattr(module, "quant_method", None)
+                if quant_method is not None:
+                    quant_method.process_weights_after_loading(module)
+
+            # NOTE(woosuk): For accurate performance evaluation, we assign
+            # random values to the weights.
+            initialize_dummy_weights(model)
+
+            # Model weight loading consists of two stages:
+            # 1. Initial weight loading.
+            # 2. Post-processing of weights, including assigning specific member variables.
+            # For `dummy_init`, only the second stage is required.
+            if hasattr(model, "post_load_weights"):
+                model.post_load_weights()
+
+        return model.eval()
+
+
+class ShardedStateLoader(BaseModelLoader):
+    """
+    Model loader that directly loads each worker's model state dict, which
+    enables a fast load path for large tensor-parallel models where each worker
+    only needs to read its own shard rather than the entire checkpoint. See
+    `examples/runtime/engine/save_sharded_state.py` for creating a sharded checkpoint.
+    """
+
+    DEFAULT_PATTERN = "model-rank-{rank}-part-{part}.safetensors"
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+        extra_config = (
+            {}
+            if load_config.model_loader_extra_config is None
+            else load_config.model_loader_extra_config.copy()
+        )
+        self.pattern = extra_config.pop("pattern", self.DEFAULT_PATTERN)
+        if extra_config:
+            raise ValueError(
+                f"Unexpected extra config keys for load format "
+                f"{load_config.load_format}: "
+                f"{load_config.model_loader_extra_config.keys()}"
+            )
+
+    @staticmethod
+    def _filter_subtensors(tensors: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
+        """
+        Filter out all tensors that share the same memory or a subset of the
+        memory of another tensor.
+        """
+        same_storage_groups: Dict[Any, List[Tuple[str, torch.Tensor]]] = (
+            collections.defaultdict(list)
+        )
+        for key, tensor in tensors.items():
+            if tensor.numel():
+                ptr = tensor.untyped_storage().data_ptr()
+                same_storage_groups[tensor.device, ptr].append((key, tensor))
+
+        def get_end_ptr(tensor: torch.Tensor) -> int:
+            return tensor.view(-1)[-1].data_ptr() + tensor.element_size()
+
+        result: Dict[str, torch.Tensor] = {}
+        for group in same_storage_groups.values():
+            for k, t in group:
+                a, b = t.data_ptr(), get_end_ptr(t)
+                for k2, t2 in group:
+                    if not t2.is_contiguous():
+                        continue
+                    a2, b2 = t2.data_ptr(), get_end_ptr(t2)
+                    if a < a2 or b2 < b:
+                        continue
+                    if a2 < a or b < b2 or not t.is_contiguous():
+                        break  # t2 covers strictly more memory than t.
+                    if k2 < k:
+                        # Same tensors, keep the one with the smaller key.
+                        break
+                else:
+                    result[k] = t
+        return result
+
+    def _prepare_weights(self, model_name_or_path: str, revision: Optional[str]):
+        if os.path.isdir(model_name_or_path):
+            return model_name_or_path
+        else:
+            allow_patterns = ["*.safetensors"]
+            return download_weights_from_hf(
+                model_name_or_path,
+                self.load_config.download_dir,
+                allow_patterns,
+                revision,
+                ignore_patterns=self.load_config.ignore_patterns,
+            )
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        self._prepare_weights(model_config.model_path, model_config.revision)
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        from safetensors.torch import safe_open
+
+        from sglang.srt.distributed import get_tensor_model_parallel_rank
+
+        local_model_path = self._prepare_weights(
+            model_config.model_path, model_config.revision
+        )
+
+        with set_default_torch_dtype(model_config.dtype):
+            with torch.device(device_config.device):
+                model = _initialize_model(model_config, self.load_config)
+                for _, module in model.named_modules():
+                    quant_method = getattr(module, "quant_method", None)
+                    if quant_method is not None:
+                        quant_method.process_weights_after_loading(module)
+            rank = get_tensor_model_parallel_rank()
+            pattern = os.path.join(
+                local_model_path,
+                self.pattern.format(rank=rank, part="*"),
+            )
+            filepaths = glob.glob(pattern)
+            if not filepaths:
+                # TODO: support un-sharded checkpoints too
+                raise ValueError(
+                    f"Could not find checkpoint files '{pattern}', only "
+                    f"pre-sharded checkpoints are currently supported!"
+                )
+            state_dict = self._filter_subtensors(model.state_dict())
+            for path in filepaths:
+                with safe_open(path, framework="pt") as f:
+                    for key in f.keys():  # noqa: SIM118
+                        tensor = f.get_tensor(key)
+                        # If loading with LoRA enabled, additional padding may
+                        # be added to certain parameters. We only load into a
+                        # narrowed view of the parameter data.
+                        param_data = state_dict[key].data
+                        param_shape = state_dict[key].shape
+                        for dim, size in enumerate(tensor.shape):
+                            if size < param_shape[dim]:
+                                param_data = param_data.narrow(dim, 0, size)
+                        if tensor.shape != param_shape:
+                            logger.warning(
+                                "loading tensor of shape %s into "
+                                "parameter '%s' of shape %s",
+                                tensor.shape,
+                                key,
+                                param_shape,
+                            )
+                        param_data.copy_(tensor)
+                        state_dict.pop(key)
+            if state_dict:
+                raise ValueError(f"Missing keys {tuple(state_dict)} in loaded state!")
+        return model.eval()
+
+    @staticmethod
+    def save_model(
+        model: torch.nn.Module,
+        path: str,
+        pattern: Optional[str] = None,
+        max_size: Optional[int] = None,
+    ) -> None:
+        from safetensors.torch import save_file
+
+        from sglang.srt.distributed import get_tensor_model_parallel_rank
+
+        if pattern is None:
+            pattern = ShardedStateLoader.DEFAULT_PATTERN
+        rank = get_tensor_model_parallel_rank()
+        part_idx = 0
+        total_size = 0
+        state_dict = ShardedStateLoader._filter_subtensors(model.state_dict())
+        state_dict_part: Dict[str, torch.Tensor] = {}
+        for key, tensor in state_dict.items():
+            param_size = tensor.nelement() * tensor.element_size()
+            if max_size is not None and total_size + param_size > max_size:
+                filename = pattern.format(rank=rank, part=part_idx)
+                save_file(
+                    state_dict_part,
+                    os.path.join(path, filename),
+                )
+                part_idx += 1
+                total_size = 0
+                state_dict_part = {}
+            state_dict_part[key] = tensor
+            total_size += param_size
+        if len(state_dict_part) > 0:
+            filename = pattern.format(rank=rank, part=part_idx)
+            save_file(
+                state_dict_part,
+                os.path.join(path, filename),
+            )
+
+
+class BitsAndBytesModelLoader(BaseModelLoader):
+    """Model loader to load model weights with BitAndBytes quantization."""
+
+    possible_config_file_names = ["adapter_config.json"]
+
+    default_target_modules = [
+        ".gate_proj.",
+        ".down_proj.",
+        ".up_proj.",
+        ".q_proj.",
+        ".k_proj.",
+        ".v_proj.",
+        ".o_proj.",
+        ".fc1.",
+        ".fc2.",
+        ".dense.",
+        ".query_key_value.",
+        ".qkv_proj.",
+        ".dense_h_to_4h.",
+        ".dense_4h_to_h.",
+        ".out_proj.",
+    ]
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+
+        # we don't need to quantize the whole model, only the target modules
+        # that are specified in the adapter config file. If the adapter config
+        # file is not provided, we will quantize the default modules.
+        if (
+            not load_config.model_loader_extra_config
+            or "qlora_adapter_name_or_path" not in load_config.model_loader_extra_config
+        ):
+            self.target_modules = []
+            return
+
+        qlora_adapter = load_config.model_loader_extra_config[
+            "qlora_adapter_name_or_path"
+        ]
+
+        config_file_path = self._get_config_file(qlora_adapter)
+
+        with open(config_file_path, "r") as f:
+            config = json.load(f)
+            self.target_modules = config["target_modules"]
+
+    def _get_config_file(self, qlora_adapter: str) -> str:
+        is_local = os.path.isdir(qlora_adapter)
+        config_file_path = None
+        if is_local:
+            for file in self.possible_config_file_names:
+                config_file_path = os.path.join(qlora_adapter, file)
+                if os.path.exists(config_file_path):
+                    break
+        else:
+            hf_api = HfApi()
+            repo_files = hf_api.list_repo_files(repo_id=qlora_adapter)
+            for file in self.possible_config_file_names:
+                if file in repo_files:
+                    config_file_path = hf_hub_download(
+                        repo_id=qlora_adapter, filename=file
+                    )
+                    break
+
+        if not config_file_path:
+            raise ValueError(f"Cannot find adapter config file in {qlora_adapter}")
+
+        return config_file_path
+
+    def _get_weight_files(
+        self,
+        model_name_or_path: str,
+        allowed_patterns: List[str],
+        revision: Optional[str] = None,
+    ) -> Tuple[List[str], str]:
+        """Retrieve weight files. Download the files if necessary.
+
+        Return the weight files and the file pattern."""
+        is_local = os.path.isdir(model_name_or_path)
+
+        if is_local:
+            for pattern in allowed_patterns:
+                weight_files = glob.glob(os.path.join(model_name_or_path, pattern))
+                if weight_files:
+                    return weight_files, pattern
+        else:
+            hf_api = HfApi()
+            repo_files = hf_api.list_repo_files(repo_id=model_name_or_path)
+            for pattern in allowed_patterns:
+                matching_files = fnmatch.filter(repo_files, pattern)
+                if matching_files:
+                    hf_folder = download_weights_from_hf(
+                        model_name_or_path,
+                        self.load_config.download_dir,
+                        [pattern],
+                        revision,
+                        ignore_patterns=self.load_config.ignore_patterns,
+                    )
+                    return glob.glob(os.path.join(hf_folder, pattern)), pattern
+
+        raise RuntimeError(f"No model weights found in: `{model_name_or_path}`")
+
+    def _prepare_weights(
+        self, model_name_or_path: str, revision: Optional[str]
+    ) -> Tuple[List[str], bool]:
+        """Prepare weight files for the model."""
+
+        allowed_patterns = ["*.safetensors", "*.bin", "*.pt"]
+
+        hf_weights_files, matched_pattern = self._get_weight_files(
+            model_name_or_path, allowed_patterns, revision
+        )
+
+        if matched_pattern != "*.safetensors":
+            hf_weights_files = filter_files_not_needed_for_inference(hf_weights_files)
+
+        if len(hf_weights_files) == 0:
+            raise RuntimeError(
+                f"Cannot find any model weights with `{model_name_or_path}`"
+            )
+
+        return hf_weights_files, matched_pattern == "*.safetensors"
+
+    def _hf_weight_iter(self, hf_weights_files, use_safetensors: bool):
+        if use_safetensors:
+            return safetensors_weights_iterator(hf_weights_files)
+        else:
+            return pt_weights_iterator(hf_weights_files)
+
+    def _get_quantized_weights_iterator(
+        self,
+        model_name_or_path: str,
+        revision: Optional[str],
+        pre_quant: bool,
+        load_8bit: bool,
+    ) -> Tuple[Generator[Tuple[str, torch.Tensor], None, None], Dict[str, Any]]:
+        """Get an iterator to the model weights with bitsandbytes quantization,
+        as well as the quantization state dictionary."""
+
+        # only load the bitsandbytes module when needed
+        try:
+            import bitsandbytes
+
+            if bitsandbytes.__version__ < "0.44.0":
+                raise ImportError(
+                    "bitsandbytes version is wrong. Please "
+                    "install bitsandbytes>=0.44.0."
+                )
+        except ImportError as err:
+            raise ImportError(
+                "Please install bitsandbytes>=0.44.0 via "
+                "`pip install bitsandbytes>=0.44.0` to use "
+                "bitsandbytes quantizer."
+            ) from err
+
+        hf_weights_files, use_safetensors = self._prepare_weights(
+            model_name_or_path, revision
+        )
+
+        quant_state_dict: Dict[str, Any] = {}
+
+        if pre_quant:
+            if load_8bit:
+                return (
+                    self._quantized_8bit_generator(
+                        hf_weights_files, use_safetensors, quant_state_dict
+                    ),
+                    quant_state_dict,
+                )
+            else:
+                return (
+                    self._quantized_4bit_generator(
+                        hf_weights_files, use_safetensors, quant_state_dict
+                    ),
+                    quant_state_dict,
+                )
+
+        return (
+            self._unquantized_generator(
+                hf_weights_files, use_safetensors, quant_state_dict
+            ),
+            quant_state_dict,
+        )
+
+    def _is_8bit_weight_name(self, weight_name: str):
+        quantized_suffix = {".scb", ".weight_format"}
+        return any(weight_name.lower().endswith(suffix) for suffix in quantized_suffix)
+
+    def _is_4bit_weight_name(self, weight_name: str):
+        quantized_suffix = {
+            "absmax",
+            "quant_map",
+            "nested_absmax",
+            "nested_quant_map",
+            "bitsandbytes",
+        }
+        suffix = weight_name.split(".")[-1]
+        return any(q_suffix in suffix for q_suffix in quantized_suffix)
+
+    def _quantized_8bit_generator(
+        self, hf_weights_files, use_safetensors, quant_state_dict
+    ) -> Generator:
+        for weight_name, weight_tensor in self._hf_weight_iter(
+            hf_weights_files, use_safetensors
+        ):
+            if not weight_name.lower().endswith(".scb"):
+                continue
+
+            weight_key = weight_name.lower().replace(".scb", ".weight")
+            quant_state_dict[weight_key] = weight_tensor
+
+        for weight_name, weight_tensor in self._hf_weight_iter(
+            hf_weights_files, use_safetensors
+        ):
+            if self._is_8bit_weight_name(weight_name):
+                continue
+
+            if weight_name in quant_state_dict:
+                set_weight_attrs(weight_tensor, {"load_in_8bit": True})
+                yield weight_name, weight_tensor
+            else:
+                yield weight_name, weight_tensor
+
+    def _quantized_4bit_generator(
+        self, hf_weights_files, use_safetensors, quant_state_dict
+    ) -> Generator:
+        from bitsandbytes.functional import QuantState
+
+        # First iterate over all quant state weights
+        weight_iterator = self._hf_weight_iter(hf_weights_files, use_safetensors)
+        temp_state_dict = {}
+        for weight_name, weight_tensor in weight_iterator:
+            if not self._is_4bit_weight_name(weight_name):
+                continue
+            # bitsandbytes library requires
+            # weight.quant_state.bitsandbytes__* in CPU
+            if "quant_state.bitsandbytes" in weight_name:
+                temp_state_dict[weight_name] = weight_tensor.cpu().data
+            else:
+                temp_state_dict[weight_name] = weight_tensor
+
+        # Closure to parse quant_state for each prequant weight
+        def _parse_quant_state(param_name: str, temp_state_dict: Dict) -> QuantState:
+            quant_state = {}
+            for k in temp_state_dict:
+                if param_name + "." in k:
+                    quant_state[k] = temp_state_dict[k]
+
+            return QuantState.from_dict(quant_state, device="cuda")
+
+        # Second iterate over all prequant and normal weights
+        # pre quantized weights would have a quant_state
+        for weight_name, weight_tensor in self._hf_weight_iter(
+            hf_weights_files, use_safetensors
+        ):
+
+            if self._is_4bit_weight_name(weight_name):
+                continue
+
+            if (f"{weight_name}.quant_state.bitsandbytes__nf4" in temp_state_dict) or (
+                f"{weight_name}.quant_state.bitsandbytes__fp4" in temp_state_dict
+            ):
+                quant_state = _parse_quant_state(weight_name, temp_state_dict)
+                quant_state_dict[weight_name] = quant_state
+                yield weight_name, weight_tensor
+            else:
+                yield weight_name, weight_tensor
+
+    def _unquantized_generator(
+        self, hf_weights_files, use_safetensors, quant_state_dict
+    ) -> Generator:
+        from bitsandbytes.functional import quantize_4bit
+
+        tp_size = get_tensor_model_parallel_world_size()
+        tp_rank = get_tensor_model_parallel_rank()
+
+        for weight_name, weight_tensor in self._hf_weight_iter(
+            hf_weights_files, use_safetensors
+        ):
+
+            if any(
+                target_module in weight_name for target_module in self.target_modules
+            ) and weight_name.endswith(".weight"):
+                weight_name = weight_name.replace(".weight", ".qweight")
+
+                if any(
+                    module in weight_name
+                    for module in self.column_parallel_weights_modules
+                ):
+
+                    total_size = weight_tensor.size(-1)
+                    start_index = total_size // tp_size * tp_rank
+                    end_index = total_size // tp_size * (tp_rank + 1)
+                    weight_sub_tensor = weight_tensor[..., start_index:end_index]
+
+                else:
+                    total_size = weight_tensor.size(0)
+                    start_index = total_size // tp_size * tp_rank
+                    end_index = total_size // tp_size * (tp_rank + 1)
+                    weight_sub_tensor = weight_tensor[start_index:end_index, ...]
+
+                # bitsandbytes requires data in GPU
+                if weight_sub_tensor.is_cuda:
+                    loaded_weight = weight_sub_tensor
+                else:
+                    loaded_weight = weight_sub_tensor.cuda()
+
+                # remove the following after the issue is fixed:
+                # https://github.com/bitsandbytes-foundation/bitsandbytes/issues/1342
+                if loaded_weight.is_contiguous() is False:
+                    loaded_weight = loaded_weight.contiguous()
+
+                with set_default_torch_dtype(torch.float32):
+                    processed_weight, quant_state = quantize_4bit(
+                        loaded_weight, compress_statistics=True, quant_type="nf4"
+                    )
+
+                quant_state_dict[weight_name] = quant_state
+            else:
+                processed_weight = weight_tensor
+
+            yield weight_name, processed_weight
+
+    def _load_weights(self, model_config: ModelConfig, model: nn.Module) -> None:
+        if not hasattr(model, "load_weights"):
+            raise AttributeError(
+                "The required method 'load_weights' is not defined in class"
+                f" {type(model).__name__}."
+            )
+
+        if not hasattr(model, "bitsandbytes_stacked_params_mapping"):
+            raise AttributeError(
+                f"Model {type(model).__name__} does not support BitsAndBytes "
+                "quantization yet."
+            )
+
+        if len(self.target_modules) == 0:
+            if hasattr(model, "default_bitsandbytes_target_modules"):
+                self.target_modules = model.default_bitsandbytes_target_modules
+            else:
+                self.target_modules = self.default_target_modules
+
+        if hasattr(model, "column_parallel_weights_modules"):
+            self.column_parallel_weights_modules = model.column_parallel_weights_modules
+        else:
+            self.column_parallel_weights_modules = []
+
+        self.model_type = type(model).__name__
+
+        logger.info(
+            "Loading weights with BitsAndBytes quantization. " " May take a while ..."
+        )
+
+        quant_config = getattr(model_config.hf_config, "quantization_config", None)
+
+        pre_quant = False
+        if quant_config is not None:
+            quant_method = quant_config.get("quant_method")
+            if quant_method == "bitsandbytes":
+                pre_quant = True
+            else:
+                raise ValueError(
+                    f"BitsAndBytes loader does not support {quant_method} "
+                    "quantization"
+                )
+
+        # The quant_states in pre_quantized models cannot work with a split
+        # weight tensor. So TP does not work with pre_quantized bnb models.
+        if pre_quant and get_tensor_model_parallel_world_size() > 1:
+            raise ValueError(
+                "Prequant BitsAndBytes models with TP is not supported."
+                "Please try with PP."
+            )
+
+        load_8bit = False
+        if pre_quant:
+            load_8bit = quant_config.get("load_in_8bit", False)
+
+        qweight_iterator, quant_state_dict = self._get_quantized_weights_iterator(
+            model_config.model_path, model_config.revision, pre_quant, load_8bit
+        )
+
+        model.load_weights(qweight_iterator)
+
+        torch.cuda.empty_cache()
+
+        param_dict = dict(model.named_parameters())
+        stacked_quant_state_dict: Dict[str, Dict[int, Any]] = {}
+        model_type = model_config.hf_config.model_type
+        for quant_param_name in quant_state_dict:
+            non_stacked_param_name = quant_param_name
+            if model_type == "mllama" and "vision_model" in quant_param_name:
+                # adapt to VisionAttention
+                quant_param_name = quant_param_name.replace(
+                    "self_attn.o_proj", "self_attn.proj"
+                )
+            shard_index = 0
+            for shard_name, (
+                weight_name,
+                index,
+            ) in model.bitsandbytes_stacked_params_mapping.items():
+                if (
+                    model_type in ["qwen2_vl", "qwen2_5_vl"]
+                    and "visual" in quant_param_name
+                ):
+                    break
+                if shard_name in quant_param_name:
+                    shard_index = index
+                    quant_param_name = quant_param_name.replace(shard_name, weight_name)
+                    break
+
+            if (
+                model_type in ["qwen2_vl", "qwen2_5_vl"]
+                and "visual" in quant_param_name
+            ):
+                quant_param_name = quant_param_name.replace(
+                    r"attn.qkv.", r"attn.qkv_proj."
+                )
+
+            if quant_param_name not in param_dict:
+                raise ValueError(
+                    f"Parameter {quant_param_name} not found in the model."
+                )
+
+            if quant_param_name not in stacked_quant_state_dict:
+                stacked_quant_state_dict[quant_param_name] = {}
+
+            stacked_quant_state_dict[quant_param_name][shard_index] = quant_state_dict[
+                non_stacked_param_name
+            ]
+
+        # save quant_states and offsets as the attributes of the parameters
+        for param_name, param in param_dict.items():
+            if param_name in stacked_quant_state_dict:
+                quant_states = stacked_quant_state_dict[param_name]
+                set_weight_attrs(param, {"bnb_quant_state": quant_states})
+
+                pack_ratio = getattr(param, "pack_factor", -1)
+                if pack_ratio == -1:
+                    raise ValueError(f"pack_factor not set for parameter {param_name}.")
+
+                num_elements = [0] * len(quant_states)
+                for seq, quant_state in quant_states.items():
+                    num_elements[seq] = math.prod(quant_state.shape) // pack_ratio
+
+                offsets = np.concatenate(([0], np.cumsum(num_elements)))
+                # Make torch infer_schema happy(Compatible with vLLM)
+                offsets = torch.tensor(offsets).cpu()
+                set_weight_attrs(param, {"bnb_shard_offsets": offsets})
+
+                if load_8bit:
+                    set_weight_attrs(
+                        param, {"matmul_state": [None] * len(quant_states)}
+                    )
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        self._prepare_weights(model_config.model_path, model_config.revision)
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        with set_default_torch_dtype(model_config.dtype):
+            with torch.device(device_config.device):
+                model = _initialize_model(
+                    model_config,
+                    self.load_config,
+                )
+
+                self._load_weights(model_config, model)
+
+        return model.eval()
+
+
+class GGUFModelLoader(BaseModelLoader):
+    """
+    Model loader that can load GGUF files. This is useful for loading models
+    that are quantized with GGUF and saved in the GGUF format. This loader
+    supports loading both full models and sharded models.
+    """
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+        if load_config.model_loader_extra_config:
+            raise ValueError(
+                f"Model loader extra config is not supported for "
+                f"load format {load_config.load_format}"
+            )
+
+    def _prepare_weights(self, model_name_or_path: str):
+        if os.path.isfile(model_name_or_path):
+            return model_name_or_path
+        else:
+            raise ValueError(f"{model_name_or_path} is not a file.")
+
+    def _get_gguf_weights_map(self, model_config: ModelConfig):
+        """
+        GGUF uses this naming convention for their tensors from HF checkpoint:
+        `blk.N.BB.weight` and `blk.N.BB.bias`
+        where N signifies the block number of a layer, and BB signifies the
+        attention/mlp layer components.
+        See "Standardized tensor names" in
+        https://github.com/ggerganov/ggml/blob/master/docs/gguf.md for details.
+        """
+
+        # only load the gguf module when needed
+        try:
+            import gguf
+
+            # FIXME: add version check for gguf
+        except ImportError as err:
+            raise ImportError(
+                "Please install gguf via `pip install gguf` to use gguf quantizer."
+            ) from err
+
+        config = model_config.hf_config
+        model_type = config.model_type
+        # hack: ggufs have a different name than transformers
+        if model_type == "cohere":
+            model_type = "command-r"
+        arch = None
+        for key, value in gguf.MODEL_ARCH_NAMES.items():
+            if value == model_type:
+                arch = key
+                break
+        if arch is None:
+            raise RuntimeError(f"Unknown gguf model_type: {model_type}")
+        num_layers = config.num_hidden_layers
+        name_map = gguf.get_tensor_name_map(arch, num_layers)
+        with torch.device("meta"):
+            dummy_model = AutoModelForCausalLM.from_config(config)
+        state_dict = dummy_model.state_dict()
+
+        gguf_to_hf_name_map = {}
+        for hf_name in state_dict:
+            name, suffix = hf_name.rsplit(".", 1)
+            gguf_name = name_map.get_name(name)
+            gguf_to_hf_name_map[f"{gguf_name}.{suffix}"] = hf_name
+        return gguf_to_hf_name_map
+
+    def _get_weights_iterator(
+        self, model_name_or_path: str, gguf_to_hf_name_map: Dict[str, str]
+    ) -> Generator[Tuple[str, torch.Tensor], None, None]:
+        return gguf_quant_weights_iterator(model_name_or_path, gguf_to_hf_name_map)
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        self._prepare_weights(model_config.model_path)
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+
+        local_model_path = self._prepare_weights(model_config.model_path)
+        gguf_weights_map = self._get_gguf_weights_map(model_config)
+        # we can only know if tie word embeddings after mapping weights
+        if "lm_head.weight" in get_gguf_extra_tensor_names(
+            local_model_path, gguf_weights_map
+        ):
+            model_config.hf_config.update({"tie_word_embeddings": True})
+
+        with set_default_torch_dtype(model_config.dtype):
+            with torch.device(device_config.device):
+                model = _initialize_model(model_config, self.load_config)
+            model.load_weights(
+                self._get_weights_iterator(local_model_path, gguf_weights_map)
+            )
+        return model
+
+
+class RemoteModelLoader(BaseModelLoader):
+    """Model loader that can load Tensors from remote database."""
+
+    def __init__(self, load_config: LoadConfig):
+        super().__init__(load_config)
+        # TODO @DellCurry: move to s3 connector only
+        set_runai_streamer_env(load_config)
+
+    def _get_weights_iterator_kv(
+        self,
+        client,
+    ) -> Generator[Tuple[str, torch.Tensor], None, None]:
+        """Get an iterator for the model weights from remote storage."""
+        assert get_connector_type(client) == ConnectorType.KV
+        rank = get_tensor_model_parallel_rank()
+        return client.weight_iterator(rank)
+
+    def _get_weights_iterator_fs(
+        self,
+        client,
+    ) -> Generator[Tuple[str, torch.Tensor], None, None]:
+        """Get an iterator for the model weights from remote storage."""
+        assert get_connector_type(client) == ConnectorType.FS
+        return client.weight_iterator()
+
+    def download_model(self, model_config: ModelConfig) -> None:
+        pass
+
+    @staticmethod
+    def save_model(
+        model: torch.nn.Module,
+        model_path: str,
+        url: str,
+    ) -> None:
+        with create_remote_connector(url) as client:
+            assert get_connector_type(client) == ConnectorType.KV
+            model_name = parse_model_name(url)
+            rank = get_tensor_model_parallel_rank()
+            state_dict = ShardedStateLoader._filter_subtensors(model.state_dict())
+            for key, tensor in state_dict.items():
+                r_key = f"{model_name}/keys/rank_{rank}/{key}"
+                client.set(r_key, tensor)
+
+            for root, _, files in os.walk(model_path):
+                for file_name in files:
+                    # ignore hidden files
+                    if file_name.startswith("."):
+                        continue
+                    if os.path.splitext(file_name)[1] not in (
+                        ".bin",
+                        ".pt",
+                        ".safetensors",
+                    ):
+                        file_path = os.path.join(root, file_name)
+                        with open(file_path, encoding="utf-8") as file:
+                            file_content = file.read()
+                            f_key = f"{model_name}/files/{file_name}"
+                            client.setstr(f_key, file_content)
+
+    def _load_model_from_remote_kv(self, model: nn.Module, client):
+        for _, module in model.named_modules():
+            quant_method = getattr(module, "quant_method", None)
+            if quant_method is not None:
+                quant_method.process_weights_after_loading(module)
+        weights_iterator = self._get_weights_iterator_kv(client)
+        state_dict = ShardedStateLoader._filter_subtensors(model.state_dict())
+        for key, tensor in weights_iterator:
+            # If loading with LoRA enabled, additional padding may
+            # be added to certain parameters. We only load into a
+            # narrowed view of the parameter data.
+            param_data = state_dict[key].data
+            param_shape = state_dict[key].shape
+            for dim, size in enumerate(tensor.shape):
+                if size < param_shape[dim]:
+                    param_data = param_data.narrow(dim, 0, size)
+            if tensor.shape != param_shape:
+                logger.warning(
+                    "loading tensor of shape %s into " "parameter '%s' of shape %s",
+                    tensor.shape,
+                    key,
+                    param_shape,
+                )
+            param_data.copy_(tensor)
+            state_dict.pop(key)
+        if state_dict:
+            raise ValueError(f"Missing keys {tuple(state_dict)} in loaded state!")
+
+    def _load_model_from_remote_fs(
+        self, model, client, model_config: ModelConfig, device_config: DeviceConfig
+    ) -> nn.Module:
+
+        target_device = torch.device(device_config.device)
+        with set_default_torch_dtype(model_config.dtype):
+            model.load_weights(self._get_weights_iterator_fs(client))
+
+            for _, module in model.named_modules():
+                quant_method = getattr(module, "quant_method", None)
+                if quant_method is not None:
+                    # When quant methods need to process weights after loading
+                    # (for repacking, quantizing, etc), they expect parameters
+                    # to be on the global target device. This scope is for the
+                    # case where cpu offloading is used, where we will move the
+                    # parameters onto device for processing and back off after.
+                    with device_loading_context(module, target_device):
+                        quant_method.process_weights_after_loading(module)
+
+    def load_model(
+        self,
+        *,
+        model_config: ModelConfig,
+        device_config: DeviceConfig,
+    ) -> nn.Module:
+        logger.info("Loading weights from remote storage ...")
+        start = time.perf_counter()
+        load_config = self.load_config
+
+        assert load_config.load_format == LoadFormat.REMOTE, (
+            f"Model loader {self.load_config.load_format} is not supported for "
+            f"load format {load_config.load_format}"
+        )
+
+        model_weights = model_config.model_path
+        if hasattr(model_config, "model_weights"):
+            model_weights = model_config.model_weights
+
+        with set_default_torch_dtype(model_config.dtype):
+            with torch.device(device_config.device):
+                model = _initialize_model(model_config, self.load_config)
+                for _, module in model.named_modules():
+                    quant_method = getattr(module, "quant_method", None)
+                    if quant_method is not None:
+                        quant_method.process_weights_after_loading(module)
+
+            with create_remote_connector(model_weights, device_config.device) as client:
+                connector_type = get_connector_type(client)
+                if connector_type == ConnectorType.KV:
+                    self._load_model_from_remote_kv(model, client)
+                elif connector_type == ConnectorType.FS:
+                    self._load_model_from_remote_fs(
+                        model, client, model_config, device_config
+                    )
+
+        end = time.perf_counter()
+        logger.info("Loaded weights from remote storage in %.2f seconds.", end - start)
+        return model.eval()
+
+
+def get_model_loader(load_config: LoadConfig) -> BaseModelLoader:
+    """Get a model loader based on the load format."""
+
+    if isinstance(load_config.load_format, type):
+        return load_config.load_format(load_config)
+
+    if load_config.load_format == LoadFormat.DUMMY:
+        return DummyModelLoader(load_config)
+
+    if load_config.load_format == LoadFormat.SHARDED_STATE:
+        return ShardedStateLoader(load_config)
+
+    if load_config.load_format == LoadFormat.BITSANDBYTES:
+        return BitsAndBytesModelLoader(load_config)
+
+    if load_config.load_format == LoadFormat.GGUF:
+        return GGUFModelLoader(load_config)
+
+    if load_config.load_format == LoadFormat.LAYERED:
+        return LayeredModelLoader(load_config)
+
+    if load_config.load_format == LoadFormat.REMOTE:
+        return RemoteModelLoader(load_config)
+
+    return DefaultModelLoader(load_config)
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/utils.py b/lib/python3.12/site-packages/sglang/srt/model_loader/utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..daad1e67fc3020038a62374c1b6f0b8f57d1a5cb
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/model_loader/utils.py
@@ -0,0 +1,41 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/model_executor/model_loader/utils.py
+
+"""Utilities for selecting and loading models."""
+import contextlib
+from typing import Tuple, Type
+
+import torch
+from torch import nn
+
+from sglang.srt.configs.model_config import ModelConfig
+
+
+@contextlib.contextmanager
+def set_default_torch_dtype(dtype: torch.dtype):
+    """Sets the default torch dtype to the given dtype."""
+    old_dtype = torch.get_default_dtype()
+    torch.set_default_dtype(dtype)
+    yield
+    torch.set_default_dtype(old_dtype)
+
+
+def get_model_architecture(model_config: ModelConfig) -> Tuple[Type[nn.Module], str]:
+    from sglang.srt.models.registry import ModelRegistry
+
+    architectures = getattr(model_config.hf_config, "architectures", [])
+    # Special handling for quantized Mixtral.
+    # FIXME(woosuk): This is a temporary hack.
+    mixtral_supported = ["fp8", "compressed-tensors", "gptq_marlin", "awq_marlin"]
+
+    if (
+        model_config.quantization is not None
+        and model_config.quantization not in mixtral_supported
+        and "MixtralForCausalLM" in architectures
+    ):
+        architectures = ["QuantMixtralForCausalLM"]
+
+    return ModelRegistry.resolve_model_cls(architectures)
+
+
+def get_architecture_class_name(model_config: ModelConfig) -> str:
+    return get_model_architecture(model_config)[1]
diff --git a/lib/python3.12/site-packages/sglang/srt/model_loader/weight_utils.py b/lib/python3.12/site-packages/sglang/srt/model_loader/weight_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..d1c44e4f7aaa4edcbf25798d9f72881b0a87fc8e
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/model_loader/weight_utils.py
@@ -0,0 +1,851 @@
+# Adapted from https://github.com/vllm-project/vllm/blob/v0.6.4.post1/vllm/model_executor/model_loader/weight_utils.py
+
+"""Utilities for downloading and initializing model weights."""
+import fnmatch
+import glob
+import hashlib
+import json
+import logging
+import os
+import tempfile
+from collections import defaultdict
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generator,
+    Iterable,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import filelock
+import huggingface_hub.constants
+import numpy as np
+import safetensors.torch
+import torch
+from huggingface_hub import HfFileSystem, hf_hub_download, snapshot_download
+from pydantic import BaseModel, ConfigDict, ValidationInfo, model_validator
+from tqdm.auto import tqdm
+
+from sglang.srt.configs.load_config import LoadConfig
+from sglang.srt.configs.model_config import ModelConfig
+from sglang.srt.distributed import get_tensor_model_parallel_rank
+from sglang.srt.layers.quantization import QuantizationConfig, get_quantization_config
+from sglang.srt.utils import print_warning_once
+
+logger = logging.getLogger(__name__)
+
+# use system-level temp directory for file locks, so that multiple users
+# can share the same lock without error.
+# lock files in the temp directory will be automatically deleted when the
+# system reboots, so users will not complain about annoying lock files
+temp_dir = tempfile.gettempdir()
+
+
+def enable_hf_transfer():
+    """automatically activates hf_transfer"""
+    if "HF_HUB_ENABLE_HF_TRANSFER" not in os.environ:
+        try:
+            # enable hf hub transfer if available
+            import hf_transfer  # type: ignore # noqa
+
+            huggingface_hub.constants.HF_HUB_ENABLE_HF_TRANSFER = True
+        except ImportError:
+            pass
+
+
+enable_hf_transfer()
+
+
+class DisabledTqdm(tqdm):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs, disable=True)
+
+
+def get_lock(model_name_or_path: str, cache_dir: Optional[str] = None):
+    lock_dir = cache_dir or temp_dir
+    os.makedirs(os.path.dirname(lock_dir), exist_ok=True)
+    model_name = model_name_or_path.replace("/", "-")
+    hash_name = hashlib.sha256(model_name.encode()).hexdigest()
+    # add hash to avoid conflict with old users' lock files
+    lock_file_name = hash_name + model_name + ".lock"
+    # mode 0o666 is required for the filelock to be shared across users
+    lock = filelock.FileLock(os.path.join(lock_dir, lock_file_name), mode=0o666)
+    return lock
+
+
+def _shared_pointers(tensors):
+    ptrs = defaultdict(list)
+    for k, v in tensors.items():
+        ptrs[v.data_ptr()].append(k)
+    failing = []
+    for _, names in ptrs.items():
+        if len(names) > 1:
+            failing.append(names)
+    return failing
+
+
+def convert_bin_to_safetensor_file(
+    pt_filename: str,
+    sf_filename: str,
+) -> None:
+    loaded = torch.load(pt_filename, map_location="cpu", weights_only=True)
+    if "state_dict" in loaded:
+        loaded = loaded["state_dict"]
+    shared = _shared_pointers(loaded)
+    for shared_weights in shared:
+        for name in shared_weights[1:]:
+            loaded.pop(name)
+
+    # For tensors to be contiguous
+    loaded = {k: v.contiguous() for k, v in loaded.items()}
+
+    dirname = os.path.dirname(sf_filename)
+    os.makedirs(dirname, exist_ok=True)
+    save_file(loaded, sf_filename, metadata={"format": "pt"})
+
+    # check file size
+    sf_size = os.stat(sf_filename).st_size
+    pt_size = os.stat(pt_filename).st_size
+    if (sf_size - pt_size) / pt_size > 0.01:
+        raise RuntimeError(
+            f"""The file size different is more than 1%:
+         - {sf_filename}: {sf_size}
+         - {pt_filename}: {pt_size}
+         """
+        )
+
+    # check if the tensors are the same
+    reloaded = safetensors.torch.load_file(sf_filename)
+    for k in loaded:
+        pt_tensor = loaded[k]
+        sf_tensor = reloaded[k]
+        if not torch.equal(pt_tensor, sf_tensor):
+            raise RuntimeError(f"The output tensors do not match for key {k}")
+
+
+# TODO(woosuk): Move this to other place.
+def get_quant_config(
+    model_config: ModelConfig,
+    load_config: LoadConfig,
+    packed_modules_mapping: Dict[str, List[str]],
+) -> QuantizationConfig:
+    quant_cls = get_quantization_config(model_config.quantization)
+
+    # GGUF doesn't have config file
+    if model_config.quantization == "gguf":
+        return quant_cls.from_config({})
+
+    # Read the quantization config from the HF model config, if available.
+    hf_quant_config = getattr(model_config.hf_config, "quantization_config", None)
+    # some vision model may keep quantization_config in their text_config
+    hf_text_config = getattr(model_config.hf_config, "text_config", None)
+    if hf_quant_config is None and hf_text_config is not None:
+        hf_quant_config = getattr(hf_text_config, "quantization_config", None)
+    if hf_quant_config is None:
+        # compressed-tensors uses a compressions_config
+        hf_quant_config = getattr(model_config.hf_config, "compression_config", None)
+    if hf_quant_config is not None:
+        hf_quant_config["packed_modules_mapping"] = packed_modules_mapping
+        return quant_cls.from_config(hf_quant_config)
+    # In case of bitsandbytes/QLoRA, get quant config from the adapter model.
+    if model_config.quantization == "bitsandbytes":
+        if (
+            not load_config.model_loader_extra_config
+            or "qlora_adapter_name_or_path" not in load_config.model_loader_extra_config
+        ):
+            return quant_cls.from_config({"adapter_name_or_path": ""})
+        model_name_or_path = load_config.model_loader_extra_config[
+            "qlora_adapter_name_or_path"
+        ]
+
+    else:
+        model_name_or_path = model_config.model_path
+    is_local = os.path.isdir(model_name_or_path)
+    if not is_local:
+        # Download the config files.
+        with get_lock(model_name_or_path, load_config.download_dir):
+            hf_folder = snapshot_download(
+                model_name_or_path,
+                revision=model_config.revision,
+                allow_patterns="*.json",
+                cache_dir=load_config.download_dir,
+                local_files_only=huggingface_hub.constants.HF_HUB_OFFLINE,
+                tqdm_class=DisabledTqdm,
+            )
+    else:
+        hf_folder = model_name_or_path
+
+    possible_config_filenames = quant_cls.get_config_filenames()
+
+    # If the quantization config is not found, use the default config.
+    if not possible_config_filenames:
+        return quant_cls()
+
+    config_files = glob.glob(os.path.join(hf_folder, "*.json"))
+
+    quant_config_files = [
+        f for f in config_files if any(f.endswith(x) for x in possible_config_filenames)
+    ]
+    if len(quant_config_files) == 0:
+        raise ValueError(f"Cannot find the config file for {model_config.quantization}")
+    if len(quant_config_files) > 1:
+        raise ValueError(
+            f"Found multiple config files for {model_config.quantization}: "
+            f"{quant_config_files}"
+        )
+
+    quant_config_file = quant_config_files[0]
+    with open(quant_config_file) as f:
+        config = json.load(f)
+
+        if model_config.quantization == "bitsandbytes":
+            config["adapter_name_or_path"] = model_name_or_path
+        elif model_config.quantization == "modelopt":
+            if config["producer"]["name"] == "modelopt":
+                return quant_cls.from_config(config)
+            else:
+                raise ValueError(
+                    f"Unsupported quantization config"
+                    f" found for {model_config.quantization} in {f}."
+                )
+
+    return quant_cls.from_config(config)
+
+
+def download_weights_from_hf(
+    model_name_or_path: str,
+    cache_dir: Optional[str],
+    allow_patterns: List[str],
+    revision: Optional[str] = None,
+    ignore_patterns: Optional[Union[str, List[str]]] = None,
+) -> str:
+    """Download model weights from Hugging Face Hub.
+
+    Args:
+        model_name_or_path (str): The model name or path.
+        cache_dir (Optional[str]): The cache directory to store the model
+            weights. If None, will use HF defaults.
+        allow_patterns (List[str]): The allowed patterns for the
+            weight files. Files matched by any of the patterns will be
+            downloaded.
+        revision (Optional[str]): The revision of the model.
+        ignore_patterns (Optional[Union[str, List[str]]]): The patterns to
+            filter out the weight files. Files matched by any of the patterns
+            will be ignored.
+
+    Returns:
+        str: The path to the downloaded model weights.
+    """
+    if not huggingface_hub.constants.HF_HUB_OFFLINE:
+        # Before we download we look at that is available:
+        fs = HfFileSystem()
+        file_list = fs.ls(model_name_or_path, detail=False, revision=revision)
+
+        # depending on what is available we download different things
+        for pattern in allow_patterns:
+            matching = fnmatch.filter(file_list, pattern)
+            if len(matching) > 0:
+                allow_patterns = [pattern]
+                break
+
+    logger.info("Using model weights format %s", allow_patterns)
+    # Use file lock to prevent multiple processes from
+    # downloading the same model weights at the same time.
+    with get_lock(model_name_or_path, cache_dir):
+        hf_folder = snapshot_download(
+            model_name_or_path,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            cache_dir=cache_dir,
+            tqdm_class=DisabledTqdm,
+            revision=revision,
+            local_files_only=huggingface_hub.constants.HF_HUB_OFFLINE,
+        )
+    return hf_folder
+
+
+def download_safetensors_index_file_from_hf(
+    model_name_or_path: str,
+    index_file: str,
+    cache_dir: Optional[str],
+    revision: Optional[str] = None,
+) -> None:
+    """Download hf safetensors index file from Hugging Face Hub.
+
+    Args:
+        model_name_or_path (str): The model name or path.
+        cache_dir (Optional[str]): The cache directory to store the model
+            weights. If None, will use HF defaults.
+        revision (Optional[str]): The revision of the model.
+    """
+    # Use file lock to prevent multiple processes from
+    # downloading the same model weights at the same time.
+    with get_lock(model_name_or_path, cache_dir):
+        try:
+            # Download the safetensors index file.
+            hf_hub_download(
+                repo_id=model_name_or_path,
+                filename=index_file,
+                cache_dir=cache_dir,
+                revision=revision,
+                local_files_only=huggingface_hub.constants.HF_HUB_OFFLINE,
+            )
+        # If file not found on remote or locally, we should not fail since
+        # only some models will have index_file.
+        except huggingface_hub.utils.EntryNotFoundError:
+            logger.info("No %s found in remote.", index_file)
+        except huggingface_hub.utils.LocalEntryNotFoundError:
+            logger.info("No %s found in local cache.", index_file)
+
+
+# For models like Mistral-7B-v0.3, there are both sharded
+# safetensors files and a consolidated safetensors file.
+# Passing both of these to the weight loader functionality breaks.
+# So, we use the index_file to
+# look up which safetensors files should be used.
+def filter_duplicate_safetensors_files(
+    hf_weights_files: List[str], hf_folder: str, index_file: str
+) -> List[str]:
+    # model.safetensors.index.json is a mapping from keys in the
+    # torch state_dict to safetensors file holding that weight.
+    index_file_name = os.path.join(hf_folder, index_file)
+    if not os.path.isfile(index_file_name):
+        return hf_weights_files
+
+    # Iterate through the weight_map (weight_name: safetensors files)
+    # to identify weights that we should use.
+    with open(index_file_name) as f:
+        weight_map = json.load(f)["weight_map"]
+    weight_files_in_index = set()
+    for weight_name in weight_map:
+        weight_files_in_index.add(os.path.join(hf_folder, weight_map[weight_name]))
+    # Filter out any fields that are not found in the index file.
+    hf_weights_files = [f for f in hf_weights_files if f in weight_files_in_index]
+    return hf_weights_files
+
+
+def filter_files_not_needed_for_inference(hf_weights_files: List[str]) -> List[str]:
+    """
+    Exclude files that are not needed for inference.
+
+    See https://github.com/huggingface/transformers/blob/v4.34.0/src/transformers/trainer.py#L227-L233
+    """
+    blacklist = [
+        "training_args.bin",
+        "optimizer.bin",
+        "optimizer.pt",
+        "scheduler.pt",
+        "scaler.pt",
+    ]
+    hf_weights_files = [
+        f for f in hf_weights_files if not any(f.endswith(x) for x in blacklist)
+    ]
+    return hf_weights_files
+
+
+# explicitly use pure text format, with a newline at the end
+# this makes it impossible to see the animation in the progress bar
+# but will avoid messing up with ray or multiprocessing, which wraps
+# each line of output with some prefix.
+_BAR_FORMAT = "{desc}: {percentage:3.0f}% Completed | {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]\n"  # noqa: E501
+
+
+def np_cache_weights_iterator(
+    model_name_or_path: str,
+    cache_dir: Optional[str],
+    hf_folder: str,
+    hf_weights_files: List[str],
+) -> Generator[Tuple[str, torch.Tensor], None, None]:
+    """Iterate over the weights in the model np files.
+
+    Will dump the model weights to numpy files if they are not already dumped.
+    """
+    enable_tqdm = (
+        not torch.distributed.is_initialized() or torch.distributed.get_rank() == 0
+    )
+    # Convert the model weights from torch tensors to numpy arrays for
+    # faster loading.
+    np_folder = os.path.join(hf_folder, "np")
+    os.makedirs(np_folder, exist_ok=True)
+    weight_names_file = os.path.join(np_folder, "weight_names.json")
+    # Use file lock to prevent multiple processes from
+    # dumping the same model weights to numpy at the same time.
+    with get_lock(model_name_or_path, cache_dir):
+        if not os.path.exists(weight_names_file):
+            weight_names: List[str] = []
+            for bin_file in tqdm(
+                hf_weights_files,
+                desc="Loading np_cache checkpoint shards",
+                disable=not enable_tqdm,
+                bar_format=_BAR_FORMAT,
+            ):
+                state = torch.load(bin_file, map_location="cpu", weights_only=True)
+                for name, param in state.items():
+                    param_path = os.path.join(np_folder, name)
+                    with open(param_path, "wb") as f:
+                        np.save(f, param.cpu().detach().numpy())
+                    weight_names.append(name)
+            with open(weight_names_file, "w") as f:
+                json.dump(weight_names, f)
+
+    with open(weight_names_file) as f:
+        weight_names = json.load(f)
+
+    for name in weight_names:
+        param_path = os.path.join(np_folder, name)
+        with open(param_path, "rb") as f:
+            param = np.load(f)
+        yield name, torch.from_numpy(param)
+
+
+def decrypt(fn, key):
+    raise NotImplementedError()
+
+
+def safetensors_encrypted_weights_iterator(
+    hf_weights_files: List[str],
+    is_all_weights_sharded: bool = False,
+    decryption_key: Optional[str] = None,
+):
+    raise NotImplementedError()
+
+
+def safetensors_weights_iterator(
+    hf_weights_files: List[str],
+    is_all_weights_sharded: bool = False,
+    decryption_key: Optional[str] = None,
+) -> Generator[Tuple[str, torch.Tensor], None, None]:
+    """Iterate over the weights in the model safetensor files.
+
+    If is_all_weights_sharded is True, it uses more optimize read by reading an
+    entire file instead of reading each tensor one by one.
+    """
+    if decryption_key:
+        yield from safetensors_encrypted_weights_iterator(
+            hf_weights_files, is_all_weights_sharded, decryption_key
+        )
+        return
+
+    enable_tqdm = (
+        not torch.distributed.is_initialized() or torch.distributed.get_rank() == 0
+    )
+    for st_file in tqdm(
+        hf_weights_files,
+        desc="Loading safetensors checkpoint shards",
+        disable=not enable_tqdm,
+        bar_format=_BAR_FORMAT,
+    ):
+        result = safetensors.torch.load_file(st_file, device="cpu")
+        for name, param in result.items():
+            yield name, param
+
+
+def pt_weights_iterator(
+    hf_weights_files: List[str],
+) -> Generator[Tuple[str, torch.Tensor], None, None]:
+    """Iterate over the weights in the model bin/pt files."""
+    enable_tqdm = (
+        not torch.distributed.is_initialized() or torch.distributed.get_rank() == 0
+    )
+    for bin_file in tqdm(
+        hf_weights_files,
+        desc="Loading pt checkpoint shards",
+        disable=not enable_tqdm,
+        bar_format=_BAR_FORMAT,
+    ):
+        state = torch.load(bin_file, map_location="cpu", weights_only=True)
+        yield from state.items()
+        del state
+
+
+def get_gguf_extra_tensor_names(
+    gguf_file: str, gguf_to_hf_name_map: Dict[str, str]
+) -> List[str]:
+    import gguf
+
+    reader = gguf.GGUFReader(gguf_file)
+    expected_gguf_keys = set(gguf_to_hf_name_map.keys())
+    exact_gguf_keys = set([tensor.name for tensor in reader.tensors])
+    extra_keys = expected_gguf_keys - exact_gguf_keys
+    return [gguf_to_hf_name_map[key] for key in extra_keys]
+
+
+def gguf_quant_weights_iterator(
+    gguf_file: str, gguf_to_hf_name_map: Dict[str, str]
+) -> Generator[Tuple[str, torch.Tensor], None, None]:
+    """
+    Iterate over the quant weights in the model gguf files and convert
+    them to torch tensors
+    """
+
+    import gguf
+
+    reader = gguf.GGUFReader(gguf_file)
+
+    for tensor in reader.tensors:
+        if tensor.name in gguf_to_hf_name_map:
+            weight_type = tensor.tensor_type
+            name = gguf_to_hf_name_map[tensor.name]
+
+            if weight_type.name != "F32":
+                weight_type_name = name.replace("weight", "qweight_type")
+                weight_type = torch.tensor(weight_type)
+                yield weight_type_name, weight_type
+
+    for tensor in reader.tensors:
+        if tensor.name in gguf_to_hf_name_map:
+            weight = tensor.data
+            weight_type = tensor.tensor_type
+            name = gguf_to_hf_name_map[tensor.name]
+
+            if weight_type.name != "F32":
+                name = name.replace("weight", "qweight")
+            param = torch.tensor(weight)
+            yield name, param
+
+
+def convert_pyslice_to_tensor(x: Any) -> torch.Tensor:
+    """convert PySafeSlice object from safetensors to torch.Tensor
+
+    PySafeSlice object supports indexing, which is done before loading the
+    actual tensor and can reduce the amount of memory being read into the
+    memory. However, it does not support more advanced functionalities
+    like `.view()` or `.t()`. Therefore, if we need to modify the loaded
+    tensor with these more complicated operators, we need to convert to
+    tensor first.
+    """
+    if not isinstance(x, torch.Tensor):
+        x = x[:]
+    return x
+
+
+def default_weight_loader(param: torch.Tensor, loaded_weight: torch.Tensor) -> None:
+    """Default weight loader."""
+    try:
+        if param.numel() == 1 and loaded_weight.numel() == 1:
+            # Sometimes scalar values aren't considered tensors with shapes
+            # so if both param and loaded_weight are a scalar,
+            # "broadcast" instead of copy
+            param.data.fill_(loaded_weight.item())
+        else:
+            assert param.size() == loaded_weight.size(), (
+                f"Attempted to load weight ({loaded_weight.size()}) "
+                f"into parameter ({param.size()})"
+            )
+
+            param.data.copy_(loaded_weight)
+    except Exception:
+        # NOTE: This exception is added for the purpose of setting breakpoint to
+        # debug weight loading issues.
+        raise
+
+
+def row_parallel_weight_loader(
+    param: torch.Tensor, loaded_weight: torch.Tensor
+) -> None:
+    """Load weights that are row-parallelized."""
+    tp_rank = get_tensor_model_parallel_rank()
+    shard_dim = 0 if param.dim() != 1 else None
+
+    if shard_dim is not None:
+        shard_size = param.data.shape[shard_dim]
+        start_idx = tp_rank * shard_size
+        loaded_weight = loaded_weight.narrow(shard_dim, start_idx, shard_size)
+
+    return default_weight_loader(param, loaded_weight)
+
+
+LoaderFunction = Callable[[torch.Tensor, torch.Tensor], torch.Tensor]
+
+
+def sharded_weight_loader(shard_axis: int) -> LoaderFunction:
+    """Create a weight loader that shards the weights along the given axis"""
+
+    def loader(param: torch.Tensor, loaded_weight: torch.Tensor) -> None:
+        tp_rank = get_tensor_model_parallel_rank()
+
+        shard_size = param.data.shape[shard_axis]
+        start_idx = tp_rank * shard_size
+        loaded_weight = loaded_weight.narrow(shard_axis, start_idx, shard_size)
+
+        return default_weight_loader(param, loaded_weight)
+
+    return loader
+
+
+def composed_weight_loader(
+    loader: LoaderFunction, fn: Callable[[torch.Tensor], torch.Tensor]
+) -> LoaderFunction:
+    """Create a weight loader that post-processes the weights after loading"""
+
+    def composed_loader(param: torch.Tensor, loaded_weight: torch.Tensor) -> None:
+        loader(param, loaded_weight)
+        param.data.copy_(fn(param))
+        return
+
+    return composed_loader
+
+
+def runai_safetensors_weights_iterator(
+    hf_weights_files: List[str],
+) -> Generator[Tuple[str, torch.Tensor], None, None]:
+    """Iterate over the weights in the model safetensor files."""
+    from runai_model_streamer import SafetensorsStreamer
+
+    enable_tqdm = (
+        not torch.distributed.is_initialized() or torch.distributed.get_rank() == 0
+    )
+
+    with SafetensorsStreamer() as streamer:
+        for st_file in tqdm(
+            hf_weights_files,
+            desc="Loading safetensors using Runai Model Streamer",
+            disable=not enable_tqdm,
+            bar_format=_BAR_FORMAT,
+        ):
+            streamer.stream_file(st_file)
+            yield from streamer.get_tensors()
+
+
+def set_runai_streamer_env(load_config: LoadConfig):
+    if load_config.model_loader_extra_config:
+        extra_config = load_config.model_loader_extra_config
+
+        if "concurrency" in extra_config and isinstance(
+            extra_config.get("concurrency"), int
+        ):
+            os.environ["RUNAI_STREAMER_CONCURRENCY"] = str(
+                extra_config.get("concurrency")
+            )
+
+        if "memory_limit" in extra_config and isinstance(
+            extra_config.get("memory_limit"), int
+        ):
+            os.environ["RUNAI_STREAMER_MEMORY_LIMIT"] = str(
+                extra_config.get("memory_limit")
+            )
+
+    runai_streamer_s3_endpoint = os.getenv("RUNAI_STREAMER_S3_ENDPOINT")
+    aws_endpoint_url = os.getenv("AWS_ENDPOINT_URL")
+    if runai_streamer_s3_endpoint is None and aws_endpoint_url is not None:
+        os.environ["RUNAI_STREAMER_S3_ENDPOINT"] = aws_endpoint_url
+
+
+def initialize_dummy_weights(
+    model: torch.nn.Module,
+    low: float = -1e-3,
+    high: float = 1e-3,
+    seed: int = 1234,
+) -> None:
+    """Initialize model weights with random values.
+
+    The model weights must be randomly initialized for accurate performance
+    measurements. Additionally, the model weights should not cause NaNs in the
+    forward pass. We empirically found that initializing the weights with
+    values between -1e-3 and 1e-3 works well for most models.
+
+    We use per-parameter random seed, so that dummy weights are consistent,
+    even if the model is partitioned across multiple devices. When the seed
+    is fixed, the random values generated by this function only depends on
+    the parameter's number of elements and its data type.
+    """
+    for param in model.state_dict().values():
+        if torch.is_floating_point(param):
+            generator = torch.Generator(device=param.data.device)
+            generator.manual_seed(seed)
+            if torch.finfo(param.data.dtype).bits < 16:
+                # uniform_ doesn't support < 16-bit datatypes (FP8)
+                dtype = param.data.dtype
+                tmp_param = param.data.to(torch.float16)
+                tmp_param = tmp_param.uniform_(low, high, generator=generator).to(dtype)
+                param.data.copy_(tmp_param)
+            else:
+                param.uniform_(low, high, generator=generator)
+
+
+def maybe_remap_kv_scale_name(name: str, params_dict: dict) -> Optional[str]:
+    """Remap the name of FP8 k/v_scale parameters.
+
+    This function handles the remapping of FP8 k/v_scale parameter names.
+    It detects if the given name ends with a suffix and attempts to remap
+    it to the expected name format in the model. If the remapped name is not
+    found in the params_dict, a warning is printed and None is returned.
+
+    Args:
+        name (str): The original loaded checkpoint parameter name.
+        params_dict (dict): Dictionary containing the model's named parameters.
+
+    Returns:
+        str: The remapped parameter name if successful, or the original name
+             if no remapping is needed.
+        None: If the remapped name is not found in params_dict.
+    """
+    if name.endswith(".kv_scale"):
+        print_warning_once(
+            "DEPRECATED. Found kv_scale in the checkpoint. "
+            "This format is deprecated in favor of separate k_scale and "
+            "v_scale tensors and will be removed in a future release. "
+            "Functionally, we will remap kv_scale to k_scale and duplicate "
+            "k_scale to v_scale"
+        )
+        # NOTE: we remap the deprecated kv_scale to k_scale
+        remapped_name = name.replace(".kv_scale", ".attn.k_scale")
+        if remapped_name not in params_dict:
+            print_warning_once(
+                f"Found kv_scale in the checkpoint (e.g. {name}), "
+                "but not found the expected name in the model "
+                f"(e.g. {remapped_name}). kv_scale is "
+                "not loaded."
+            )
+            return None
+        return remapped_name
+
+    possible_scale_names = [".k_scale", ".v_scale"]
+    modelopt_scale_names = [".self_attn.k_proj.k_scale", ".self_attn.v_proj.v_scale"]
+    for scale_name in possible_scale_names:
+        if name.endswith(scale_name):
+            # Check and remap the name based on modelopt scale names
+            if any(
+                modelopt_scale_name in name
+                for modelopt_scale_name in modelopt_scale_names
+            ):
+                remapped_name = name.replace(
+                    f".self_attn.{scale_name[1]}_proj{scale_name}",
+                    f".self_attn.attn{scale_name}",
+                )
+            else:
+                remapped_name = name.replace(scale_name, f".attn{scale_name}")
+            if remapped_name not in params_dict:
+                print_warning_once(
+                    f"Found {scale_name} in the checkpoint (e.g. {name}), "
+                    "but not found the expected name in the model "
+                    f"(e.g. {remapped_name}). {scale_name} is "
+                    "not loaded."
+                )
+                return None
+            return remapped_name
+
+    # If there were no matches, return the untouched param name
+    return name
+
+
+# Adapted from https://github.com/vllm-project/vllm/blob/68ad4e3a8d8a66fb2a43be57471ee13a8bec4ec0/vllm/model_executor/layers/quantization/schema.py
+class KVCacheQuantSchema(BaseModel):
+    dtype: str
+    # Each key is a TP rank. Each value is a dictionary mapping a TP rank's
+    # layer indices to their per-tensor KV cache scaling factor.
+    # TODO: Consider pulling this and its validation methods out into its
+    # own schema class (tricky as its members are variable)
+    scaling_factor: Dict[int, Dict[int, float]]
+
+    @model_validator(mode="after")
+    def check_is_fp8(self) -> "KVCacheQuantSchema":
+        assert self.dtype == "float8_e4m3fn", (
+            "Loaded scaling factors intended for KV cache dtype = "
+            f"{self.dtype} rather than float8_e4m3fn!"
+        )
+        return self
+
+    @model_validator(mode="after")
+    def check_tp_ranks(self, info: ValidationInfo) -> "KVCacheQuantSchema":
+        context = info.context
+        if context:
+            tp_size = context["tp_size"]
+            num_hidden_layers = context["num_hidden_layers"]
+            assert len(self.scaling_factor) == tp_size, (
+                f"Loaded dictionary has TP size {len(self.scaling_factor)} "
+                f"but LLM engine is currently running with TP size {tp_size}."
+            )
+            for tp_rank, layer_maps in self.scaling_factor.items():
+                assert len(layer_maps) == num_hidden_layers, (
+                    f"KV cache scales map for TP rank {tp_rank} is malformed. "
+                    f"Expected {num_hidden_layers} layers, got "
+                    f"{len(layer_maps)}."
+                )
+            for i in range(tp_size):
+                assert (
+                    i in self.scaling_factor
+                ), f"KV cache scales map for TP rank {i} not found."
+        return self
+
+    @model_validator(mode="after")
+    def check_current_rank(self, info: ValidationInfo) -> "KVCacheQuantSchema":
+        context = info.context
+        if context:
+            tp_rank = context["tp_rank"]
+            num_hidden_layers = context["num_hidden_layers"]
+            layer_scales_map = self.scaling_factor[tp_rank]
+            for i in range(num_hidden_layers):
+                assert i in layer_scales_map, (
+                    f"Could not find KV cache scales for layer {i} in "
+                    f"TP rank {tp_rank}."
+                )
+        return self
+
+
+class QuantParamSchema(BaseModel):
+    # TODO: Generalize and extend with more fields
+    # (e.g. weights/activations params) once functionality is enabled
+    model_config = ConfigDict(protected_namespaces=())
+    model_type: Optional[str]
+    kv_cache: KVCacheQuantSchema
+
+    @model_validator(mode="after")
+    def check_model_type(self, info: ValidationInfo) -> "QuantParamSchema":
+        context = info.context
+        if context:
+            model_type = context.get("model_type", None)
+            if model_type is not None:
+                assert model_type == self.model_type, (
+                    f"Model type is {model_type} but loaded "
+                    f"scaling factors belonging to different "
+                    f"model type {self.model_type}!"
+                )
+        return self
+
+
+def kv_cache_scales_loader(
+    filename: str,
+    tp_rank: int,
+    tp_size: int,
+    num_hidden_layers: int,
+    model_type: Optional[str],
+) -> Iterable[Tuple[int, float]]:
+    """
+    A simple utility to read in KV cache scaling factors that have been
+    previously serialized to disk. Used by the model to populate the appropriate
+    KV cache scaling factors. The serialization should represent a dictionary
+    whose keys are the TP ranks and values are another dictionary mapping layers
+    to their KV cache scaling factors.
+    """
+    try:
+        with open(filename) as f:
+            context = {
+                "model_type": model_type,
+                "num_hidden_layers": num_hidden_layers,
+                "tp_rank": tp_rank,
+                "tp_size": tp_size,
+            }
+            schema_dct = json.load(f)
+            schema = QuantParamSchema.model_validate(schema_dct, context=context)
+            layer_scales_map = schema.kv_cache.scaling_factor[tp_rank]
+            return layer_scales_map.items()
+    except FileNotFoundError:
+        logger.error("File or directory '%s' not found.", filename)
+    except json.JSONDecodeError:
+        logger.error("Error decoding JSON in file '%s'.", filename)
+    except Exception:
+        logger.error("An error occurred while reading '%s'.", filename)
+    # This section is reached if and only if any of the excepts are hit
+    # Return an empty iterable (list) => no KV cache scales are loaded
+    # which ultimately defaults to 1.0 scales
+    logger.warning(
+        "Defaulting to KV cache scaling factors = 1.0 for all "
+        "layers in TP rank %d as an error occurred during loading.",
+        tp_rank,
+    )
+    return []
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/custom_logit_processor.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/custom_logit_processor.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..7566c0d7e7d27e13d8513304e7796774bfe9ec41
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/custom_logit_processor.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_batch_info.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_batch_info.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..8cb282639b35bb19d92da23a7d6d772f61d77c73
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_batch_info.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_params.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_params.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..f83994b473ac271bea927101a290c2d4050f59c5
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/__pycache__/sampling_params.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/custom_logit_processor.py b/lib/python3.12/site-packages/sglang/srt/sampling/custom_logit_processor.py
new file mode 100644
index 0000000000000000000000000000000000000000..a64b2498f2390381d27a7a371f91ee7ee26b84d5
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/custom_logit_processor.py
@@ -0,0 +1,38 @@
+import json
+from abc import ABC, abstractmethod
+from functools import lru_cache
+from typing import Any, Dict, List, Optional
+
+import dill
+import torch
+
+
+@lru_cache(maxsize=None)
+def _cache_from_str(json_str: str):
+    """Deserialize a json string to a Callable object.
+    This function is cached to avoid redundant deserialization.
+    """
+    data = json.loads(json_str)
+    return dill.loads(bytes.fromhex(data["callable"]))
+
+
+class CustomLogitProcessor(ABC):
+    """Abstract base class for callable functions."""
+
+    @abstractmethod
+    def __call__(
+        self,
+        logits: torch.Tensor,
+        custom_param_list: Optional[List[Dict[str, Any]]] = None,
+    ) -> torch.Tensor:
+        """Define the callable behavior."""
+        raise NotImplementedError
+
+    def to_str(self) -> str:
+        """Serialize the callable function to a JSON-compatible string."""
+        return json.dumps({"callable": dill.dumps(self).hex()})
+
+    @classmethod
+    def from_str(cls, json_str: str):
+        """Deserialize a callable function from a JSON string."""
+        return _cache_from_str(json_str)
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__init__.py b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..26a780517ce7d70849195dd765f3e38c5dd71863
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__init__.py
@@ -0,0 +1,11 @@
+from sglang.srt.sampling.penaltylib.frequency_penalty import BatchedFrequencyPenalizer
+from sglang.srt.sampling.penaltylib.min_new_tokens import BatchedMinNewTokensPenalizer
+from sglang.srt.sampling.penaltylib.orchestrator import BatchedPenalizerOrchestrator
+from sglang.srt.sampling.penaltylib.presence_penalty import BatchedPresencePenalizer
+
+__all__ = [
+    "BatchedFrequencyPenalizer",
+    "BatchedMinNewTokensPenalizer",
+    "BatchedPresencePenalizer",
+    "BatchedPenalizerOrchestrator",
+]
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/__init__.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/__init__.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..a132e36d70794018f43ff1f89e1b05701ae31556
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/__init__.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/frequency_penalty.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/frequency_penalty.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..271142442303b5de760837e803237aa464df9061
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/frequency_penalty.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/min_new_tokens.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/min_new_tokens.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..aac434c1a7819803a53e65d47e7b53814abbc6be
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/min_new_tokens.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/orchestrator.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/orchestrator.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..41d3a342c29f2afa5892b23c36c61ae2a9accb19
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/orchestrator.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/presence_penalty.cpython-312.pyc b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/presence_penalty.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..1905fde35e650a9e878a2d105940e46ecbb8af81
Binary files /dev/null and b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/__pycache__/presence_penalty.cpython-312.pyc differ
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/frequency_penalty.py b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/frequency_penalty.py
new file mode 100644
index 0000000000000000000000000000000000000000..893a1c3775a676f47f0027e1a67de113a31e75bf
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/frequency_penalty.py
@@ -0,0 +1,65 @@
+import torch
+
+from sglang.srt.sampling.penaltylib.orchestrator import (
+    BatchedPenalizerOrchestrator,
+    _BatchedPenalizer,
+)
+
+
+class BatchedFrequencyPenalizer(_BatchedPenalizer):
+    """
+    Frequency penalizer penalizes tokens based on their frequency in the output.
+    """
+
+    def __init__(self, orchestrator: BatchedPenalizerOrchestrator):
+        self.orchestrator = orchestrator
+        self._is_prepared = False
+
+    def _is_required(self) -> bool:
+        return any(
+            req.sampling_params.frequency_penalty != 0.0
+            for req in self.orchestrator.reqs()
+        )
+
+    def _prepare(self):
+        self.cumulated_frequency_penalties = torch.zeros(
+            (len(self.orchestrator.reqs()), self.orchestrator.vocab_size),
+            dtype=torch.float32,
+            device=self.orchestrator.device,
+        )
+
+        self.frequency_penalties = (
+            torch.tensor(
+                data=[
+                    req.sampling_params.frequency_penalty
+                    for req in self.orchestrator.reqs()
+                ],
+                dtype=torch.float32,
+                device=self.orchestrator.device,
+            )
+        ).unsqueeze_(1)
+
+    def _cumulate_output_tokens(self, output_ids: torch.Tensor):
+        self.cumulated_frequency_penalties.scatter_add_(
+            dim=1,
+            index=output_ids.unsqueeze(1),
+            src=self.frequency_penalties,
+        )
+
+    def _apply(self, logits: torch.Tensor) -> torch.Tensor:
+        logits.sub_(self.cumulated_frequency_penalties)
+
+    def _filter(self, keep_indices: torch.Tensor):
+        self.frequency_penalties = self.frequency_penalties[keep_indices]
+        self.cumulated_frequency_penalties = self.cumulated_frequency_penalties[
+            keep_indices
+        ]
+
+    def _merge(self, their: "BatchedFrequencyPenalizer"):
+        self.frequency_penalties = torch.cat(
+            [self.frequency_penalties, their.frequency_penalties], dim=0
+        )
+        self.cumulated_frequency_penalties = torch.cat(
+            [self.cumulated_frequency_penalties, their.cumulated_frequency_penalties],
+            dim=0,
+        )
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/min_new_tokens.py b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/min_new_tokens.py
new file mode 100644
index 0000000000000000000000000000000000000000..da06265d99bc38318a60916244ce5bca55bb7e39
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/min_new_tokens.py
@@ -0,0 +1,94 @@
+import torch
+
+from sglang.srt.sampling.penaltylib.orchestrator import (
+    BatchedPenalizerOrchestrator,
+    _BatchedPenalizer,
+)
+
+
+class BatchedMinNewTokensPenalizer(_BatchedPenalizer):
+    """
+    Min new tokens penalizer penalizes tokens based on the length of the output.
+    """
+
+    def __init__(self, orchestrator: BatchedPenalizerOrchestrator):
+        self.orchestrator = orchestrator
+        self._is_prepared = False
+
+    def _is_required(self) -> bool:
+        return any(
+            req.sampling_params.min_new_tokens > 0 for req in self.orchestrator.reqs()
+        )
+
+    def _prepare(self):
+        self.min_new_tokens = torch.tensor(
+            data=[
+                req.sampling_params.min_new_tokens for req in self.orchestrator.reqs()
+            ],
+            dtype=torch.int32,
+            device=self.orchestrator.device,
+        ).unsqueeze_(1)
+
+        padded_stop_token_ids = torch.nn.utils.rnn.pad_sequence(
+            sequences=[
+                torch.tensor(
+                    data=(
+                        list(
+                            (req.sampling_params.stop_token_ids or set())
+                            | (req.tokenizer.additional_stop_token_ids or set())
+                            | {req.tokenizer.eos_token_id}
+                        )
+                    ),
+                    dtype=torch.int64,
+                    device=self.orchestrator.device,
+                )
+                for req in self.orchestrator.reqs()
+            ],
+            batch_first=True,
+            padding_value=self.orchestrator.vocab_size,
+        )
+        self.stop_token_penalties = torch.zeros(
+            size=(len(self.orchestrator.reqs()), self.orchestrator.vocab_size + 1),
+            dtype=torch.float32,
+            device=self.orchestrator.device,
+        ).scatter_add_(
+            dim=1,
+            index=padded_stop_token_ids,
+            src=torch.full_like(
+                input=padded_stop_token_ids,
+                dtype=torch.float32,
+                fill_value=float("-inf"),
+                device=self.orchestrator.device,
+            ),
+        )[
+            :, : self.orchestrator.vocab_size
+        ]
+
+        self.len_output_tokens = torch.zeros(
+            size=(len(self.orchestrator.reqs()), 1),
+            dtype=torch.int32,
+            device=self.orchestrator.device,
+        )
+
+    def _cumulate_output_tokens(self, output_ids: torch.Tensor):
+        self.len_output_tokens += 1
+
+    def _apply(self, logits: torch.Tensor):
+        mask = (self.len_output_tokens < self.min_new_tokens).expand_as(logits)
+        logits[mask] += self.stop_token_penalties[mask]
+
+    def _filter(self, keep_indices: torch.Tensor):
+        self.min_new_tokens = self.min_new_tokens[keep_indices]
+        self.stop_token_penalties = self.stop_token_penalties[keep_indices]
+        self.len_output_tokens = self.len_output_tokens[keep_indices]
+
+    def _merge(self, their: "BatchedMinNewTokensPenalizer"):
+        self.min_new_tokens = torch.cat(
+            [self.min_new_tokens, their.min_new_tokens], dim=0
+        )
+        self.stop_token_penalties = torch.cat(
+            [self.stop_token_penalties, their.stop_token_penalties], dim=0
+        )
+        self.len_output_tokens = torch.cat(
+            [self.len_output_tokens, their.len_output_tokens], dim=0
+        )
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/orchestrator.py b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/orchestrator.py
new file mode 100644
index 0000000000000000000000000000000000000000..a75d5e9bbf5e968e7e17495f13d2332305e36999
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/orchestrator.py
@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING, Set, Type
+
+import torch
+
+if TYPE_CHECKING:
+    from sglang.srt.managers.schedule_batch import ScheduleBatch
+
+
+class BatchedPenalizerOrchestrator:
+    def __init__(
+        self,
+        vocab_size: int,
+        batch: ScheduleBatch,
+        penalizers: Set[Type["_BatchedPenalizer"]],
+    ):
+        self.vocab_size = vocab_size
+        self.batch = batch
+        self.device = batch.device
+        self.penalizers = {Penalizer: Penalizer(self) for Penalizer in penalizers}
+
+        is_required = False
+        for penalizer in self.penalizers.values():
+            pen_is_required = penalizer.prepare_if_required()
+            is_required |= pen_is_required
+        self.is_required = is_required
+
+    def reqs(self):
+        return self.batch.reqs
+
+    def cumulate_output_tokens(self, output_ids: torch.Tensor):
+        """
+        Feed the output tokens to the penalizers.
+
+        Args:
+            output_ids (torch.Tensor): The output tokens.
+        """
+        for penalizer in self.penalizers.values():
+            penalizer.cumulate_output_tokens(output_ids=output_ids)
+
+    def apply(self, logits: torch.Tensor) -> torch.Tensor:
+        """
+        Apply the penalizers to the logits.
+        Note that it may apply the penalizers in-place.
+
+        Args:
+            logits (torch.Tensor): The logits to apply the penalizers to.
+
+        Returns:
+            torch.Tensor: The logits after applying the penalizers.
+        """
+        for penalizer in self.penalizers.values():
+            penalizer.apply(logits)
+
+    def filter(self, keep_indices: torch.Tensor):
+        """
+        Filter the penalizers based on the indices to keep in the batch.
+
+        Args:
+            keep_indices (torch.Tensor): Tensor of indices to keep in the batch.
+        """
+        if not self.is_required:
+            return
+
+        if len(keep_indices) == 0:
+            self.is_required = False
+            for penalizer in self.penalizers.values():
+                penalizer.teardown()
+            return
+
+        is_required = False
+        for penalizer in self.penalizers.values():
+            tmp_is_required = penalizer.is_required()
+            is_required |= tmp_is_required
+            if tmp_is_required:
+                penalizer.filter(keep_indices=keep_indices)
+            else:
+                penalizer.teardown()
+        self.is_required = is_required
+
+    def merge(self, their: "BatchedPenalizerOrchestrator"):
+        """
+        Merge the penalizers of another orchestrator into this one.
+
+        Note that this function **must** be called _before_ self.batch.reqs is updated (filtered).
+        Each unprepared penalizers would have to be prepared (creating tensors, etc.) first before merging.
+        This step requires the original batch.reqs, before it gets merged with other batch.reqs.
+
+        Args:
+            their (BatchedPenalizerOrchestrator): The orchestrator to merge into this one.
+        """
+        if not self.is_required and not their.is_required:
+            return
+
+        self.is_required = True
+        for penalizer, their_penalizer in their.penalizers.items():
+            self.penalizers[penalizer].merge(their_penalizer)
+
+
+class _BatchedPenalizer(abc.ABC):
+    """
+    An abstract class for a batched penalizer.
+    """
+
+    def is_prepared(self) -> bool:
+        return self._is_prepared
+
+    def is_required(self) -> bool:
+        return self._is_required()
+
+    def prepare(self):
+        if not self._is_prepared:
+            self._prepare()
+            self._is_prepared = True
+
+    def prepare_if_required(self):
+        if self._is_required():
+            self.prepare()
+            return True
+        else:
+            return False
+
+    def teardown(self):
+        self._is_prepared = False
+
+    def cumulate_output_tokens(self, output_ids: torch.Tensor):
+        if not self._is_prepared:
+            return
+
+        self._cumulate_output_tokens(output_ids=output_ids)
+
+    def apply(self, logits: torch.Tensor) -> torch.Tensor:
+        if not self._is_prepared:
+            return
+
+        self._apply(logits=logits)
+
+    def filter(self, keep_indices: torch.Tensor):
+        if not self._is_prepared:
+            return
+
+        self._filter(keep_indices=keep_indices)
+
+    def merge(self, their: "_BatchedPenalizer"):
+        if not self._is_prepared and not their._is_prepared:
+            return
+
+        self.prepare()
+        their.prepare()
+        self._merge(their)
+
+    @abc.abstractmethod
+    def _is_required(self) -> bool:
+        """
+        Check if the penalizer is required to be prepared.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _prepare(self):
+        """
+        Prepare the penalizer.
+        Usually, this is where the penalizer initializes its tensors.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _cumulate_output_tokens(self, output_ids: torch.Tensor):
+        """
+        Cumulate the output tokens.
+        Orchestrator will call this function to feed the output tokens to the penalizer.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _apply(self, logits: torch.Tensor) -> torch.Tensor:
+        """
+        Apply the penalizer to the logits.
+        Penalizers can modify the logits in-place if needed.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _filter(self, keep_indices: torch.Tensor):
+        """
+        Filter the penalizer (tensors or underlying data) based on the indices to keep in the batch.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _merge(self, their: "_BatchedPenalizer"):
+        """
+        Merge the penalizer with another penalizer.
+        """
+        pass
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/presence_penalty.py b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/presence_penalty.py
new file mode 100644
index 0000000000000000000000000000000000000000..4f3a6ace3a0c4519acb5b107098a1fbd0bab181f
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/penaltylib/presence_penalty.py
@@ -0,0 +1,65 @@
+import torch
+
+from sglang.srt.sampling.penaltylib.orchestrator import (
+    BatchedPenalizerOrchestrator,
+    _BatchedPenalizer,
+)
+
+
+class BatchedPresencePenalizer(_BatchedPenalizer):
+    """
+    Presence penalizer penalizes tokens based on their presence in the output.
+    """
+
+    def __init__(self, orchestrator: BatchedPenalizerOrchestrator):
+        self.orchestrator = orchestrator
+        self._is_prepared = False
+
+    def _is_required(self) -> bool:
+        return any(
+            req.sampling_params.presence_penalty != 0.0
+            for req in self.orchestrator.reqs()
+        )
+
+    def _prepare(self):
+        self.cumulated_presence_penalties = torch.zeros(
+            (len(self.orchestrator.reqs()), self.orchestrator.vocab_size),
+            dtype=torch.float32,
+            device=self.orchestrator.device,
+        )
+
+        self.presence_penalties = (
+            torch.tensor(
+                data=[
+                    req.sampling_params.presence_penalty
+                    for req in self.orchestrator.reqs()
+                ],
+                dtype=torch.float32,
+                device=self.orchestrator.device,
+            )
+        ).unsqueeze_(1)
+
+    def _cumulate_output_tokens(self, output_ids: torch.Tensor):
+        self.cumulated_presence_penalties.scatter_(
+            dim=1,
+            index=output_ids.unsqueeze(1),
+            src=self.presence_penalties,
+        )
+
+    def _apply(self, logits: torch.Tensor) -> torch.Tensor:
+        logits.sub_(self.cumulated_presence_penalties)
+
+    def _filter(self, keep_indices: torch.Tensor):
+        self.presence_penalties = self.presence_penalties[keep_indices]
+        self.cumulated_presence_penalties = self.cumulated_presence_penalties[
+            keep_indices
+        ]
+
+    def _merge(self, their: "BatchedPresencePenalizer"):
+        self.presence_penalties = torch.cat(
+            [self.presence_penalties, their.presence_penalties], dim=0
+        )
+        self.cumulated_presence_penalties = torch.cat(
+            [self.cumulated_presence_penalties, their.cumulated_presence_penalties],
+            dim=0,
+        )
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/sampling_batch_info.py b/lib/python3.12/site-packages/sglang/srt/sampling/sampling_batch_info.py
new file mode 100644
index 0000000000000000000000000000000000000000..66e6552c01d9ca683a893f26f938cbf56585b673
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/sampling_batch_info.py
@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import dataclasses
+import logging
+import threading
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple
+
+import torch
+
+import sglang.srt.sampling.penaltylib as penaltylib
+from sglang.srt.sampling.custom_logit_processor import CustomLogitProcessor
+
+if TYPE_CHECKING:
+    from sglang.srt.managers.schedule_batch import ScheduleBatch
+
+logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass
+class SamplingBatchInfo:
+    # Basic batched sampling params
+    temperatures: torch.Tensor
+    top_ps: torch.Tensor
+    top_ks: torch.Tensor
+    min_ps: torch.Tensor
+
+    # Whether all requests use greedy sampling
+    is_all_greedy: bool
+
+    # Whether any request needs min_p sampling
+    need_min_p_sampling: bool
+
+    # Masking tensors for grammar-guided structured outputs
+    vocab_size: int
+    grammars: Optional[List] = None
+    vocab_mask: Optional[torch.Tensor] = None
+    apply_mask_func: Optional[Callable[[torch.Tensor, torch.Tensor], None]] = None
+
+    # An event used for overlap schedule
+    sampling_info_done: Optional[threading.Event] = None
+
+    # Penalizer
+    penalizer_orchestrator: Optional[penaltylib.BatchedPenalizerOrchestrator] = None
+    linear_penalty: torch.Tensor = None
+
+    # Whether any request has custom logit processor
+    has_custom_logit_processor: bool = False
+    # Custom parameters
+    custom_params: Optional[List[Optional[Dict[str, Any]]]] = None
+    # Custom logit processor
+    custom_logit_processor: Optional[
+        Dict[int, Tuple[CustomLogitProcessor, torch.Tensor]]
+    ] = None
+
+    # Device
+    device: str = "cuda"
+
+    @classmethod
+    def from_schedule_batch(cls, batch: ScheduleBatch, vocab_size: int):
+        reqs = batch.reqs
+        device = batch.device
+        temperatures = (
+            torch.tensor(
+                [r.sampling_params.temperature for r in reqs],
+                dtype=torch.float,
+            )
+            .view(-1, 1)
+            .to(device, non_blocking=True)
+        )
+        top_ps = torch.tensor(
+            [r.sampling_params.top_p for r in reqs], dtype=torch.float
+        ).to(device, non_blocking=True)
+        top_ks = torch.tensor(
+            [r.sampling_params.top_k for r in reqs], dtype=torch.int32
+        ).to(device, non_blocking=True)
+        min_ps = torch.tensor(
+            [r.sampling_params.min_p for r in reqs], dtype=torch.float
+        ).to(device, non_blocking=True)
+
+        # Check if any request has custom logit processor
+        has_custom_logit_processor = (
+            batch.enable_custom_logit_processor  # check the flag first.
+            and any(r.custom_logit_processor for r in reqs)  # then check the requests.
+        )
+
+        if has_custom_logit_processor:
+            # Merge the same type of custom logit processors together
+            processor_dict = {}
+            for i, r in enumerate(reqs):
+                if r.custom_logit_processor is None:
+                    continue
+                processor_str = r.custom_logit_processor
+                if processor_str not in processor_dict:
+                    processor_dict[processor_str] = []
+                processor_dict[processor_str].append(i)
+
+            merged_custom_logit_processor = {
+                hash(processor_str): (
+                    # The deserialized custom logit processor object
+                    CustomLogitProcessor.from_str(processor_str),
+                    # The mask tensor for the requests that use this custom logit processor
+                    torch.zeros(len(reqs), dtype=torch.bool)
+                    .scatter_(0, torch.tensor(true_indices), True)
+                    .to(device, non_blocking=True),
+                )
+                for processor_str, true_indices in processor_dict.items()
+            }
+            custom_params = [r.sampling_params.custom_params for r in reqs]
+        else:
+            merged_custom_logit_processor = None
+            custom_params = None
+
+        # Each penalizers will do nothing if they evaluate themselves as not required by looking at
+        # the sampling_params of the requests (See {_is_required()} of each penalizers). So this
+        # should not add hefty computation overhead other than simple checks.
+        #
+        # While we can choose not to even create the class instances if they are not required, this
+        # could add additional complexity to the {ScheduleBatch} class, especially we need to
+        # handle {filter_batch()} and {merge_batch()} cases as well.
+        penalizer_orchestrator = penaltylib.BatchedPenalizerOrchestrator(
+            vocab_size=vocab_size,
+            batch=batch,
+            penalizers={
+                penaltylib.BatchedFrequencyPenalizer,
+                penaltylib.BatchedMinNewTokensPenalizer,
+                penaltylib.BatchedPresencePenalizer,
+            },
+        )
+
+        ret = cls(
+            temperatures=temperatures,
+            top_ps=top_ps,
+            top_ks=top_ks,
+            min_ps=min_ps,
+            is_all_greedy=all(r.sampling_params.top_k <= 1 for r in reqs),
+            need_min_p_sampling=any(r.sampling_params.min_p > 0 for r in reqs),
+            vocab_size=vocab_size,
+            penalizer_orchestrator=penalizer_orchestrator,
+            has_custom_logit_processor=has_custom_logit_processor,
+            custom_params=custom_params,
+            custom_logit_processor=merged_custom_logit_processor,
+            device=device,
+        )
+        return ret
+
+    def __len__(self):
+        return len(self.temperatures)
+
+    def update_regex_vocab_mask(self):
+        if not self.grammars:
+            self.vocab_mask = None
+            self.apply_mask_func = None
+            return
+
+        # Find a grammar from the list
+        first_grammar = next(grammar for grammar in self.grammars if grammar)
+
+        # TODO(lianmin): Maybe we can reuse the existing mask?
+        self.vocab_mask = first_grammar.allocate_vocab_mask(
+            vocab_size=self.vocab_size,
+            batch_size=len(self.temperatures),
+            device=self.device,
+        )
+        self.apply_mask_func = (
+            first_grammar.apply_vocab_mask
+        )  # force to use static method
+
+        # Apply the mask
+        for i, grammar in enumerate(self.grammars):
+            if grammar and not grammar.finished:
+                grammar.fill_vocab_mask(self.vocab_mask, i)
+
+        # Move the mask to the device if needed
+        self.vocab_mask = first_grammar.move_vocab_mask(self.vocab_mask, self.device)
+
+    def update_penalties(self):
+        if self.penalizer_orchestrator.is_required:
+            self.linear_penalty = torch.zeros(
+                (len(self.temperatures), self.vocab_size),
+                dtype=torch.float32,
+                device=self.temperatures.device,
+            )
+            self.penalizer_orchestrator.apply(self.linear_penalty)
+        else:
+            self.linear_penalty = None
+
+    def apply_logits_bias(self, logits: torch.Tensor):
+        if self.linear_penalty is not None:
+            # Used in the overlap mode
+            logits.add_(self.linear_penalty)
+
+        if self.penalizer_orchestrator and self.penalizer_orchestrator.is_required:
+            # Used in the non-overlap mode
+            self.penalizer_orchestrator.apply(logits)
+
+        if self.vocab_mask is not None:
+            self.apply_mask_func(logits=logits, vocab_mask=self.vocab_mask)
+
+    def filter_batch(self, keep_indices: List[int], keep_indices_device: torch.Tensor):
+        self.penalizer_orchestrator.filter(keep_indices_device)
+
+        if self.has_custom_logit_processor:
+            self._filter_batch_custom_logit_processor(keep_indices, keep_indices_device)
+
+        for item in [
+            "temperatures",
+            "top_ps",
+            "top_ks",
+            "min_ps",
+        ]:
+            value = getattr(self, item, None)
+            setattr(self, item, value[keep_indices_device])
+
+    def _filter_batch_custom_logit_processor(
+        self, keep_indices: List[int], keep_indices_device: torch.Tensor
+    ):
+        """Filter the custom logit processor and custom params"""
+        self.custom_logit_processor = {
+            k: (p, mask[keep_indices_device])
+            for k, (p, mask) in self.custom_logit_processor.items()
+            if torch.any(
+                mask[keep_indices_device]
+            )  # ignore the custom logit processor whose mask is all False
+        }
+        self.custom_params = [self.custom_params[i] for i in keep_indices]
+
+        # If the custom logit processor is an empty dict, set the flag to False,
+        # and set the custom logit processor and custom params to None.
+        if len(self.custom_logit_processor) == 0:
+            self.custom_logit_processor = None
+            self.custom_params = None
+            self.has_custom_logit_processor = False
+
+    @staticmethod
+    def merge_custom_logit_processor(
+        lhs: Optional[Dict[int, Tuple[CustomLogitProcessor, torch.Tensor]]],
+        rhs: Optional[Dict[int, Tuple[CustomLogitProcessor, torch.Tensor]]],
+        bs1: int,
+        bs2: int,
+        device: str,
+    ):
+        if lhs is None and rhs is None:
+            return None
+        lhs, rhs = lhs or {}, rhs or {}
+
+        keys = set(lhs.keys()).union(set(rhs.keys()))
+        merged_dict = {}
+
+        for k in keys:
+            # Get the logit processor object
+            processor = lhs[k][0] if k in lhs else rhs[k][0]
+            # Get and merge the mask tensors from the two dicts
+            left_mask = (
+                lhs[k][1]
+                if k in lhs
+                else torch.zeros(bs1, dtype=torch.bool, device=device)
+            )
+            right_mask = (
+                rhs[k][1]
+                if k in rhs
+                else torch.zeros(bs2, dtype=torch.bool, device=device)
+            )
+            merged_dict[k] = (processor, torch.cat([left_mask, right_mask]))
+
+            assert merged_dict[k][1].shape[0] == bs1 + bs2, (
+                f"The batch size of merged mask ({merged_dict[k][1].shape[0]}) does not match "
+                f"the sum of the batch sizes of the two masks ({bs1 + bs2})"
+                f"\n{left_mask=}\n{right_mask=}\n{bs1=}\n{bs2=}"
+                f"\n{lhs=}\n{rhs=}"
+            )
+
+        return merged_dict
+
+    def merge_batch(self, other: "SamplingBatchInfo"):
+        self.penalizer_orchestrator.merge(other.penalizer_orchestrator)
+
+        # Merge the custom logit processors and custom params lists
+        if self.has_custom_logit_processor or other.has_custom_logit_processor:
+            # Merge the custom logit processors
+            self.custom_logit_processor = (
+                SamplingBatchInfo.merge_custom_logit_processor(
+                    self.custom_logit_processor,
+                    other.custom_logit_processor,
+                    len(self),
+                    len(other),
+                    self.device,
+                )
+            )
+            # Merge the custom params lists
+            self.custom_params = self.custom_params or [None] * len(self)
+            other.custom_params = other.custom_params or [None] * len(other)
+            self.custom_params.extend(other.custom_params)
+
+            # Set the flag to True if any of the two has custom logit processor
+            self.has_custom_logit_processor = True
+
+        # Note: becasue the __len()__ operator is defined on the temperatures tensor,
+        # please make sure any merge operation with len(self) or len(other) is done before
+        # the merge operation of the temperatures tensor below.
+        for item in [
+            "temperatures",
+            "top_ps",
+            "top_ks",
+            "min_ps",
+        ]:
+            self_val = getattr(self, item, None)
+            other_val = getattr(other, item, None)
+            setattr(self, item, torch.cat([self_val, other_val]))
+
+        self.is_all_greedy |= other.is_all_greedy
+        self.need_min_p_sampling |= other.need_min_p_sampling
diff --git a/lib/python3.12/site-packages/sglang/srt/sampling/sampling_params.py b/lib/python3.12/site-packages/sglang/srt/sampling/sampling_params.py
new file mode 100644
index 0000000000000000000000000000000000000000..7c77a204f651530775ece6c6883ed788e527b7ac
--- /dev/null
+++ b/lib/python3.12/site-packages/sglang/srt/sampling/sampling_params.py
@@ -0,0 +1,153 @@
+# Copyright 2023-2024 SGLang Team
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Sampling parameters for text generation."""
+
+from typing import Any, Dict, List, Optional, Union
+
+_SAMPLING_EPS = 1e-6
+
+
+class SamplingParams:
+    """
+    The sampling parameters.
+
+    See docs/backend/sampling_params.md or
+    https://docs.sglang.ai/backend/sampling_params.html
+    for the documentation.
+    """
+
+    def __init__(
+        self,
+        max_new_tokens: int = 128,
+        stop: Optional[Union[str, List[str]]] = None,
+        stop_token_ids: Optional[List[int]] = None,
+        temperature: float = 1.0,
+        top_p: float = 1.0,
+        top_k: int = -1,
+        min_p: float = 0.0,
+        frequency_penalty: float = 0.0,
+        presence_penalty: float = 0.0,
+        repetition_penalty: float = 1.0,
+        min_new_tokens: int = 0,
+        n: int = 1,
+        json_schema: Optional[str] = None,
+        regex: Optional[str] = None,
+        ebnf: Optional[str] = None,
+        structural_tag: Optional[str] = None,
+        ignore_eos: bool = False,
+        skip_special_tokens: bool = True,
+        spaces_between_special_tokens: bool = True,
+        no_stop_trim: bool = False,
+        custom_params: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.max_new_tokens = max_new_tokens
+        self.stop_strs = stop
+        if stop_token_ids:
+            self.stop_token_ids = set(stop_token_ids)
+        else:
+            self.stop_token_ids = None
+        self.temperature = temperature
+        self.top_p = top_p
+        self.top_k = top_k
+        self.min_p = min_p
+        self.frequency_penalty = frequency_penalty
+        self.presence_penalty = presence_penalty
+        self.repetition_penalty = repetition_penalty
+        self.min_new_tokens = min_new_tokens
+        self.regex = regex
+        self.n = n
+        self.json_schema = json_schema
+        self.ebnf = ebnf
+        self.structural_tag = structural_tag
+        self.ignore_eos = ignore_eos
+        self.skip_special_tokens = skip_special_tokens
+        self.spaces_between_special_tokens = spaces_between_special_tokens
+        self.no_stop_trim = no_stop_trim
+        self.custom_params = custom_params
+
+        # Process some special cases
+        if 0 <= self.temperature < _SAMPLING_EPS:
+            # top_k = 1 means greedy sampling
+            self.temperature = 1.0
+            self.top_k = 1
+        if self.top_k == -1:
+            self.top_k = 1 << 30  # whole vocabulary
+
+    def verify(self):
+        if self.temperature < 0.0:
+            raise ValueError(
+                f"temperature must be non-negative, got {self.temperature}."
+            )
+        if not 0.0 < self.top_p <= 1.0:
+            raise ValueError(f"top_p must be in (0, 1], got {self.top_p}.")
+        if not 0.0 <= self.min_p <= 1.0:
+            raise ValueError(f"min_p must be in [0, 1], got {self.min_p}.")
+        if self.top_k < 1 or self.top_k == -1:
+            raise ValueError(
+                f"top_k must be -1 (disable) or at least 1, got {self.top_k}."
+            )
+        if not -2.0 <= self.frequency_penalty <= 2.0:
+            raise ValueError(
+                "frequency_penalty must be in [-2, 2], got "
+                f"{self.frequency_penalty}."
+            )
+        if not -2.0 <= self.presence_penalty <= 2.0:
+            raise ValueError(
+                "presence_penalty must be in [-2, 2], got " f"{self.presence_penalty}."
+            )
+        if not 0.0 <= self.repetition_penalty <= 2.0:
+            raise ValueError(
+                "repetition_penalty must be in [0, 2], got "
+                f"{self.repetition_penalty}."
+            )
+        if not 0 <= self.min_new_tokens:
+            raise ValueError(
+                f"min_new_tokens must be in [0, max_new_tokens], got "
+                f"{self.min_new_tokens}."
+            )
+        if self.max_new_tokens is not None:
+            if self.max_new_tokens < 0:
+                raise ValueError(
+                    f"max_new_tokens must be at least 0, got {self.max_new_tokens}."
+                )
+            if not self.min_new_tokens <= self.max_new_tokens:
+                raise ValueError(
+                    f"min_new_tokens must be in [0, max_new_tokens({self.max_new_tokens})], got "
+                    f"{self.min_new_tokens}."
+                )
+        grammars = [
+            self.json_schema,
+            self.regex,
+            self.ebnf,
+        ]  # since mutually exclusive, only one can be set
+        if sum(x is not None for x in grammars) > 1:
+            raise ValueError("Only one of regex, json_schema, or ebnf can be set.")
+
+    def normalize(self, tokenizer):
+        # Process stop strings
+        if self.stop_strs is None:
+            self.stop_strs = []
+            self.stop_str_max_len = 0
+        else:
+            if isinstance(self.stop_strs, str):
+                self.stop_strs = [self.stop_strs]
+
+            stop_str_max_len = 0
+            for stop_str in self.stop_strs:
+                if tokenizer is not None:
+                    stop_str_ids = tokenizer.encode(stop_str, add_special_tokens=False)
+                    stop_str_max_len = max(stop_str_max_len, len(stop_str_ids))
+                else:
+                    stop_str_max_len = max(stop_str_max_len, len(stop_str))
+            self.stop_str_max_len = stop_str_max_len