Merge pull request #99 from decargroup/add_tutorial

Add tutorial

.gitignore

@@ -53,5 +53,6 @@ Thumbs.db
 *.egg-info
 docs/build/
 docs/_build/
-docs/source/_autosummary
-dev/
+docs/source/_autosummary/
+dev/
+build/

README.rst

@@ -28,7 +28,7 @@ The core idea behind this project is to abstract-away the state definition such
 - Monte Carlo experiment executor with result aggregation
 - A preintegration module for linear, wheel odometry, and IMU process models
 
-By implementing a few classes, the user can model almost any problem. Documentation can be found by https://decargroup.github.io/navlie
+By implementing a few classes, the user can model almost any problem. Documentation can be found at https://decargroup.github.io/navlie
 
 Setup
 -----
@@ -140,14 +140,14 @@ As another more complicated example, a state object belonging to the SE(3) Lie g
 
 Process and Measurement Models
 ------------------------------
-.. image:: system_diagram.png
+.. image:: ./docs/source/system_diagram.png
     :alt: System Diagram
 
 There are a few more core types in this package. The main ones are the `ProcessModel` and `MeasurementModel` classes. Both of these are abstract classes requiring the user to implement
 
-    - an `evaluate()` method, 
-    - a `jacobian()` method,
-    - and a `covariance()` method.
+- an `evaluate()` method, 
+- a `covariance()` method,
+- and optionally a `jacobian()` method.
 
 For example, a simple "single integrator" (velocity input) model can be implemented as follows:
 
@@ -172,7 +172,7 @@ For example, a simple "single integrator" (velocity input) model can be implemen
 
         def jacobian(self, x: VectorState, u: VectorInput, dt: float) -> np.ndarray:
             """
-            Jacobian of the process model with respect to the state.
+            (optional) Jacobian of the process model with respect to the state.
             """
             return np.identity(x.dof)
 
@@ -212,7 +212,7 @@ Similarly, a single distance-to-landmark measurement model can be implemented as
             return self._R
 
 
-In fact, for both `ProcessModel` and `MeasurementModel`, subclasses will inherit a finite-difference numerical differentiation method `jacobian_fd()`, that allows for a seamless way to check your `jacobian()` implementation! (`evaluate()` method must be implemented for this to work, see some of the files in `tests/` for an example of this.)
+In fact, for both `ProcessModel` and `MeasurementModel`, subclasses will inherit a finite-difference numerical differentiation method `jacobian_fd()`, which also serves as the default implementation if `jacobian` is not overriden. Nevertheless, it allows for an easy way to check your `jacobian()` implementation! (`evaluate()` method must be implemented for this to work, see some of the files in `tests/` for an example of this.)
 
 Built-in Library
 ----------------
@@ -274,17 +274,21 @@ The goal of this project is to write general algorithms that work for any implem
 
 Contributing to the Documentation
 ---------------------------------
-The documentation is automatically generated from python docstrings using `sphinx`, which can be installed by following these instructions: https://www.sphinx-doc.org/en/master/usage/installation.html.
+You must first install the dependencies for the documentation. This can be done by running
 
-After sphinx is installed change to the `./docs/` directory and run 
+.. code-block:: bash
+
+    pip install -r docs/requirements.txt
+
+After this is done, change to the `./docs/` directory and run 
 
 .. code-block:: bash
 
     make html
 
-and the documentation will be updated (you may need to install some dependencies... sorry. just follow the error prompts and install whats required. TODO).  In terms of actually writing documentation, we use the numpy format, which can be seen in some of the existing docstrings in the code, and can be used as a template. 
+and the documentation will be updated, and viewable by opening the ``docs/index.html`` file in your browser.  In terms of actually writing documentation, we use the numpy format, which can be seen in some of the existing docstrings in the code, and used as a template. 
 
-Alternatively and prefereably, install the autoDocstring extension for VSCode: https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring and change the docstring format in the settings to `numpy`.
+Alternatively and prefereably, install the `autoDocstring extension for VSCode. <https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring>` and change the docstring format in the settings to `numpy`.
 
 
 

docs/source/index.rst

@@ -8,30 +8,37 @@
    :hidden:
 
    Home <self>
-   Tutorial <tutorial>
+   Tutorial <tutorial.rst>
    API <api>
 
 
-Welcome to navlie's documentation!
-----------------------------------
+Welcome to navlie!
+------------------
 
-The core idea behind this project is to abstract-away the state definition such that a single estimator implementation can operate on a variety of state manifolds, such as the usual vector space, and any Lie group. At the moment, algorithms and features of this package include:
+navlie is a state estimation package specifically designed for both traditional and Lie-group-based estimation problems! 
+
+The core idea behind this project is to use abstraction in such a way that both traditional and Lie-group-based problems fall under the exact same interface. Using this, a single estimator implementation can operate on a variety of state definitions, such as the usual vector space, and any Lie group. We allow the user to define their custom state, process model, and measurement models, after which they will have a variety of algorithms available to them, including:
 
 - Extended Kalman Filter
 - Iterated Extended Kalman Filter
 - Sigmapoint Kalman Filters (Unscented, Spherical Cubature, Gauss-Hermite)
 - Interacting Multiple Model Filter
 - Batch MAP Estimation
+
+In addition, navlie contains
+
 - A large collection of common process and measurement models
-- Out-of-the-box on-manifold numerical jacobian using finite differencing
+- Out-of-the-box on-manifold numerical Jacobians using finite differencing
 - Various utils for plotting, error, and consistency evaluation
 - Monte Carlo experiment executor with result aggregation
 - A preintegration module for linear, wheel odometry, and IMU process models
 
-By implementing a few classes, the user can model almost any problem. Documentation can be found by https://decargroup.github.io/navlie
+By implementing a few classes, the user can model a large variety of problems. The following diagram summarizes the abstraction
+
+.. image:: ./system_diagram.png
+   :width: 100%
+   :align: center
 
-Setup
------
 
 Installation
 ^^^^^^^^^^^^
@@ -40,10 +47,11 @@ Clone this repo, change to its directory, and execute
 
 .. code-block:: bash
 
-    pip install -e .
+   git clone git@github.com:decargroup/navlie.git 
+   cd navlie && pip install -e .
 
-This command should automatically install all dependencies, including our package `pymlg` (found at https://github.com/decargroup/pymlg) for back-end Lie group mathematical operations.
+This command should automatically install all dependencies, including our package `pymlg <https://github.com/decargroup/pymlg>`_ for back-end Lie group mathematical operations. 
 
 Examples
 ^^^^^^^^
-Some starting examples running EKFs can be found in the `examples/` folder. Simply run these as python3 scripts 
+A more in-depth `tutorial <tutorial.rst>`_ can be found on this website, but there are also many examples found in the `examples/` folder. Simply run these as python3 scripts.

docs/source/tutorial.rst

@@ -0,0 +1,26 @@
+
+Getting Started
+---------------
+
+Welcome to the navlie tutorial! The following few pages will go through a toy localization problem, where we will be running state estimation algorithms using navlie's framework. The first step is to install this package. This should be done by directly cloning the git repo and performing a local pip install:
+
+.. code-block:: bash
+
+   git clone git@github.com:decargroup/navlie.git 
+   cd navlie && pip install -e .
+
+All the dependencies should get installed by this command and the package should now be ready to use. Use the column on the left to go to next page of the tutorial.
+
+
+.. note::
+
+   Although this package is currently registed with PyPi, installation via ``pip install navlie`` will not work. We're still figuring out how to set this up properly. Sorry! Feel free to help.
+
+
+.. toctree::
+   :hidden:
+
+   1. Getting Started <self>
+   2. Toy Problem - Traditional <./tutorial/traditional.ipynb>
+   3. Toy Problem - Lie groups <./tutorial/lie_groups.ipynb>
+   4. Specifying Jacobians <./tutorial/jacobians.ipynb>