Add files

python/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = pybertini
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

python/docs/source/_static/.gitignore

@@ -0,0 +1 @@
+# for _static

python/docs/source/building.rst

@@ -0,0 +1,6 @@
+🛠 Building PyBertini
+****************************
+
+This part is unsatisfactory to me.  I really wish the package would just detect dependencies, and build itself.  However, since there is a C++ library behind it, this is not yet implemented.  For now, you have to configure, compile, and install yourself.
+
+Please see `the b2 wiki entry for compilation <https://github.com/bertiniteam/b2/wiki/Compilation-Guide>`_

python/docs/source/conf.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# PyBertini documentation build configuration file, created by
+# sphinx-quickstart on Wed Oct  4 23:28:46 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# stuff to get autodoc to work. silviana amethyst
+import sys
+import os
+sys.path.insert(0,os.path.abspath('../../.libs'))
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.autosectionlabel',
+    'sphinxcontrib.bibtex']
+
+bibtex_bibfiles = ['../../../doc_resources/bertini2.bib']
+
+#    'sphinx.ext.autosectionlabel_prefix_document',
+autodoc_default_flags = ['members', 'undoc-members','show-inheritance'] 
+#, 'special-members'
+#, , 'inherited-members'
+
+# see http://www.sphinx-doc.org/en/stable/ext/autodoc.html#confval-autoclass_content
+autoclass_content = 'both'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'PyBertini'
+copyright = '2015-2021, Bertini Team'
+author = 'Bertini Team'
+
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+try:
+    import git  #package gitpython
+    repo = git.Repo(search_parent_directories=True) 
+    last_commit = str(repo.head.commit) 
+    version = last_commit[:7]
+    release = last_commit # full version
+except:
+    last_commit = 'gitpython not installed'
+    version = last_commit # The short X.Y version.
+    release = version # The full version, including alpha/beta/rc tags.
+
+
+
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['test']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'bizstyle'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PyBertinidoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'PyBertini.tex', 'PyBertini Documentation',
+     'Bertini Team', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pybertini', 'PyBertini Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'PyBertini', 'PyBertini Documentation',
+     author, 'PyBertini', 'Software for Numerical Algebraic Geometry.',
+     'Miscellaneous'),
+]
+
+
+
+html_logo = "images/bpy_icon_.svg"
+

python/docs/source/detailed/common_doc_nav.incl

@@ -0,0 +1,4 @@
+quick nav links:
+
+* jump to :ref:`👩‍🔧 Detailed`
+* jump to :ref:`🔦 Tutorials`

python/docs/source/detailed/configs.rst

@@ -0,0 +1,30 @@
+🎛 Configurations for algorithms, trackers, endgames, etc
+===================================================================
+
+.. include:: common_doc_nav.incl
+
+🛤 Tracking configs
+---------------------------
+
+* :class:`pybertini.tracking.config.SteppingConfig`
+* :class:`pybertini.tracking.config.NewtonConfig`
+* :class:`pybertini.tracking.config.AMPConfig`
+* :class:`pybertini.tracking.config.FixedPrecisionConfig`
+
+.. autoclass:: pybertini.tracking.config.SteppingConfig
+
+.. autoclass:: pybertini.tracking.config.NewtonConfig
+
+.. autoclass:: pybertini.tracking.config.AMPConfig
+
+.. autoclass:: pybertini.tracking.config.FixedPrecisionConfig
+
+
+🎮 Endgame configs
+-------------------------
+
+.. autoclass:: pybertini.endgame.config.Endgame
+
+Algorithm configs
+---------------------------
+

python/docs/source/detailed/containers.rst

@@ -0,0 +1,15 @@
+🕳 pybertini.list
+=====================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+These types are exposed to Python, because they are returned types from some function or another.  They should be fully interoperable with regular lists, except they can't contain arbitrary things.  
+
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.list

python/docs/source/detailed/cpp_side.rst

@@ -0,0 +1,31 @@
+🗡 C++-flavored gory-detail documentation
+===============================================
+
+.. include:: common_doc_nav.incl
+
+_pybertini
+-------------------
+
+.. automodule:: _pybertini
+
+
+_pybertini.function_tree
+----------------------------
+
+.. automodule:: _pybertini.function_tree
+
+
+
+_pybertini.tracking
+----------------------
+
+.. automodule:: _pybertini.tracking
+
+
+
+_pybertini.endgames
+----------------------
+
+.. automodule:: _pybertini.endgame
+
+

python/docs/source/detailed/detailed.rst

@@ -0,0 +1,49 @@
+👩‍🔧 Detailed
+*******************
+
+.. include:: common_doc_nav.incl
+
+This is a stub page, which merely acts to point you to more specific places in the documentation.  Table of contents below 🔽.  
+
+🖍 Highlights
+--------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   configs
+
+⚙️ Modules
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   top_level
+   doubleprec
+   multiprec
+   function_tree
+   system
+   start_system
+   tracking
+   endgame
+   parse
+   containers
+   logging
+   
+
+🎱 Things you probably don't need
+----------------------------------------
+
+.. toctree::
+  :maxdepth: 1
+
+  cpp_side
+  🕸 PyBertini doc archives <https://doc.bertini2.org/pybertini_archives>
+
+
+
+
+
+
+

python/docs/source/detailed/doubleprec.rst

@@ -0,0 +1,12 @@
+2️⃣ pybertini.doubleprec
+==============================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.doubleprec

python/docs/source/detailed/endgame.rst

@@ -0,0 +1,21 @@
+🎮 pybertini.endgame
+==========================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+
+.. automodule:: pybertini.endgame
+
+
+🎮 pybertini.endgame.config
+=====================================
+
+.. automodule:: pybertini.endgame.config
+
+

python/docs/source/detailed/function_tree.rst

@@ -0,0 +1,26 @@
+🌳 pybertini.function_tree
+===================================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.function_tree
+   :members:
+
+🌳 pybertini.function_tree.symbol
+======================================
+
+.. automodule:: pybertini.function_tree.symbol
+   :members:
+
+
+🌳 pybertini.function_tree.root
+==================================
+
+.. automodule:: pybertini.function_tree.root
+   :members:

python/docs/source/detailed/logging.rst

@@ -0,0 +1,18 @@
+📋 pybertini.logging
+=====================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Logging is enabled for PyBertini through Bertini2's core logging facilities, in turn powered by Boost.Log.  
+
+They currently aren't fancy, but you have a few things you can do.
+
+#. Adjust the level.  See :class:`~pybertini.logging.severity_level` and :func:`~pybertini.logging.set_level`
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.logging

python/docs/source/detailed/multiprec.rst

@@ -0,0 +1,12 @@
+🃏 pybertini.multiprec
+============================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.multiprec

python/docs/source/detailed/parse.rst

@@ -0,0 +1,12 @@
+💬 pybertini.parse
+=====================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.parse

python/docs/source/detailed/start_system.rst

@@ -0,0 +1,12 @@
+🚦 pybertini.system.start_system
+==================================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.system.start_system

python/docs/source/detailed/system.rst

@@ -0,0 +1,12 @@
+🏙 pybertini.system
+==========================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.system

python/docs/source/detailed/top_level.rst

@@ -0,0 +1,29 @@
+🔝 pybertini
+==================
+
+.. include:: common_doc_nav.incl
+
+Namespaces
+-------------
+
+* :py:mod:`~pybertini.multiprec`
+* :py:mod:`~pybertini.system`
+* :py:mod:`~pybertini.function_tree`
+* :py:mod:`~pybertini.tracking`
+* :py:mod:`~pybertini.endgame`
+
+
+
+Convenience
+------------
+
+For your convenience, these things have been placed in the root level `pybertini` namespace:
+
+* :class:`~pybertini.system.System`
+* :class:`~pybertini.function_tree.symbol.Variable`
+* :class:`~pybertini.function_tree.VariableGroup`
+
+There's not a whole lot else at this level.  Pybertini mostly exists in submodules, to help things be organized.
+
+
+

python/docs/source/detailed/tracking.rst

@@ -0,0 +1,54 @@
+🛤 pybertini.tracking
+===========================
+
+.. include:: common_doc_nav.incl
+
+Notes
+--------
+
+Trackers in Bertini2 are stateful objects, that refer to a system they are tracking, hold their specific settings, and have a notion of current time and space value.
+
+Here are some particular classes and functions to pay attention to:
+
+* :class:`pybertini.tracking.AMPTracker`
+* :class:`pybertini.tracking.DoublePrecisionTracker`
+* :class:`pybertini.tracking.MultiplePrecisionTracker`
+
+Here are the implemented ODE predictors you can choose from:
+
+* :class:`pybertini.tracking.Predictor`
+
+Calls to :meth:`track_path` return a :class:`pybertini.tracking.SuccessCode`.
+
+And, trackers are implemented using observer pattern.  They live in the ``pybertini.tracking.observers`` namespace, with provisions for each tracker type available under a submodule thereof: ``amp``, ``multiple``, and ``double``.  They are also conveniently available using the ``tr.observers``, where ``tr`` is a tracker you already made.  See :mod:`pybertini.tracking.observers.amp`
+
+
+Auto-generated docs
+--------------------
+
+.. automodule:: pybertini.tracking
+
+
+🛤 pybertini.tracking.config
+=====================================
+
+.. automodule:: pybertini.tracking.config
+
+
+🛤 pybertini.tracking.observers
+===================================
+
+📝 All of these are available for all trackers, though you should use the ones for your tracker type.  Look in ``pybertini.tracking.AMPTracker.observers``, etc.
+
+.. automodule:: pybertini.tracking.observers
+
+#. ``pybertini.tracking.observers.amp``
+#. ``pybertini.tracking.observers.double``
+#. ``pybertini.tracking.observers.multiple``
+
+📝 Symmetrically, there are the same observers in all three.
+
+.. automodule:: pybertini.tracking.observers.amp
+
+
+ Know that you are loved and appreciated, dear reader.  💟

python/docs/source/images/bpy_icon_.svg

@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   id="svg2"
+   version="1.1"
+   viewBox="0 0 54 46"
+   height="46pt"
+   width="54pt">
+  <metadata
+     id="metadata43">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <!--latexit:AAAFvXjadVRdbFRFFJ5hpqV0Kd22UEqh7WK3glrKtoILQmtb2q1YulR2t912d7vO
+3ju7vfT+ee8sstxsMvEHH/BfYwwRpSX+lBhFo8agD8aEGG1MtCW+kvjiky+++Orc
+3RWpwTu5mTNnzpzznTPfmYypKjYLBG7CDQhXVT91Nu4/Qy1bMfS438icphKzZ/zE
+kuYVoY76mWE2Anj+8ife3Rtrdt/T6e+6d8/e++5/oPfQ4f6hsUfDJ6fjybQkz6uG
+zWJ+Pa+qa5tqPZubfdPhSM8CLdizYq74nfJLKrHt5bot9d6Gxqat2/gGjjjmVbya
+b+Q1fBOvXd7esqN156629g7u4Zv5Fl7PG3gr38nbeDv3xTPEpqqi05hkqIYV1QyZ
+xpjCVBo3LUq0jEpTGsnpSlaRCBMpRWXCaNpbnyHSQs4y8rp8zD04axt5S6JRepZ1
+gsq31r3P07M/EAtHTo0NJ8ORkmHEJBINBXxiAC/kdat9Dx44OFtOQycajZdFak9X
+Diw9FPxHjIcjJ0t5e/Gq5+EjR2dEIWxmKXqOeyeFo4FHBLBwZCLPiMAdKe1cGRgM
+inPlxdqw59jIaOj2WoAaYkLK5Bm1eSPfwZvSDdBJyoaU16jOSlASvQGTpRxiMUVS
+abE2mbepSGKB5GhCiC5oO+WUylf0dQmN7Msalvh15itp7zzhEM22C1pGWGqEzdv/
+3XOVd9tL5Fn2UMpRdFNA1aVyoGxe9THDxwom9cmKJQqjFoRAJEsRWH3SPLGIxAQV
+13kiB0xiUqtbI1ZO0ft7Fb1bJbpsS0KbcnLU0CizCsXaddBcQMwwVFvkP0JFXSw6
+SURIeUSwR1NEkKREFdVJqu5UdJJWaf5f46xqGJawLs2ueVmodal+fHxi8TG+dfEE
+38ZbpsKRkKjkzcnHT3ki0diUWEeUc1RcYTakkpwt1mFxA52De8uk83p5M98+NWHo
+RDIEJ2ZmKx6WEsGKJLSpOXH1I4rkMppYhaVUUCifIGlv4x2MkMskWcoE76rvHBwu
+h1ylnmzObU6mCCBD31Z/vfJ7vobvEi6V0yLmiOiYpYVgRXK7QtsfCPX6xAC8zuWk
+ORriHSX2eduTbqkzGWe4mHaSTPSTblgaUR2zUCzO9Qmf+TNpb9Ntlv+bxJV8Klji
+/zgtUHmo8t78UjgXtQyDcQhqQANoBZ1gH+gDQZAABMwDEzjgafACeAm8Al4Db4A3
+wVvgIngbvAM+BFfBR+BjcA18Bj4HX4KvwHXwDbgBVsDP4FdwC/wB/oQY1sMW2AG7
+YB88DI/AfjgMJ+AUnIMEKtCCDBbgM/A5eB5egJfgIrwKP4XX4ffwB7gCf0InUATF
+0DSaQQmUQjLSEENF9Cx6Eb2MXkWvo4voXfQ+WkbX0BfoO3QD/Yhuod/QXxjgKlyH
+m3ELbsN+vAf34IP4KB7Ao3gMH8fjWMVP4ufxBXwJX8bvla9oA6y8SQ5Y9+EP/gbj
+f94X
+-->
+  <defs
+     id="defs4">
+    <g
+       id="g6">
+      <symbol
+         id="glyph0-0"
+         overflow="visible">
+        <path
+           id="path9"
+           d=""
+           style="stroke:none;" />
+      </symbol>
+      <symbol
+         id="glyph0-1"
+         overflow="visible">
+        <path
+           id="path12"
+           d="M 5.015625 -21.296875 C 5.015625 -21.765625 5.015625 -22.65625 4.703125 -23.3125 L 8.609375 -23.3125 C 8.140625 -22.734375 8.140625 -22.015625 8.140625 -21.484375 L 8.140625 -3.078125 C 8.140625 -2.546875 8.140625 -1.828125 8.609375 -1.25 L 4.703125 -1.25 C 5.015625 -1.90625 5.015625 -2.796875 5.015625 -3.265625 Z M 14.78125 -13.765625 C 15.953125 -14.921875 16.25 -16.75 16.25 -18.28125 C 16.25 -20.765625 15.453125 -22.296875 14.625 -23.171875 C 17.109375 -22.875 19.65625 -21.984375 19.65625 -18.4375 C 19.65625 -16.140625 17.140625 -14.265625 14.78125 -13.765625 Z M 9.390625 -21.375 C 9.390625 -22.09375 9.390625 -22.484375 9.890625 -22.875 C 10.046875 -22.953125 10.578125 -23.3125 11.4375 -23.3125 C 13.015625 -23.3125 14.984375 -22.046875 14.984375 -18.28125 C 14.984375 -14.265625 12.9375 -13.40625 9.390625 -13.34375 Z M 16.921875 -13.15625 C 18.9375 -14.203125 20.90625 -16 20.90625 -18.4375 C 20.90625 -23.421875 16.78125 -24.5625 12.40625 -24.5625 L 1.546875 -24.5625 C 0.890625 -24.5625 0.328125 -24.5625 0.328125 -23.921875 C 0.328125 -23.3125 0.9375 -23.3125 1.5 -23.3125 C 3.65625 -23.3125 3.765625 -22.953125 3.765625 -21.234375 L 3.765625 -3.328125 C 3.765625 -1.546875 3.625 -1.25 1.359375 -1.25 C 0.96875 -1.25 0.328125 -1.25 0.328125 -0.640625 C 0.328125 0 0.890625 0 1.546875 0 L 12.1875 0 C 16.609375 0 22.265625 -1.71875 22.265625 -6.703125 C 22.265625 -10.4375 19.546875 -12.4375 16.921875 -13.15625 Z M 9.390625 -3.1875 L 9.390625 -12.078125 C 12.265625 -12.078125 13.484375 -12.078125 14.59375 -11.265625 C 16 -10.1875 16.09375 -7.859375 16.09375 -6.703125 C 16.09375 -5.3125 16 -1.25 11.515625 -1.25 C 9.390625 -1.25 9.390625 -2.515625 9.390625 -3.1875 Z M 15.78125 -1.6875 C 17.109375 -3.1875 17.359375 -5.09375 17.359375 -6.703125 C 17.359375 -9.1875 16.8125 -11.046875 15.390625 -12.234375 C 18.6875 -11.6875 21.015625 -9.828125 21.015625 -6.703125 C 21.015625 -3.984375 18.859375 -2.40625 15.78125 -1.6875 Z M 15.78125 -1.6875 "
+           style="stroke:none;" />
+      </symbol>
+      <symbol
+         id="glyph1-0"
+         overflow="visible">
+        <path
+           id="path15"
+           d=""
+           style="stroke:none;" />
+      </symbol>
+      <symbol
+         id="glyph1-1"
+         overflow="visible">
+        <path
+           id="path18"
+           d="M 12.6875 -4.5625 L 11.828125 -4.5625 C 11.75 -4.015625 11.5 -2.53125 11.171875 -2.28125 C 10.96875 -2.140625 9.046875 -2.140625 8.6875 -2.140625 L 4.0625 -2.140625 C 6.703125 -4.46875 7.578125 -5.171875 9.09375 -6.359375 C 10.953125 -7.828125 12.6875 -9.390625 12.6875 -11.78125 C 12.6875 -14.8125 10.015625 -16.671875 6.796875 -16.671875 C 3.6875 -16.671875 1.578125 -14.484375 1.578125 -12.171875 C 1.578125 -10.890625 2.65625 -10.765625 2.90625 -10.765625 C 3.515625 -10.765625 4.25 -11.203125 4.25 -12.109375 C 4.25 -12.546875 4.0625 -13.4375 2.765625 -13.4375 C 3.546875 -15.21875 5.25 -15.765625 6.421875 -15.765625 C 8.9375 -15.765625 10.25 -13.8125 10.25 -11.78125 C 10.25 -9.59375 8.6875 -7.859375 7.890625 -6.953125 L 1.828125 -0.984375 C 1.578125 -0.75 1.578125 -0.703125 1.578125 0 L 11.921875 0 Z M 12.6875 -4.5625 "
+           style="stroke:none;" />
+      </symbol>
+      <symbol
+         id="glyph1-2"
+         overflow="visible">
+        <path
+           id="path21"
+           d="M 6.984375 3.96875 C 5.34375 3.96875 5.09375 3.96875 5.09375 2.890625 L 5.09375 -1.203125 C 5.21875 -1.078125 6.40625 0.25 8.515625 0.25 C 11.828125 0.25 14.65625 -2.234375 14.65625 -5.421875 C 14.65625 -8.515625 12.109375 -11.078125 8.90625 -11.078125 C 7.484375 -11.078125 6.03125 -10.546875 5 -9.546875 L 5 -11.078125 L 1.234375 -10.796875 L 1.234375 -9.890625 C 2.984375 -9.890625 3.109375 -9.765625 3.109375 -8.71875 L 3.109375 2.890625 C 3.109375 3.96875 2.859375 3.96875 1.234375 3.96875 L 1.234375 4.875 C 1.28125 4.875 3.03125 4.765625 4.09375 4.765625 C 5.015625 4.765625 6.75 4.84375 6.984375 4.875 Z M 5.09375 -8.359375 C 5.84375 -9.609375 7.3125 -10.265625 8.640625 -10.265625 C 10.75 -10.265625 12.375 -8.0625 12.375 -5.421875 C 12.375 -2.5625 10.5 -0.453125 8.359375 -0.453125 C 6.15625 -0.453125 5.171875 -2.390625 5.09375 -2.53125 Z M 5.09375 -8.359375 "
+           style="stroke:none;" />
+      </symbol>
+      <symbol
+         id="glyph1-3"
+         overflow="visible">
+        <path
+           id="path24"
+           d="M 11.875 -8.359375 C 12.578125 -9.890625 13.859375 -9.921875 14.265625 -9.921875 L 14.265625 -10.828125 C 13.5625 -10.765625 13.078125 -10.71875 12.359375 -10.71875 C 11.671875 -10.71875 10.75 -10.75 10.0625 -10.828125 L 10.0625 -9.921875 C 10.890625 -9.875 11.09375 -9.359375 11.09375 -8.96875 C 11.09375 -8.65625 10.96875 -8.4375 10.875 -8.1875 L 8.078125 -2.234375 L 5 -8.859375 C 4.921875 -9.015625 4.84375 -9.171875 4.84375 -9.34375 C 4.84375 -9.921875 5.703125 -9.921875 6.125 -9.921875 L 6.125 -10.828125 C 5.75 -10.796875 3.9375 -10.71875 3.234375 -10.71875 C 2.484375 -10.71875 1.5 -10.75 0.78125 -10.828125 L 0.78125 -9.921875 C 2.1875 -9.921875 2.453125 -9.84375 2.84375 -9.046875 L 7.0625 0 C 6.828125 0.5 6.578125 0.984375 6.359375 1.484375 C 5.796875 2.6875 5 4.421875 3.296875 4.421875 C 2.65625 4.421875 2.453125 4.296875 2.203125 4.125 C 2.234375 4.125 2.9375 3.859375 2.9375 3.03125 C 2.9375 2.40625 2.484375 1.953125 1.859375 1.953125 C 1.203125 1.953125 0.75 2.40625 0.75 3.0625 C 0.75 4.25 1.9375 5.125 3.296875 5.125 C 5.421875 5.125 6.65625 2.890625 7 2.140625 Z M 11.875 -8.359375 "
+           style="stroke:none;" />
+      </symbol>
+    </g>
+  </defs>
+  <g
+     id="surface1">
+    <g
+       id="g27"
+       style="fill:rgb(0%,0%,0%);fill-opacity:1;">
+      <use
+         id="use29"
+         y="31.574"
+         x="0.6284"
+         xlink:href="#glyph0-1" />
+    </g>
+    <g
+       id="g31"
+       style="fill:rgb(0%,0%,0%);fill-opacity:1;">
+      <use
+         id="use33"
+         y="16.7636"
+         x="24.5396"
+         xlink:href="#glyph1-1" />
+    </g>
+    <g
+       id="g35"
+       style="fill:rgb(0%,0%,0%);fill-opacity:1;">
+      <use
+         id="use37"
+         y="40.4408"
+         x="24.5396"
+         xlink:href="#glyph1-2" />
+      <use
+         id="use39"
+         y="40.4408"
+         x="39.603008"
+         xlink:href="#glyph1-3" />
+    </g>
+  </g>
+</svg>

python/docs/source/images_common

@@ -0,0 +1 @@
+../../../doc_resources/images/

python/docs/source/index.rst

@@ -0,0 +1,35 @@
+.. PyBertini documentation master file, created by
+   sphinx-quickstart on Wed Oct  4 23:28:46 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+PyBertini -- the Python bindings for Bertini
+*************************************************
+
+
+1️⃣ Introductory materials
+==================================
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   tutorials/tutorials
+
+🏛 Reference materials
+============================
+
+.. toctree::
+   :maxdepth: 3
+
+   detailed/detailed
+   building
+   zbib
+
+🔀 Indices and tables
+=============================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* 🔍 :ref:`search`
+

python/docs/source/intro.rst

@@ -0,0 +1,33 @@
+👋 Welcome to PyBertini
+====================================
+
+Bertini is software for numerically solving systems of polynomials.  PyBertini is the Python provided for running Bertini.
+
+🗺 Mathematical overview
+----------------------------------
+
+The main algorithm for numerical algebraic geometry implemented in Bertini is homotopy continuation.  A homotopy is formed, and the solutions to the start system are continued into the solutions for the target system.
+
+
+.. figure:: images_common/homotopycontinuation_generic_40ppi.png
+   :scale: 100 %
+   :alt: Homotopy continuation
+
+   Predictor-corrector methods with optional adaptive precision track paths from 1 to 0, solving :math:`f`.
+
+The definitive resource for Bertini 1 is the book :cite:`bertinibook`.  While the way we interact with Bertini changes from version 1 to version 2, particularly when using PyBertini, the algorithms remain fundamentally the same.  So do most of the ways to change settings for the path trackers, etc.  We believe that embracing the flexibility of Python3 with PyBertini allows for much greater flexibility.  It also will relieve the user from the burden of input and output file writing and parsing.  Instead, computed results are returned directly to the user.  
+
+Consider checking out the :ref:`🔦 Tutorials`.
+
+
+⛲️ Source code
+---------------------------
+
+PyBertini is distributed with Bertini2, available at `its GitHub repo <https://github.com/bertiniteam/b2>`_.
+
+The core is written in template-heavy C++, and is exposed to Python through Boost.Python.
+
+⚖️ Licenses
+------------------
+
+Bertini2 and its direct components are available under GPL3, with additional clauses in section 7 to protect the Bertini name.  Bertini2 also uses open source softwares, with their own licenses, which may be found in the Bertini2 repository, in the licenses folder.

python/docs/source/tutorials/evaluation_cyclic.rst

@@ -0,0 +1,91 @@
+♻️ Evaluation of cyclic-:math:`n` polynomials 
+*******************************************************
+
+Bertini is software for algebraic geometry.  This means we work with systems of polynomials, a critical component of which is system and function evaluation.
+
+Bertini2 allows us to set up many kinds of functions, and thus systems, by exploting operator overloading.
+
+Make some symbols
+==================
+
+Let's start by making some variables, programmatically [1]_.  
+
+::
+
+	import pybertini
+	import numpy
+
+	num_vars = 10
+	x = [None] * num_vars # preallocate the list
+	for ii in range(num_vars):
+	    x[ii] = pybertini.Variable('x' + str(ii))
+
+Huzzah, we have `num_vars` variables!  This was hard to do in Bertini 1's classic style input files.  Now we can do it directly! 🎯
+
+Write a function to produce the cyclic :math:`n` polynomials :cite:`cyclic_n`.
+
+::
+
+	def cyclic(vars):
+	    n = len(vars)
+	    f = [None] * len(vars)
+	    y = []
+	    for ii in range(2):
+	        for x in vars:
+	            y.append(x)
+	        
+	    for ii in range(n-1):
+	        f[ii] = numpy.sum( [numpy.prod(y[jj:jj+ii+1]) for jj in range(n)] ) 
+	    
+	    # the last one is minus one
+	    f[-1] = numpy.prod(vars)-1
+	    return f
+
+Now we will make a System, and put the cyclic polynomials into it.
+
+::
+
+	sys = pybertini.System()
+
+	for f in cyclic(x):
+	    sys.add_function(f)
+	    
+	print(sys) # long screen output, i know
+
+We also need to associate the variables with the system.  Unassociated variables are left unknown, and retain their value until elsewhere set.
+
+::
+	
+	vg = pybertini.VariableGroup()
+	for var in x:
+		vg.append(var)
+	sys.add_variable_group(vg)
+
+Let's simplify this.  It will modify elements of the constructed function tree, even those held externally -- Bertini uses shared pointers under the hood, so pay attention to where you re-use parts of your functions, because later modification of them without deep cloning will cause ... modification elsewhere, too.  
+
+::
+
+	pybertini.system.simplify(sys)
+
+Now, let's evaluate it at the origin -- all zero's (0 is the default value for multiprecision complex numbers in Bertini2).  The returned value should be all zero's except the last entry, which should be -1.
+
+::
+
+	s = pybertini.multiprec.Vector() 
+	s.resize(num_vars)
+	sys.eval(s)
+
+Yay, all zeros, except the last one is -1.  Huzzah.
+
+Let's change the values of our vector, and re-evaluate.
+
+::
+
+	for ii in range(num_vars):
+		s[ii] = pybertini.multiprec.Complex(ii)
+	sys.eval(s)
+
+
+There is much more one can do, too!  Please write the authors, particularly Dani Brake, for more.
+
+.. [1] This is one of the reasons we wrote Bertini2's symbolic C++ core and exposed it to Python.

python/docs/source/tutorials/manual_endgame_usage.rst

@@ -0,0 +1,164 @@
+🎮 Using an endgame to compute singular endpoints 
+*********************************************************
+
+
+
+Background
+==============
+
+Polynomial systems often have singular solutions.  In numerical algebraic geometry, we want to compute all solutions, even the challenging singular ones.  The normal method of homotopy continuation with straight-line tracking fails to compute such roots, because tracking to a place where the Jacobian is non-invertible using methods that require inverting the Jacobian is doomed to fail [#]_.  
+
+So, if we can't track to a singular solution, but we still want to track to compute them, what are we to do?  We track around them, or near them, but not actually to them.  These methods are collectively called *endgames*, a term coined to evoke a sense of chess :cite:`morgan1990computing` :cite:`morgan1992computing` :cite:`morgan1992power`.  Thanks, Andrew Sommese, Charles Wampler, and Alexander Morgan, for everything you have given our community.
+
+Endgames represent a way to finish a tracking of a path, when the endpoint is possibly singular.  Rather than track all the way to the endtime, you instead run an endgame that uses mathematical theory to compute the root.
+
+Endgames in PyBertini
+==========================
+
+An endgame is a computational tool that one does in the final stage of a path track to a possibly singular root.  There are two implemented endgames in Bertini:
+
+#. Power series (PSEG) -- uses `Hermite interpolation <https://en.wikipedia.org/wiki/Hermite_interpolation>`_ across a sequence of geometrically-spaced points (in time) to extrapolate to a target time :cite:`morgan1992power`. 
+#. Cauchy (CauchyEG)-- uses `Cauchy's integral formula <https://en.wikipedia.org/wiki/Cauchy's_integral_formula>`_ in a sequence of circles about the root you are computing.  
+
+Both try to compute the cycle number :math:`c` for the root.  In PSEG, :math:`c` is used as the degree of a Hermite interpolant used to extrapolate to 0.  In CauchyEG,  it is used for the number of cycles to walk before doing a trapezoid-rule integral.
+
+Each is provided in the three precision modes, double, fixed multiple, and adaptive.  Since we are using the :class:`~pybertini.tracking.AMPTracker` in this tutorial, we will of course use the adaptive endgame.  I really like the Cauchy endgame, so we're in the land of the :class:`~pybertini.endgame.AMPCauchyEG`.
+
+
+Example
+----------
+
+
+Form a system
+~~~~~~~~~~~~~~~~
+
+The Griewank-Osborne system has one multiplicity-three singular solution at the origin :cite:`griewank1983analysis`.  It comes pre-built for us as part of Bertini2's C++ core, and is accessible by peeking into the `precon` module.  
+
+.. todo::
+
+	expose the precon namespace.  it's a 1-hour task, and danielle 😈 should do it.
+
+Let's build it from scratch, for the practice.
+
+:: 
+
+	import pybertini
+
+	gw = pybertini.System()
+
+	x = pybertini.Variable("x")
+	y = pybertini.Variable("y")
+
+	vg = pybertini.VariableGroup()
+	vg.append(x)
+	vg.append(y)
+	gw.add_variable_group(vg)
+
+	gw.add_function(pybertini.multiprec.Rational(29,16)*x**3 - 2*x*y)
+	gw.add_function(y - x**2)
+
+
+Form a start system and homotopy 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Next, we make the total degree start system for `gw`, and couple it using the gamma trick :cite:`morgan1987homotopy` and a path variable.
+
+::
+
+	t = pybertini.Variable('t')
+	td = pybertini.system.start_system.TotalDegree(gw)
+	gamma = pybertini.function_tree.symbol.Rational.rand()
+	hom = (1-t)*gw + t*gamma*td
+	hom.add_path_variable(t)
+
+
+
+🛤 Track to the endgame boundary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make a tracker.  I use adaptive precision a lot, so we'll roll with that.  There are also double and fixed-multiple versions.  See the other tutorials or the detailed documentation.
+
+::
+
+	tr = pybertini.tracking.AMPTracker(hom)
+
+	start_time = pybertini.multiprec.Complex("1")
+	eg_boundary = pybertini.multiprec.Complex("0.1")
+
+	midpath_points = [None]*td.num_start_points()
+	for ii in range(td.num_start_points()):
+		midpath_points[ii] = pybertini.multiprec.Vector()
+		code = tr.track_path(result=midpath_points[ii], start_time=start_time, end_time=eg_boundary, start_point=td.start_point_mp(ii))
+		if code != pybertini.tracking.SuccessCode.Success:
+			print('uh oh, tracking a path before the endgame boundary failed, successcode ' + code)
+
+
+
+
+🎮 Use the endgame
+~~~~~~~~~~~~~~~~~~~~
+
+
+To make an endgame, we need to feed it the tracker that is used to run.  There are also config structs to play with, that control the way things are computed.
+
+::
+
+	eg = pybertini.endgame.AMPCauchyEG(tr)
+
+	# make an observer to be able to see what's going on inside
+	ob = pybertini.endgame.observers.amp_cauchy.GoryDetailLogger()
+
+	eg.add_observer(ob)
+
+Since the endgame hasn't been run yet things are empty and default::
+
+	assert(eg.cycle_number()==0)
+	assert(eg.final_approximation()==np.array([]))
+
+The endgames are used by invoking ``run``, feeding it the point we are tracking on, the time we are at, and the time we want to track to. ::
+
+	final_points = []
+
+
+	target_time = pybertini.multiprec.Complex(0)
+	codes = []
+	for ii in range(td.num_start_points()):
+		eg_boundary.precision( midpath_points[ii][0].precision())
+		target_time.precision( midpath_points[ii][0].precision())
+		print('before {} {} {}'.format(eg_boundary.precision(), target_time.precision(), midpath_points[ii][0].precision()))
+		codes.append(eg.run(start_time=eg_boundary, target_time=target_time, start_point=midpath_points[ii]))
+		print('path {} -- code {}'.format(ii,codes[-1]))
+		print(eg.final_approximation())
+		# final_points.append(copy.deep_copy(eg.final_approximation()))
+		print('after {} {} {}'.format(eg_boundary.precision(), target_time.precision(), midpath_points[ii][0].precision()))
+
+.. todo::
+
+	the endgame returns its `final_approximation` by reference, so capturing its value into a list makes many references to this internal variable, not copies of the point.  so, one should take deepcopy's of the vector, but they are not currently pickleable due to the complex multiprecision class.  an issue has been filed (#148) and this issue will be solved shortly (danielle, 20180227)
+
+Conclusion
+============
+
+
+Using a singular endgame, we can compute singular endpoints of homotopy paths.  What an age to live in!  🌌
+
+
+
+
+
+📚 Further reading
+========================
+
+The following three papers (cited above) laid the foundation for endgames and computation of singular endpoints:
+
+* Computing singular solutions to nonlinear analytic systems :cite:`morgan1990computing`
+* Computing singular solutions to polynomial systems :cite:`morgan1992computing` 
+* A power series method for computing singular solutions to nonlinear analytic systems :cite:`morgan1992power`.
+
+👣 Footnotes
+-------------
+
+.. [#]  No, we don't actually invert the Jacobian in practice while solving the Davidenko differential equation, but numerical issues exist no matter which method you use to solve the system.
+
+
+

python/docs/source/tutorials/tracking_nonsingular.rst

@@ -0,0 +1,264 @@
+🛤 Tracking to nonsingular endpoints 
+**********************************************
+
+.. testsetup:: *
+
+   import pybertini
+
+PyBertini works by setting up systems, setting up algorithms to use those systems, and doing something with the output.
+
+Forming a system
+=================
+
+First, gain access to pybertini::
+
+    import pybertini
+
+Let's make a couple of :class:`~pybertini.function_tree.symbol.Variable`'s::
+
+	x = pybertini.function_tree.symbol.Variable("x") #yes, you can make a variable not match its name...
+	y = pybertini.function_tree.symbol.Variable("y")
+
+Now, make a few symbolic expressions out of them::
+
+	f = x**2 + y**2 -1  # ** is exponentiation in Python.
+	g = x+y
+
+There's no need to "set them equal to 0" -- expressions used as functions in a system in Bertini are taken to be equal to zero.  If you have an equality that's not zero, move one side to the other.
+
+Let's make an empty :class:`~pybertini.system.System`, then build into it::
+
+	sys = pybertini.System()
+	sys.add_function(f, 'f')  # name the function
+	sys.add_function(g)       # or not...
+
+``sys`` doesn't know its variables yet, so let's group them into an affine :class:`~pybertini.container.ListOfVariableGroup` [#]_, and stuff it into ``sys``::
+
+	grp = pybertini.VariableGroup()
+	grp.append(x)
+	grp.append(y)
+	sys.add_variable_group(grp)
+
+Let's check that the degrees of our functions are correct::
+
+	d = sys.degrees()
+	assert(d[0]==2)  # f is degree 2 (highest power in any term is 2)
+	assert(d[1]==1)  # g is degree 1 (highest power in any term is 2)
+
+
+Aside -- a brief exploration into non-algebraic things
+---------------------------------------------------------
+
+
+What happens if we add a non-polynomial function to our system?
+
+::
+
+	sys.add_function(x**-1)  # happily accepts a non-polynomial function.  
+	sys.add_function( pybertini.function_tree.sin(x) )
+	d = sys.degrees()
+	assert(d[2]==-1) # unsurprising, but actually a coincidence
+	assert(d[3]==-1) # also -1.  anything non-polynomial is a negative number.  
+	# sin has no well-defined degree
+
+	# bertini uses negative degree to indicate non-polynomial
+
+
+correcting our system -- a return to algebraicness
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+We can indeed do homotopy continuation with a non-algebraic systems.  What we cannot do is form a start system that we can guarantee will track to all solutions of the target system.  (because of things like :math:`\sin(x)` having infinitely many solutions, etc)
+
+:: 
+
+	del sys #we mal-formed our system above by adding too many functions, and non-polynomial functions to it.
+	# so, we start over
+	sys = pybertini.System()
+	sys.add_variable_group(grp)
+	sys.add_function(f, 'f') #name the function in the system
+	sys.add_function(g) # default name
+
+
+
+Forming a start system
+=========================
+
+To solve our algebraic system ``sys``, we need a corresponding start system -- one with related structure, but that is actually solvable without too much trouble.  Bertini2 has several implemented options.  The most basic (easiest to form and solve) start system is the Total Degree (TD) start system.  It is implemented as a first-class object in Bertini and PyBertini.  It takes in a polynomial system as its argument, and self-forms.
+
+
+Above, we formed a target system, ``sys``.  Now, let's make a start system ``td``.  Later, we will couple it to ``sys``.
+It's trivial to make a total degree start system (:class:`~pybertini.system.start_system.TotalDegree`): ::
+
+	td = pybertini.system.start_system.TotalDegree(sys)
+
+Note that you have to pass in the target system into the constructor of the total degree, or you get an error.
+
+
+Wonderful, now we have an easy-to-solve system ``td``, the structure of which mirrors that of our target system.  Every start system comes with a method ``start_point_*`` for generating its start points, by integer index.
+
+::
+	
+	# generate the 1th (0-based offsets in python) start point
+	sp_d = td.start_point_d(1)# at double precision
+	
+	sp_mp = td.start_point_mp(1) # generate the 1th point at current default multiple precision
+	assert(pybertini.default_precision() == sp_mp[1].precision())
+
+
+Forming a homotopy
+==================
+
+
+We turn next to the act of path tracking.  This is the core computational method of numerical algebraic geometry, and it requires a continuous deformation between systems, called a "homotopy".  
+
+A homotopy in Numerical Algebraic Geometry glues together a start system and a target system, such that we can later "continue" from one into the other.   Observe:
+
+
+We couple ``sys`` and ``td``::
+
+	t = pybertini.Variable("t")     # make a path variable
+	homotopy = (1-t)*sys + t*td     # glue
+	homotopy.add_path_variable(t)   # indicate the path var
+
+Now, we have the minimum theoretical ingredients for solving a polynomial system using Numerical Algebraic Geometry: 
+
+#. a homotopy ``homotopy``, 
+#. a target system ``sys``, 
+#. and a start system ``td``.
+
+as well as a few other incidentals which will be implicitly used, such as a path variable ``t``.
+
+
+Tracking a single path
+======================
+
+There are three basic trackers available in PyBertini:
+
+
+#. Fixed double precision: :class:`~pybertini.tracking.DoublePrecisionTracker`
+#. Fixed multiple precision: :class:`~pybertini.tracking.MultiplePrecisionTracker`
+#. Adaptive precision: :class:`~pybertini.tracking.AMPTracker`
+
+Each brings its own advantages and disadvantages.  And, each has its ambient numeric type.
+
+Let's use the adaptive one, since adaptivity is generally a good trait to have.  ``AMPTracker`` uses variable-precision vectors and matrices in its ambient work -- that is, you feed it multiprecisions, and get back multiprecisions.  Internally, it will use double precision when it can, and higher when it has to.
+
+We associate a system with a tracker when we make it.  You cannot make a tracker without telling the tracker which system it will be tracking...
+
+::
+
+	tr = pybertini.tracking.AMPTracker(homotopy)
+	tr.tracking_tolerance(1e-5) # track the path to 5 digits or so
+
+	# adjust some stepping settings
+	stepping = pybertini.tracking.config.SteppingConfig()
+	stepping.max_step_size = pybertini.multiprec.Rational(1,13)
+
+	#then, set the config into the tracker.
+	tr.set_stepping(stepping)
+
+
+Once we feel comfortable with the configs (of which there are many, see the book or elsewhere in this site, perhaps), we can track a path.
+
+::
+
+	result = pybertini.multiprec.Vector()
+	tr.track_path(result, pybertini.multiprec.Complex(1), pybertini.multiprec.Complex(0), td.start_point_mp(0))
+
+Logging to inspect the path that was tracked
+---------------------------------------------
+
+
+Let's generate a log of what was computed along the way, first making an :mod:`observer <pybertini.tracking.observers>`, and then attaching it to the tracker.
+
+::
+
+	#make observer
+	g = pybertini.tracking.observers.amp.GoryDetailLogger()
+	
+	#attach
+	tr.add_observer(g)
+
+Re-running it, you should find a ton of stuff printed to the screen.
+
+::
+
+	result = pybertini.multiprec.Vector()
+	tr.track_path(result, pybertini.multiprec.Complex(1), pybertini.multiprec.Complex(0), td.start_point_mp(0))
+
+If you are going to keep tracking, but want to turn off the logging, remove the observer.::
+
+	tr.remove_observer(g)
+
+
+A complete tracking of paths
+=============================
+
+
+Now that we've tracked a single path, you might want to loop over all start points.  Awesome!  The next blob takes all the above, and puts it into a single blob.  Enjoy!
+
+
+.. testcode:: tracking_nonsingular_main
+	
+	import pybertini
+
+	x = pybertini.function_tree.symbol.Variable("x") #yes, you can make a variable not match its name...
+	y = pybertini.function_tree.symbol.Variable("y")
+	f = x**2 + y**2 -1
+	g = x+y
+
+	sys = pybertini.System()
+	sys.add_function(f, 'f')
+	sys.add_function(g)
+
+	grp = pybertini.VariableGroup()
+	grp.append(x)
+	grp.append(y)
+	sys.add_variable_group(grp)
+
+	td = pybertini.system.start_system.TotalDegree(sys)
+
+	t = pybertini.Variable("t")
+	homotopy = (1-t)*sys + t*td
+	homotopy.add_path_variable(t)
+
+	tr = pybertini.tracking.AMPTracker(homotopy)
+
+	#commented out for screen-saving.
+	#g = pybertini.tracking.observers.amp.GoryDetailLogger()
+	#tr.add_observer(g)  
+	# one could also pybertini.logging.init() and set a file name, 
+	# so it gets piped there instead of wherever Boost.Log goes by default.
+
+	tr.tracking_tolerance(1e-5) # track the path to 5 digits or so
+	tr.infinite_truncation_tolerance(1e5)
+	tr.predictor(pybertini.tracking.Predictor.RK4)
+	stepping = pybertini.tracking.config.SteppingConfig()
+	stepping.max_step_size = pybertini.multiprec.Rational(1,13)
+
+	# set the config into the tracker
+	tr.set_stepping(stepping)
+
+	results = [] # make an empty list into which to put the results
+	expected_code = pybertini.tracking.SuccessCode.Success
+	codes = []
+	for ii in range(td.num_start_points()):
+		results.append(pybertini.multiprec.Vector())
+		codes.append(tr.track_path(result=results[-1], start_time=pybertini.multiprec.Complex(1), end_time=pybertini.multiprec.Complex(0), start_point=td.start_point_mp(ii)))
+
+	tr.remove_observer(g)
+
+	print(codes == [expected_code]*2)
+
+.. testoutput:: tracking_nonsingular_main
+
+	True
+
+
+
+
+
+Footnotes
+---------
+
+.. [#]  Affinely-grouped variables live together in the same complex space, :math:`\mathbb{C}^N`.  The alternative is projectively-grouped variables, which live in a copy of :math:`\mathbb{P}^N`.

python/docs/source/tutorials/tutorials.rst

@@ -0,0 +1,13 @@
+🔦 Tutorials
+*****************
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Available tutorials
+
+
+   evaluation_cyclic
+   tracking_nonsingular
+   manual_endgame_usage
+

python/docs/source/zbib.rst

@@ -0,0 +1,4 @@
+📚 Bibliography
+********************
+
+.. bibliography:: ../../../doc_resources/bertini2.bib