Merge pull request #365 from JuliaReach/schillic/doc_vectorfield

Document plotting of vector fields

Author: schillic

docs/Project.toml

@@ -2,8 +2,10 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 LazySets = "b4f0291d-fe17-52bc-9479-3d1a343d9043"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 
 [compat]
 Documenter = "1"
 DocumenterCitations = "1.3"
 LazySets = "5 - 6"
+Plots = "1"

docs/make.jl

@@ -1,5 +1,7 @@
+ENV["GKSwstype"] = "100"  # prevent plots from opening interactively
+
 using Documenter, MathematicalSystems, DocumenterCitations
-import LazySets
+import LazySets, Plots
 
 DocMeta.setdocmeta!(MathematicalSystems, :DocTestSetup,
                     :(using MathematicalSystems); recursive=true)
@@ -14,10 +16,11 @@ makedocs(; sitename="MathematicalSystems.jl",
          pagesonly=true,
          plugins=[bib],
          pages=["Home" => "index.md",
-                "Manual" => Any["Overview of System Types" => "man/systems.md"],
-                "Library" => Any["Types"     => "lib/types.md",
-                                 "Methods"   => "lib/methods.md",
-                                 "Internals" => "lib/internals.md"],
+                "Manual" => ["Overview of System Types" => "man/systems.md"
+                             "Vector Fields"            => "man/vectorfield.md"],
+                "Library" => ["Types"     => "lib/types.md",
+                              "Methods"   => "lib/methods.md",
+                              "Internals" => "lib/internals.md"],
                 "Bibliography" => "bibliography.md",
                 "About" => "about.md"])
 

docs/src/man/vectorfield.md

@@ -0,0 +1,51 @@
+# Vector Fields
+
+Vector fields can be plotted via the (unexported)
+[`MathematicalSystems.VectorField`](@ref) type. First we give an example where
+the vector field is represented by a function that takes a two-dimensional state
+vector and returns the corresponding two-dimensional (derivative) vector:
+
+```@example vector_fields
+using MathematicalSystems, Plots
+
+f(x) = [2*x[2], -x[1]];
+
+V = MathematicalSystems.VectorField(f);
+
+plot(V)
+```
+
+Alternatively, one can also pass a continuous system:
+
+```@example vector_fields
+S = LinearContinuousSystem([0.0 2; -1 0])
+
+V = MathematicalSystems.VectorField(S);
+
+plot(V)
+```
+
+The above example shows the default grid of 20×20 points for the range
+``[-3, 3] × [-3, 3]``. A custom grid can be passed via the `grid_points` keyword
+argument, which takes a pair `(x, y)` whose entries specify ranges for the x and
+y coordinates of the grid points. For instance:
+
+```@example vector_fields
+xrange = range(-1, stop=3, length=5);
+
+yrange = range(-5, stop=2, length=8);
+
+plot(V; grid_points=(xrange, yrange))
+```
+
+The implementation supports projective plotting of vector fields with more than
+two output dimensions. For that, one can use the `dims` keyword argument to pass
+a vector with the two dimensions to plot:
+
+```@example vector_fields
+f(x) = [2*x[2], 42, -x[1]];
+
+V = MathematicalSystems.VectorField(f);
+
+plot(V; dims=[1, 3])
+```

src/vector_field.jl

@@ -126,11 +126,11 @@ end
 """
     VectorField{T<:Function}
 
-Type that computes the vector field of an `AbstractContinuousSystem`.
+Type that represents the vector field of an `AbstractContinuousSystem`.
 
 ### Fields
 
-- `field`  -- function for calculating the vector field
+- `field` -- function for evaluating the vector field at a given point
 """
 struct VectorField{T<:Function}
     field::T