Add State Space Documentation #639

mcm001 · 2020-04-27T16:08:44Z

This PR is associated with wpilibsuite/allwpilib#2494

WIP: State-space documentation, to go with the state-space-v2 PR to allwpilib. Things still to do:

Basic state-space and LQR documentation
Video Hosting and build pipeline for animations with manim
Documentation for pose estimators
(more) filter documentation for the EKF and UKF
Documentation for C++/Java examples

Daltz333 · 2020-04-27T19:24:08Z

/azp run

azure-pipelines · 2020-04-27T19:24:13Z

Pull request contains merge conflicts.

source/docs/software/state-space/state-space-observers.rst

source/docs/software/state-space/index.rst

source/docs/software/state-space/state-space-observers.rst

source/index.rst

source/docs/software/advanced-control/state-space/state-space-drivetrain-controllers.rst

source/docs/software/advanced-control/state-space/state-space-pose_state-estimators.rst

source/docs/software/advanced-control/state-space/state-space-intro.rst

source/docs/software/advanced-control/state-space/state-space-drivetrain-controllers.rst

calcmogul

We're going to need either a lot of glossary links or a whole section devoted to teaching terminology.

source/docs/software/advanced-control/state-space/state-space-drivetrain-controllers.rst

source/docs/software/advanced-control/state-space/state-space-flywheel-walkthrough.rst

source/docs/software/advanced-control/state-space/state-space-observers.rst

source/docs/software/advanced-control/state-space/state-space-flywheel-walkthrough.rst

Daltz333 · 2020-07-23T16:31:51Z

I'd like to see more usage tutorials.

Aka: If you want to solve X, this is how you do it with state-space
Additionally, don't commit the .idea files.

Starlight220

Math (LaTeX) formatting isn't done in tooltip content. Therefore some tooltips have "(\mathbf{y})", etc.
Some more reviews coming in a few days, after I read the rest of the docs.

source/docs/software/advanced-controls/state-space/state-space-intro.rst

modelmat

A few minor nitpicks and requests for clarification.

source/docs/software/advanced-controls/state-space/state-space-intro.rst

source/docs/software/advanced-controls/state-space/state-space-flywheel-walkthrough.rst

modelmat · 2020-09-23T07:41:59Z

source/docs/software/advanced-controls/state-space/state-space-flywheel-walkthrough.rst

+
+Kalman filters are used to filter our velocity measurements using our state-space model. As our flywheel model is linear, we can use a Kalman filter to estimate the flywheel's velocity. WPILib's Kalman filter takes a ``LinearSystem`` (which we found above), along with standard deviations of model and sensor measurements. We can adjust how "smooth" our state estimate is by adjusting these weights. Larger state standard deviations will cause the filter to "distrust" our state estimate and favor new measurements more highly, while larger measurement standard deviations will do the opposite. In the case of a flywheel we start with a state standard deviation of 3 rad/s and a measurement standard deviation of 0.01 rad/s. These values are up to the user to choose -- these weights produced a filter that was tolerant to some noise but whose state estimate quickly reacted to external disturbances for *a* flywheel -- and should be tuned to create a filter that behaves well for your specific flywheel. Graphing states, measurements, inputs, references, and outputs over time is a great visual way to tune Kalman filters.
+
+.. image:: images/filter_comparison.png


You can barely read the key on this graph. It's also (again) a very different style to the rest of the document and (most) of the other graphs.

The lines are also thin and hard to tell apart. It could be beneficial to have the x-axis range from [1600, 3000] to see more detail where the "action" happens.

The spinup part is actually the most important part, as it shows that the kalman filter can laglessly filter data. I'm not sure I have the program that generated that graph anymore

source/docs/software/advanced-controls/state-space/state-space-flywheel-walkthrough.rst

source/docs/software/advanced-controls/state-space/state-space-pose_state-estimators.rst

source/docs/software/advanced-controls/state-space/state-space-intro.rst

source/docs/software/advanced-controls/state-space/state-space-flywheel-walkthrough.rst

source/docs/software/advanced-controls/state-space/state-space-intro.rst

…-intro.rst Co-authored-by: Dalton Smith <daltzsmith@gmail.com>

…-intro.rst Co-authored-by: Prateek Machiraju <prateek.machiraju@gmail.com>

…-intro.rst Co-authored-by: Dalton Smith <daltzsmith@gmail.com>

source/docs/software/advanced-controls/state-space/state-space-intro.rst

…-intro.rst Co-authored-by: Tyler Veness <calcmogul@gmail.com>

source/docs/software/advanced-controls/state-space/state-space-observers.rst

* Recreate original graph in matplotlib * Use 4 subplots to show the differing behaviours of the four filters Also, add a minimum y-value so the behaviour of the filter is clear. * Move stdev information onto newline in axis title

…-observers.rst Co-authored-by: Tyler Veness <calcmogul@gmail.com>

stale

Daltz333 added the Type: New Article label Apr 28, 2020

prateekma reviewed May 12, 2020

View reviewed changes

Daltz333 reviewed May 12, 2020

View reviewed changes

Daltz333 requested changes May 13, 2020

View reviewed changes

source/index.rst Outdated Show resolved Hide resolved

prateekma reviewed May 14, 2020

View reviewed changes

prateekma reviewed May 15, 2020

View reviewed changes

calcmogul suggested changes May 15, 2020

View reviewed changes

source/docs/software/advanced-control/state-space/state-space-drivetrain-controllers.rst Outdated Show resolved Hide resolved

mcm001 force-pushed the state-space branch from bbdbe67 to 1610aff Compare May 19, 2020 05:49

prateekma reviewed May 19, 2020

View reviewed changes

calcmogul suggested changes May 19, 2020

View reviewed changes

calcmogul suggested changes May 20, 2020

View reviewed changes

source/docs/software/advanced-control/state-space/state-space-flywheel-walkthrough.rst Outdated Show resolved Hide resolved

mcm001 force-pushed the state-space branch 2 times, most recently from bdabe7d to 4011931 Compare May 20, 2020 15:57

Starlight220 reviewed Jul 23, 2020

View reviewed changes

source/docs/software/advanced-controls/state-space/state-space-intro.rst Outdated Show resolved Hide resolved

mcm001 force-pushed the state-space branch 3 times, most recently from 62991fc to 7d45f31 Compare August 25, 2020 20:07

mcm001 added 9 commits August 28, 2020 21:21

Start state-space docs

d705bc0

reeeeeeeeeeeeeeeeeeeeeeeeeee

7a1d619

Fix mathJax rendering

ada143b

Reorganize observer section

5974c70

add field vs robot frame diagram

dba773a

fix lint check

ce1abfe

fix some math

28c2451

fix plural stuff

b9258b8

add missing :

aa20b9b

Add notes on latency compensation

9d36b18

modelmat suggested changes Sep 23, 2020

View reviewed changes

mcm001 added 6 commits September 26, 2020 11:07

Hopefully clarify LQR

609cb50

add cpp include

c9f77db

Address review from @modelmat

2577dbd

Update state-space-intro.rst

6df67e6

oop

c322a5d

Whitespace

f14ec99

mcm001 force-pushed the state-space branch from 827c9a5 to f14ec99 Compare September 29, 2020 15:15

remove multiline latex

754ffdf

mcm001 force-pushed the state-space branch from 9773cd6 to 754ffdf Compare October 1, 2020 18:00

prateekma suggested changes Oct 1, 2020

View reviewed changes

Daltz333 previously requested changes Oct 1, 2020

View reviewed changes

source/docs/software/advanced-controls/state-space/state-space-intro.rst Outdated Show resolved Hide resolved

mcm001 and others added 3 commits October 1, 2020 11:47

Update source/docs/software/advanced-controls/state-space/state-space…

87eb8c4

…-intro.rst Co-authored-by: Dalton Smith <daltzsmith@gmail.com>

Update source/docs/software/advanced-controls/state-space/state-space…

9ef02fb

…-intro.rst Co-authored-by: Prateek Machiraju <prateek.machiraju@gmail.com>

Update source/docs/software/advanced-controls/state-space/state-space…

57be912

…-intro.rst Co-authored-by: Dalton Smith <daltzsmith@gmail.com>

calcmogul reviewed Oct 1, 2020

View reviewed changes

source/docs/software/advanced-controls/state-space/state-space-intro.rst Outdated Show resolved Hide resolved

Daltz333 changed the title ~~[WIP] State space~~ Add State Space Documentation Oct 1, 2020

mcm001 and others added 2 commits October 1, 2020 12:09

Update source/docs/software/advanced-controls/state-space/state-space…

9f78f0e

…-intro.rst Co-authored-by: Tyler Veness <calcmogul@gmail.com>

Address review

5618eea

calcmogul suggested changes Oct 2, 2020

View reviewed changes

source/docs/software/advanced-controls/state-space/state-space-observers.rst Outdated Show resolved Hide resolved

calcmogul suggested changes Oct 2, 2020

View reviewed changes

source/docs/software/advanced-controls/state-space/state-space-observers.rst Show resolved Hide resolved

mcm001 and others added 3 commits October 2, 2020 17:39

Update state-space-intro.rst

801a11b

Update source/docs/software/advanced-controls/state-space/state-space…

c3e1516

…-observers.rst Co-authored-by: Tyler Veness <calcmogul@gmail.com>

Daltz333 requested a review from calcmogul October 3, 2020 21:48

calcmogul approved these changes Oct 3, 2020

View reviewed changes

Daltz333 approved these changes Oct 3, 2020

View reviewed changes

Daltz333 merged commit 9f9a01c into wpilibsuite:master Oct 3, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add State Space Documentation #639

Add State Space Documentation #639

mcm001 commented Apr 27, 2020 •

edited

Daltz333 commented Apr 27, 2020

azure-pipelines bot commented Apr 27, 2020

calcmogul left a comment

Daltz333 commented Jul 23, 2020

Starlight220 left a comment •

edited

modelmat left a comment

modelmat Sep 23, 2020

mcm001 Sep 27, 2020 •

edited


		Kalman filters are used to filter our velocity measurements using our state-space model. As our flywheel model is linear, we can use a Kalman filter to estimate the flywheel's velocity. WPILib's Kalman filter takes a ``LinearSystem`` (which we found above), along with standard deviations of model and sensor measurements. We can adjust how "smooth" our state estimate is by adjusting these weights. Larger state standard deviations will cause the filter to "distrust" our state estimate and favor new measurements more highly, while larger measurement standard deviations will do the opposite. In the case of a flywheel we start with a state standard deviation of 3 rad/s and a measurement standard deviation of 0.01 rad/s. These values are up to the user to choose -- these weights produced a filter that was tolerant to some noise but whose state estimate quickly reacted to external disturbances for a flywheel -- and should be tuned to create a filter that behaves well for your specific flywheel. Graphing states, measurements, inputs, references, and outputs over time is a great visual way to tune Kalman filters.

		.. image:: images/filter_comparison.png

Add State Space Documentation #639

Add State Space Documentation #639

Conversation

mcm001 commented Apr 27, 2020 • edited

Daltz333 commented Apr 27, 2020

azure-pipelines bot commented Apr 27, 2020

calcmogul left a comment

Choose a reason for hiding this comment

Daltz333 commented Jul 23, 2020

Starlight220 left a comment • edited

Choose a reason for hiding this comment

modelmat left a comment

Choose a reason for hiding this comment

modelmat Sep 23, 2020

Choose a reason for hiding this comment

mcm001 Sep 27, 2020 • edited

Choose a reason for hiding this comment

mcm001 commented Apr 27, 2020 •

edited

Starlight220 left a comment •

edited

mcm001 Sep 27, 2020 •

edited