Merge pull request #119 from 00krishna-opensource/add_docstrings

Building out LabelArrays docstrings.

Author: ChrisRackauckas

docs/pages.jl

@@ -2,9 +2,9 @@
 
 pages=[
     "Home" => "index.md",
+    "Example: Nice DiffEq Syntax Without A DSL" => "Example_dsl.md",
     "SLArrays" => "SLArrays.md",
     "LArrays" => "LArrays.md",
-    "Example: Nice DiffEq Syntax Without A DSL" => "Example_dsl.md",
     "Relation to NamedTuples" => "NamedTuples_relation.md",
     "Note_labelled_slices.md"
 ]

docs/src/Example_dsl.md

@@ -1,15 +1,33 @@
 # Example: Nice DiffEq Syntax Without A DSL
 
+Users of the SciML ecosystem are often solving large models with complicated
+states and/or hundreds or thousands of parameters. These models are implemented
+using arrays, and those arrays have traditionally been indexed by integers, 
+such as `p[1]` or `p[1:5]`. Numerical indexing is wonderful for small 
+models, but can quickly cause problems as models become bigger. It is easy to 
+forget which index corresponds to which reaction rate or which diffusion coeffient. 
+This confusion can lead to difficult to debug problems in a user's code. `LabelledArrays` 
+can make an important difference here. It is much easier to build a model using parameter 
+references such as `p.rate_nacl` or `p.probability_birth`, instead 
+of `p[26]` or `p[1026]`. Labelled arrays make both the development and debugging of models 
+much faster.  
+
 LabelledArrays.jl are a way to get DSL-like syntax without a macro. In this case,
 we can solve differential equations with labelled components by making use of
 labelled arrays, and always refer to the components by name instead of index.
 
-Let's solve the Lorenz equation. Using `@LVector`s, we can do:
+One key caveat is that users do not need to sacrifice performance when using 
+labelled arrays. Labelled arrays are as performant as traditional numerically 
+indexed arrays.
+
+Let's solve the Lorenz equation using an `LVector`s. `LVectors` are 
+mutable, hence we can use the non-allocating form of the `OrdinaryDiffEq` 
+API.
 
 ```julia
 using LabelledArrays, OrdinaryDiffEq
 
-function lorenz_f(du,u,p,t)
+function lorenz_f!(du,u,p,t)
   du.x = p.σ*(u.y-u.x)
   du.y = u.x*(p.ρ-u.z) - u.y
   du.z = u.x*u.y - p.β*u.z
@@ -18,13 +36,21 @@ end
 u0 = @LArray [1.0,0.0,0.0] (:x,:y,:z)
 p = @LArray [10.0, 28.0, 8/3]  (:σ,:ρ,:β)
 tspan = (0.0,10.0)
-prob = ODEProblem(lorenz_f,u0,tspan,p)
+prob = ODEProblem(lorenz_f!,u0,tspan,p)
 sol = solve(prob,Tsit5())
 # Now the solution can be indexed as .x/y/z as well!
 sol[10].x
 ```
 
-We can also make use of `@SLVector`:
+In the example above, we used an `LArray` to define the
+intial state `u0` as well as the parameter vector `p`.
+The reminder of the ODE solution steps are are no different
+that the original `DifferentialEquations` [tutorials](https://diffeq.sciml.ai/stable/tutorials/ode_example/#Example-2:-Solving-Systems-of-Equations).
+
+Alternatively, we can use an immutable `SLVector` to 
+implement the same equation. In this case, we need to 
+use the allocating form of the `OrdinaryDiffEq` API when
+defining our model equation.
 
 ```julia
 LorenzVector = @SLVector (:x,:y,:z)
@@ -42,4 +68,5 @@ p = LorenzParameterVector(10.0,28.0,8/3)
 tspan = (0.0,10.0)
 prob = ODEProblem(f,u0,tspan,p)
 sol = solve(prob,Tsit5())
-```
+```
+

docs/src/LArrays.md

@@ -1,60 +1,40 @@
 # LArrays
 
-The `LArrays`s are fully mutable arrays with labels. There is no performance
-loss by using the labelled instead of indexing. Using the macro with values
-and labels generates the labelled array with the given values:
+`LArrays` are fully mutable arrays with labels. There is no performance
+loss by using labelled indexing instead of purely numerical indexing. 
+Using the macro with values and labels generates the labelled array with
+the given values:
 
-```julia
-A = @LArray [1,2,3] (:a,:b,:c)
-A.a == 1
-```
-
-One can generate a labelled array with undefined values by instead giving
-the dimensions:
+Users interested in using labelled elements in their arrays should also 
+consider `ComponentArrays` from the 
+[ComponentArrays.jl](https://github.com/jonniedie/ComponentArrays.jl)
+library. `ComponentArrays` are well integrated into the SciML ecosystem. 
 
-```julia
-A = @LArray Float64 (2,2) (:a,:b,:c,:d)
-W = rand(2,2)
-A .= W
-A.d == W[2,2]
-```
+## `@LArray` and `@LVector` macros
 
-or using an `@LVector` shorthand:
+Macro constructors are convenient for building most `LArray` objects. An 
+`@LArray` may be of arbitrary dimension while an `@LVector` is a 
+one dimensional array. 
 
-```julia
-A = @LVector Float64 (:a,:b,:c,:d)
-A .= rand(4)
+```@docs
+@LArray
+@LVector
 ```
 
-As with `SLArray`, alternative constructors exist that use the keyword argument
-form:
+## `LArray` and `LVector` constructors
 
-```julia
-julia> LVector(a=1, b=2, c=3)
-3-element LArray{Int64,1,(:a, :b, :c)}:
- 1
- 2
- 3
+The original constructors for `LArray`s and `LVector`s are as 
+follows: 
 
-julia> LArray((2,2); a=1, b=2, c=3, d=4) # need to specify size as first argument
-2×2 LArray{Int64,2,(:a, :b, :c, :d)}:
- 1  3
- 2  4
+```@docs
+LArray
+LVector
 ```
+## Manipulating `LArrays` and `LVectors`
 
-One can also specify the indices directly.
-```julia
-julia> z = @LArray [1.,2.,3.] (a = 1:2, b = 2:3);
-julia> z.b
-2-element view(::Array{Float64,1}, 2:3) with eltype Float64:
- 2.0
- 3.0
-julia> z = @LArray [1 2; 3 4] (a = (2, :), b = 2:3);
-julia> z.a
-2-element view(::Array{Int64,2}, 2, :) with eltype Int64:
- 3
- 4
-```
+User may want a list of the labels or keys in an `LArray` or `LVector`.
+The `symbols(::LArray)` function returns a tuple of array labels.
 
-The labels of LArray and SLArray can be accessed 
-by function `symbols`, which returns a tuple of symbols.
+```@docs
+symbols
+```

docs/src/SLArrays.md

@@ -1,88 +1,35 @@
 # SLArrays
 
-The `SLArray` and `SLVector` macros are for creating static LabelledArrays.
-First you create the type and then you can use that constructor to generate
+The `SLArray` and `SLVector` macros create static LabelledArrays.
+First the user would create the array type, then use that constructor to generate
 instances of the labelled array.
 
-```julia
-ABC = @SLVector (:a,:b,:c)
-A = ABC(1,2,3)
-A.a == 1
+## `@SLArray` and `@SLVector` macros
 
-ABCD = @SLArray (2,2) (:a,:b,:c,:d)
-B = ABCD(1,2,3,4)
-B.c == 3
-B[2,2] == B.d
-```
-
-Here we have that `A == [1,2,3]` and for example `A.b == 2`. We can create a
-typed `SLArray` via:
-
-```julia
-SVType = @SLVector Float64 (:a,:b,:c)
-```
-
-Alternatively, you can also construct a static labelled array using the
-`SLVector` constructor by writing out the entries as keyword arguments:
+Macro constructors are convenient for building most `SLArray` objects. An 
+`@SLArray` may be of arbitrary dimension while an `@SLVector` is a 
+one dimensional array. 
 
-```julia
-julia> SLVector(a=1, b=2, c=3)
-3-element SLArray{Tuple{3},1,(:a, :b, :c),Int64}:
- 1
- 2
- 3
+```@docs
+@SLArray
+@SLVector
 ```
 
-For general N-dimensional labelled arrays, you need to specify the size
-(`Tuple{dim1,dim2,...}`) as the type parameter to the `SLArray` constructor:
+## `SLArray` and `SLVector` constructors
 
-```julia
-julia> SLArray{Tuple{2,2}}(a=1, b=2, c=3, d=4)
-2×2 SLArray{Tuple{2,2},2,(:a, :b, :c, :d),Int64}:
- 1  3
- 2  4
-```
-
-Constructing copies with some items changed is supported by
-a keyword constructor whose first argument is the source and
-additonal keyword arguments change several entries.
-
-```julia
-julia> v1 = SLVector(a=1.1, b=2.2, c=3.3);
-julia> v2 = SLVector(v1; b=20.20, c=30.30 )
-3-element SLArray{Tuple{3},Float64,1,3,(:a, :b, :c)}:
-  1.1
- 20.2
- 30.3
-```
+Alternatively, users can construct a static labelled array using the
+`SLVector` and `SLArrays` constructors by writing out the entries as keyword arguments:
 
-```julia
-julia> ABCD = @SLArray (2,2) (:a,:b,:c,:d);
-julia> B = ABCD(1,2,3,4);
-julia> B2 = SLArray(B; c=30 )
-2×2 SLArray{Tuple{2,2},Int64,2,4,(:a, :b, :c, :d)}:
- 1  30
- 2   4
+```@docs
+SLArray
+SLVector
 ```
 
-One can also specify the indices directly.
-```julia
-julia> EFG = @SLArray (2,2) (e=1:3, f=4, g=2:4);
-julia> y = EFG(1.0,2.5,3.0,5.0)
-2×2 SLArray{Tuple{2,2},Float64,2,4,(e = 1:3, f = 4, g = 2:4)}:
- 1.0  3.0
- 2.5  5.0
+## Manipulating `SLArrays` and `SLVectors`
 
-julia> y.g
-3-element view(reshape(::StaticArrays.SArray{Tuple{2,2},Float64,2,4}, 4), 2:4) with eltype Float64:
- 2.5
- 3.0
- 5.0
+Users may want a list of the labels or keys in an `SLArray` or `SLVector`.
+The `symbols(::SLArray)` function returns a tuple of array labels.
 
-julia> Arr = @SLArray (2, 2) (a = (2, :), b = 3);
-julia> z = Arr(1, 2, 3, 4);
-julia> z.a
-2-element view(::StaticArrays.SArray{Tuple{2,2},Int64,2,4}, 2, :) with eltype Int64:
- 2
- 4
+```@docs
+symbols(::SLArray)
 ```

docs/src/index.md

@@ -2,7 +2,7 @@
 
 LabelledArrays.jl is a package which provides arrays with labels, i.e. they are
 arrays which `map`, `broadcast`, and all of that good stuff, but their components
-are labelled. Thus for instance you can set that the second component is named
+are labelled. For instance, users can name the second component of an array to
 `:second` and retrieve it with `A.second`.
 
 ## Installation