From d178ab1d67f22ac6c5aa747bd27da67459909759 Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 13 Feb 2023 22:06:39 +0100 Subject: [PATCH 1/3] LanguageTool --- docs/src/Example_dsl.md | 10 +++++----- docs/src/LArrays.md | 2 +- docs/src/NamedTuples_relation.md | 2 +- docs/src/Note_labelled_slices.md | 2 +- docs/src/SLArrays.md | 4 ++-- src/larray.jl | 2 +- src/slarray.jl | 10 +++++----- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/src/Example_dsl.md b/docs/src/Example_dsl.md index e184196..e814c20 100644 --- a/docs/src/Example_dsl.md +++ b/docs/src/Example_dsl.md @@ -1,11 +1,11 @@ # 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 +states and 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. +forget which index corresponds to which reaction rate or which diffusion coefficient. 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 @@ -21,7 +21,7 @@ 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` +mutable. Hence, we can use the non-allocating form of the `OrdinaryDiffEq` API. ```julia @@ -43,8 +43,8 @@ sol[10].x ``` 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 +initial state `u0` as well as the parameter vector `p`. +The reminder of the ODE solution steps are no different that the original `DifferentialEquations` [tutorials](https://docs.sciml.ai/DiffEqDocs/stable/tutorials/ode_example/#Example-2:-Solving-Systems-of-Equations). Alternatively, we can use an immutable `SLVector` to diff --git a/docs/src/LArrays.md b/docs/src/LArrays.md index 8043cbf..6ec5677 100644 --- a/docs/src/LArrays.md +++ b/docs/src/LArrays.md @@ -13,7 +13,7 @@ library. `ComponentArrays` are well integrated into the SciML ecosystem. ## `@LArray` and `@LVector` macros Macro constructors are convenient for building most `LArray` objects. An -`@LArray` may be of arbitrary dimension while an `@LVector` is a +`@LArray` may be of arbitrary dimension, while an `@LVector` is a one dimensional array. ```@docs diff --git a/docs/src/NamedTuples_relation.md b/docs/src/NamedTuples_relation.md index 131bdb5..a9a2392 100644 --- a/docs/src/NamedTuples_relation.md +++ b/docs/src/NamedTuples_relation.md @@ -38,7 +38,7 @@ creates an iterator that is functionally the same as for each label of the array. There are some crucial differences between a labelled array and -a named tuple. Labelled arrays can have any dimensions while +a named tuple. Labelled arrays can have any dimensions, while named tuples are always 1D. A named tuple can have different types on each element, while an `SLArray` can only have one element type and furthermore it has the actions of a static vector. diff --git a/docs/src/Note_labelled_slices.md b/docs/src/Note_labelled_slices.md index 8381d1e..e982111 100644 --- a/docs/src/Note_labelled_slices.md +++ b/docs/src/Note_labelled_slices.md @@ -1,5 +1,5 @@ # Note: Labelled slices This functionality has been removed from LabelledArrays.jl, but can -replicated with the same compile-time performance and indexing syntax +be replicated with the same compile-time performance and indexing syntax using [DimensionalData.jl](https://github.com/rafaqz/DimensionalData.jl). \ No newline at end of file diff --git a/docs/src/SLArrays.md b/docs/src/SLArrays.md index 28cd93b..9d990be 100644 --- a/docs/src/SLArrays.md +++ b/docs/src/SLArrays.md @@ -1,13 +1,13 @@ # SLArrays The `SLArray` and `SLVector` macros create static LabelledArrays. -First the user would create the array type, then use that constructor to generate +First, the user would create the array type, then use that constructor to generate instances of the labelled array. ## `@SLArray` and `@SLVector` macros Macro constructors are convenient for building most `SLArray` objects. An -`@SLArray` may be of arbitrary dimension while an `@SLVector` is a +`@SLArray` may be of arbitrary dimension, while an `@SLVector` is a one dimensional array. ```@docs diff --git a/src/larray.jl b/src/larray.jl index e682750..eece533 100644 --- a/src/larray.jl +++ b/src/larray.jl @@ -285,7 +285,7 @@ end """ symbols(::LArray) -Returns the labels of the `LArray` . +Returns the labels of the `LArray`. For example: diff --git a/src/slarray.jl b/src/slarray.jl index d71c5a5..8c53aa9 100644 --- a/src/slarray.jl +++ b/src/slarray.jl @@ -57,7 +57,7 @@ SLArray{::Tuple}(::NamedTuple) SLArray{::Tuple}(kwargs) ``` -These are the standard constructors for `SLArray`. For general N-dimensional +These are the standard constructors for `SLArray`. For general N-dimensional labelled arrays, users need to specify the size (`Tuple{dim1,dim2,...}`) in the type parameter to the `SLArray` constructor: @@ -129,8 +129,8 @@ julia> v2 = SLVector(v1; b=20.20, c=30.30 ) Additional examples: ```julia -SLVector((a=1, b=2)) -SLVector(a=1, b=2) +SLVector((a=1, b=2)) +SLVector(a=1, b=2) ``` """ SLVector(tup::NamedTuple) = SLArray{Tuple{length(tup)}}(tup) @@ -271,7 +271,7 @@ end The macro creates a labelled static vector with element type `ElType`, and names from `Names`. If no eltype is given, then the eltype is determined from the values in the constructor. -The array size is found from the input data. +The array size is found from the input data. For example: @@ -304,7 +304,7 @@ end """ symbols(::SLArray) -Returns the labels of the `SLArray` . +Returns the labels of the `SLArray`. For example: ```julia From 0e20b40b2e9f2ec601cc4a5d86dc60dd6f18befc Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 13 Feb 2023 22:11:43 +0100 Subject: [PATCH 2/3] strict --- docs/make.jl | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 9d787b9..2ef2a9f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -8,7 +8,15 @@ include("pages.jl") makedocs(sitename = "LabelledArrays.jl", authors = "Chris Rackauckas", modules = [LabelledArrays], - clean = true, doctest = false, + clean = true, doctest = false, linkcheck = true, + strict = [ + :doctest, + :linkcheck, + :parse_error, + :example_block, + # Other available options are + # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block + ], format = Documenter.HTML(analytics = "UA-90474609-3", assets = ["assets/favicon.ico"], canonical = "https://docs.sciml.ai/LabelledArrays/stable/"), From 907d5e437c74158b3d6da26c49a3811cf5bffaea Mon Sep 17 00:00:00 2001 From: ArnoStrouwen Date: Mon, 13 Feb 2023 22:49:44 +0100 Subject: [PATCH 3/3] format markdown --- .JuliaFormatter.toml | 3 +- LICENSE.md | 37 ++++----- README.md | 133 +++++++++++++++++-------------- docs/src/Example_dsl.md | 73 +++++++++-------- docs/src/LArrays.md | 21 ++--- docs/src/NamedTuples_relation.md | 16 ++-- docs/src/Note_labelled_slices.md | 6 +- docs/src/SLArrays.md | 8 +- docs/src/index.md | 50 ++++++++---- src/larray.jl | 32 +++++--- src/slarray.jl | 52 +++++++----- 11 files changed, 234 insertions(+), 197 deletions(-) diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml index 453925c..9c79359 100644 --- a/.JuliaFormatter.toml +++ b/.JuliaFormatter.toml @@ -1 +1,2 @@ -style = "sciml" \ No newline at end of file +style = "sciml" +format_markdown = true \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md index dec5eb5..a315925 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,40 +1,33 @@ The LabelledArrays.jl package is licensed under the MIT "Expat" License: > Copyright (c) 2017: Christopher Rackauckas. -> -> +> > Permission is hereby granted, free of charge, to any person obtaining a copy -> +> > of this software and associated documentation files (the "Software"), to deal -> +> > in the Software without restriction, including without limitation the rights -> +> > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -> +> > copies of the Software, and to permit persons to whom the Software is -> +> > furnished to do so, subject to the following conditions: -> -> -> +> > The above copyright notice and this permission notice shall be included in all -> +> > copies or substantial portions of the Software. -> -> -> +> > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -> +> > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -> +> > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -> +> > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -> +> > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -> +> > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -> +> > SOFTWARE. -> -> diff --git a/README.md b/README.md index 320e875..13b3cc7 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![codecov](https://codecov.io/gh/SciML/LabelledArrays.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/LabelledArrays.jl) [![Build Status](https://github.com/SciML/LabelledArrays.jl/workflows/CI/badge.svg)](https://github.com/SciML/LabelledArrays.jl/actions?query=workflow%3ACI) -[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) +[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac) [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) # About @@ -19,10 +19,12 @@ are labelled. Thus for instance you can set that the second component is named ## How to install The package can be installed from this repository by + ```julia -> using Pkg -> Pkg.add("LabelledArrays") +using Pkg +Pkg.add("LabelledArrays") ``` + ## Tutorials and Documentation For information on using the package, @@ -37,28 +39,28 @@ First you create the type and then you can use that constructor to generate instances of the labelled array. ```julia -ABC = @SLVector (:a,:b,:c) -A = ABC(1,2,3) +ABC = @SLVector (:a, :b, :c) +A = ABC(1, 2, 3) A.a == 1 -ABCD = @SLArray (2,2) (:a,:b,:c,:d) -B = ABCD(1,2,3,4) +ABCD = @SLArray (2, 2) (:a, :b, :c, :d) +B = ABCD(1, 2, 3, 4) B.c == 3 -B[2,2] == B.d +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) +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: ```julia -julia> SLVector(a=1, b=2, c=3) +julia> SLVector(a = 1, b = 2, c = 3) 3-element SLArray{Tuple{3},1,(:a, :b, :c),Int64}: 1 2 @@ -69,7 +71,7 @@ For general N-dimensional labelled arrays, you need to specify the size (`Tuple{dim1,dim2,...}`) as the type parameter to the `SLArray` constructor: ```julia -julia> SLArray{Tuple{2,2}}(a=1, b=2, c=3, d=4) +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 @@ -80,8 +82,9 @@ 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 ) +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 @@ -89,18 +92,22 @@ julia> v2 = SLVector(v1; b=20.20, c=30.30 ) ``` ```julia -julia> ABCD = @SLArray (2,2) (:a,:b,:c,:d); -julia> B = ABCD(1,2,3,4); -julia> B2 = SLArray(B; c=30 ) +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 ``` 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) +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 @@ -112,7 +119,9 @@ julia> y.g 5.0 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 @@ -126,7 +135,7 @@ loss by using the labelled instead of 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 = @LArray [1, 2, 3] (:a, :b, :c) A.a == 1 ``` @@ -134,16 +143,16 @@ One can generate a labelled array with undefined values by instead giving the dimensions: ```julia -A = @LArray Float64 (2,2) (:a,:b,:c,:d) -W = rand(2,2) +A = @LArray Float64 (2, 2) (:a, :b, :c, :d) +W = rand(2, 2) A .= W -A.d == W[2,2] +A.d == W[2, 2] ``` or using an `@LVector` shorthand: ```julia -A = @LVector Float64 (:a,:b,:c,:d) +A = @LVector Float64 (:a, :b, :c, :d) A .= rand(4) ``` @@ -151,38 +160,39 @@ As with `SLArray`, alternative constructors exist that use the keyword argument form: ```julia -julia> LVector(a=1, b=2, c=3) +julia> LVector(a = 1, b = 2, c = 3) 3-element LArray{Int64,1,(:a, :b, :c)}: 1 2 3 -julia> LArray((2,2); a=1, b=2, c=3, d=4) # need to specify size as first argument +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 ``` One can also specify the indices directly. + ```julia -julia> z = @LArray [1.,2.,3.] (a = 1:2, b = 2:3); +julia> z = @LArray [1.0, 2.0, 3.0] (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 ``` -The labels of LArray and SLArray can be accessed +The labels of LArray and SLArray can be accessed by function `symbols`, which returns a tuple of symbols. - - - ## Example: Nice DiffEq Syntax Without A DSL LabelledArrays.jl are a way to get DSL-like syntax without a macro. In this case, @@ -194,17 +204,17 @@ Let's solve the Lorenz equation. Using `@LVector`s, we can do: ```julia using LabelledArrays, OrdinaryDiffEq -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 +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 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) -sol = solve(prob,Tsit5()) +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) +sol = solve(prob, Tsit5()) # Now the solution can be indexed as .x/y/z as well! sol[10].x ``` @@ -212,21 +222,21 @@ sol[10].x We can also make use of `@SLVector`: ```julia -LorenzVector = @SLVector (:x,:y,:z) -LorenzParameterVector = @SLVector (:σ,:ρ,:β) - -function f(u,p,t) - x = p.σ*(u.y-u.x) - y = u.x*(p.ρ-u.z) - u.y - z = u.x*u.y - p.β*u.z - LorenzVector(x,y,z) +LorenzVector = @SLVector (:x, :y, :z) +LorenzParameterVector = @SLVector (:σ, :ρ, :β) + +function f(u, p, t) + x = p.σ * (u.y - u.x) + y = u.x * (p.ρ - u.z) - u.y + z = u.x * u.y - p.β * u.z + LorenzVector(x, y, z) end -u0 = LorenzVector(1.0,0.0,0.0) -p = LorenzParameterVector(10.0,28.0,8/3) -tspan = (0.0,10.0) -prob = ODEProblem(f,u0,tspan,p) -sol = solve(prob,Tsit5()) +u0 = LorenzVector(1.0, 0.0, 0.0) +p = LorenzParameterVector(10.0, 28.0, 8 / 3) +tspan = (0.0, 10.0) +prob = ODEProblem(f, u0, tspan, p) +sol = solve(prob, Tsit5()) ``` ## Relation to NamedTuples @@ -234,29 +244,29 @@ sol = solve(prob,Tsit5()) Julia's Base has NamedTuples in v0.7+. They are constructed as: ```julia -p = (σ = 10.0,ρ = 28.0,β = 8/3) +p = (σ = 10.0, ρ = 28.0, β = 8 / 3) ``` and they support `p[1]` and `p.σ` as well. The `LVector`, `SLVector`, `LArray` and `SLArray` constructors also support named tuples as their arguments: ```julia -julia> LVector((a=1, b=2)) +julia> LVector((a = 1, b = 2)) 2-element LArray{Int64,1,(:a, :b)}: 1 2 -julia> SLVector((a=1, b=2)) +julia> SLVector((a = 1, b = 2)) 2-element SLArray{Tuple{2},1,(:a, :b),Int64}: 1 2 -julia> LArray((2,2), (a=1, b=2, c=3, d=4)) +julia> LArray((2, 2), (a = 1, b = 2, c = 3, d = 4)) 2×2 LArray{Int64,2,(:a, :b, :c, :d)}: 1 3 2 4 -julia> SLArray{Tuple{2,2}}((a=1, b=2, c=3, d=4)) +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 @@ -269,18 +279,17 @@ creates an iterator that is functionally the same as for each label of the array. There are some crucial differences between a labelled array and -a named tuple. Labelled arrays can have any dimensions while +a named tuple. Labelled arrays can have any dimensions while named tuples are always 1D. A named tuple can have different types on each element, while an `SLArray` can only have one element type and furthermore it has the actions of a static vector. -As a result `SLArray` has less element type information, which +As a result `SLArray` has less element type information, which improves compilation speed while giving more vector functionality than a NamedTuple. `LArray` also only has a single element type and, unlike a named tuple, is mutable. - ## Note: Labelled slices -This functionality has been removed from LabelledArrays.jl, but can -replicated with the same compile-time performance and indexing syntax +This functionality has been removed from LabelledArrays.jl, but can +replicated with the same compile-time performance and indexing syntax using [DimensionalData.jl](https://rafaqz.github.io/DimensionalData.jl/stable/). diff --git a/docs/src/Example_dsl.md b/docs/src/Example_dsl.md index e814c20..780e4a8 100644 --- a/docs/src/Example_dsl.md +++ b/docs/src/Example_dsl.md @@ -2,42 +2,42 @@ Users of the SciML ecosystem are often solving large models with complicated states and 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 coefficient. -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. +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 coefficient. +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. -One key caveat is that users do not need to sacrifice performance when using -labelled arrays. Labelled arrays are as performant as traditional numerically +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` +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) - 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 +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 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) -sol = solve(prob,Tsit5()) +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) +sol = solve(prob, Tsit5()) # Now the solution can be indexed as .x/y/z as well! sol[10].x ``` @@ -47,26 +47,25 @@ initial state `u0` as well as the parameter vector `p`. The reminder of the ODE solution steps are no different that the original `DifferentialEquations` [tutorials](https://docs.sciml.ai/DiffEqDocs/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 +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) -LorenzParameterVector = @SLVector (:σ,:ρ,:β) +LorenzVector = @SLVector (:x, :y, :z) +LorenzParameterVector = @SLVector (:σ, :ρ, :β) -function f(u,p,t) - x = p.σ*(u.y-u.x) - y = u.x*(p.ρ-u.z) - u.y - z = u.x*u.y - p.β*u.z - LorenzVector(x,y,z) +function f(u, p, t) + x = p.σ * (u.y - u.x) + y = u.x * (p.ρ - u.z) - u.y + z = u.x * u.y - p.β * u.z + LorenzVector(x, y, z) end -u0 = LorenzVector(1.0,0.0,0.0) -p = LorenzParameterVector(10.0,28.0,8/3) -tspan = (0.0,10.0) -prob = ODEProblem(f,u0,tspan,p) -sol = solve(prob,Tsit5()) +u0 = LorenzVector(1.0, 0.0, 0.0) +p = LorenzParameterVector(10.0, 28.0, 8 / 3) +tspan = (0.0, 10.0) +prob = ODEProblem(f, u0, tspan, p) +sol = solve(prob, Tsit5()) ``` - diff --git a/docs/src/LArrays.md b/docs/src/LArrays.md index 6ec5677..a055a6a 100644 --- a/docs/src/LArrays.md +++ b/docs/src/LArrays.md @@ -1,20 +1,20 @@ # LArrays `LArrays` are fully mutable arrays with labels. There is no performance -loss by using labelled indexing instead of purely numerical indexing. +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: -Users interested in using labelled elements in their arrays should also -consider `ComponentArrays` from the +Users interested in using labelled elements in their arrays should also +consider `ComponentArrays` from the [ComponentArrays.jl](https://docs.sciml.ai/ComponentArrays/stable/) -library. `ComponentArrays` are well integrated into the SciML ecosystem. +library. `ComponentArrays` are well integrated into the SciML ecosystem. ## `@LArray` and `@LVector` macros -Macro constructors are convenient for building most `LArray` objects. An -`@LArray` may be of arbitrary dimension, while an `@LVector` is a -one dimensional array. +Macro constructors are convenient for building most `LArray` objects. An +`@LArray` may be of arbitrary dimension, while an `@LVector` is a +one dimensional array. ```@docs @LArray @@ -23,13 +23,14 @@ one dimensional array. ## `LArray` and `LVector` constructors -The original constructors for `LArray`s and `LVector`s are as -follows: +The original constructors for `LArray`s and `LVector`s are as +follows: ```@docs LArray LVector ``` + ## Manipulating `LArrays` and `LVectors` User may want a list of the labels or keys in an `LArray` or `LVector`. @@ -37,4 +38,4 @@ The `symbols(::LArray)` function returns a tuple of array labels. ```@docs symbols -``` \ No newline at end of file +``` diff --git a/docs/src/NamedTuples_relation.md b/docs/src/NamedTuples_relation.md index a9a2392..2d00494 100644 --- a/docs/src/NamedTuples_relation.md +++ b/docs/src/NamedTuples_relation.md @@ -3,29 +3,29 @@ Julia's Base has NamedTuples in v0.7+. They are constructed as: ```julia -p = (σ = 10.0,ρ = 28.0,β = 8/3) +p = (σ = 10.0, ρ = 28.0, β = 8 / 3) ``` and they support `p[1]` and `p.σ` as well. The `LVector`, `SLVector`, `LArray` and `SLArray` constructors also support named tuples as their arguments: ```julia -julia> LVector((a=1, b=2)) +julia> LVector((a = 1, b = 2)) 2-element LArray{Int64,1,(:a, :b)}: 1 2 -julia> SLVector((a=1, b=2)) +julia> SLVector((a = 1, b = 2)) 2-element SLArray{Tuple{2},1,(:a, :b),Int64}: 1 2 -julia> LArray((2,2), (a=1, b=2, c=3, d=4)) +julia> LArray((2, 2), (a = 1, b = 2, c = 3, d = 4)) 2×2 LArray{Int64,2,(:a, :b, :c, :d)}: 1 3 2 4 -julia> SLArray{Tuple{2,2}}((a=1, b=2, c=3, d=4)) +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 @@ -38,11 +38,11 @@ creates an iterator that is functionally the same as for each label of the array. There are some crucial differences between a labelled array and -a named tuple. Labelled arrays can have any dimensions, while +a named tuple. Labelled arrays can have any dimensions, while named tuples are always 1D. A named tuple can have different types on each element, while an `SLArray` can only have one element type and furthermore it has the actions of a static vector. -As a result `SLArray` has less element type information, which +As a result `SLArray` has less element type information, which improves compilation speed while giving more vector functionality than a NamedTuple. `LArray` also only has a single element type and, -unlike a named tuple, is mutable. \ No newline at end of file +unlike a named tuple, is mutable. diff --git a/docs/src/Note_labelled_slices.md b/docs/src/Note_labelled_slices.md index e982111..23cfbca 100644 --- a/docs/src/Note_labelled_slices.md +++ b/docs/src/Note_labelled_slices.md @@ -1,5 +1,5 @@ # Note: Labelled slices -This functionality has been removed from LabelledArrays.jl, but can -be replicated with the same compile-time performance and indexing syntax -using [DimensionalData.jl](https://github.com/rafaqz/DimensionalData.jl). \ No newline at end of file +This functionality has been removed from LabelledArrays.jl, but can +be replicated with the same compile-time performance and indexing syntax +using [DimensionalData.jl](https://github.com/rafaqz/DimensionalData.jl). diff --git a/docs/src/SLArrays.md b/docs/src/SLArrays.md index 9d990be..e8327c1 100644 --- a/docs/src/SLArrays.md +++ b/docs/src/SLArrays.md @@ -6,9 +6,9 @@ instances of the labelled array. ## `@SLArray` and `@SLVector` macros -Macro constructors are convenient for building most `SLArray` objects. An -`@SLArray` may be of arbitrary dimension, while an `@SLVector` is a -one dimensional array. +Macro constructors are convenient for building most `SLArray` objects. An +`@SLArray` may be of arbitrary dimension, while an `@SLVector` is a +one dimensional array. ```@docs @SLArray @@ -32,4 +32,4 @@ The `symbols(::SLArray)` function returns a tuple of array labels. ```@docs symbols(::SLArray) -``` \ No newline at end of file +``` diff --git a/docs/src/index.md b/docs/src/index.md index 85acae3..3c2775d 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -16,66 +16,84 @@ Pkg.add("LabelledArrays") ## Contributing -- Please refer to the - [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md) - for guidance on PRs, issues, and other matters relating to contributing to SciML. -- There are a few community forums: - - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/) - - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter - - on the [Julia Discourse forums](https://discourse.julialang.org) - - see also [SciML Community page](https://sciml.ai/community/) + - Please refer to the + [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md) + for guidance on PRs, issues, and other matters relating to contributing to SciML. + + - There are a few community forums: + + + the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/) + + [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter + + on the [Julia Discourse forums](https://discourse.julialang.org) + + see also [SciML Community page](https://sciml.ai/community/) ## Reproducibility + ```@raw html
The documentation of this SciML package was built using these direct dependencies, ``` + ```@example using Pkg # hide Pkg.status() # hide ``` + ```@raw html
``` + ```@raw html
and using this machine and Julia version. ``` + ```@example using InteractiveUtils # hide versioninfo() # hide ``` + ```@raw html
``` + ```@raw html
A more complete overview of all dependencies and their versions is also provided. ``` + ```@example using Pkg # hide -Pkg.status(;mode = PKGMODE_MANIFEST) # hide +Pkg.status(; mode = PKGMODE_MANIFEST) # hide ``` + ```@raw html
``` + ```@raw html You can also download the manifest file and the project file. -``` \ No newline at end of file +``` diff --git a/src/larray.jl b/src/larray.jl index eece533..7b41f1f 100644 --- a/src/larray.jl +++ b/src/larray.jl @@ -31,13 +31,14 @@ Base.keys(x::LArray{T, N, D, Syms}) where {T, N, D, Syms} = Syms LArray(::Tuple, ::NamedTuple) LArray(::Tuple, kwargs) ``` + The standard constructors for `LArray`. For example: ```julia -LArray((2,2), (a=1, b=2, c=3, d=4)) # need to specify size -LArray((2,2); a=1, b=2, c=3, d=4) +LArray((2, 2), (a = 1, b = 2, c = 3, d = 4)) # need to specify size +LArray((2, 2); a = 1, b = 2, c = 3, d = 4) ``` """ function LArray(size::NTuple{S, Int}, tup::NamedTuple{Syms, Tup}) where {S, Syms, Tup} @@ -51,12 +52,14 @@ LArray(size::NTuple{S, Int}; kwargs...) where {S} = LArray(size, values(kwargs)) LVector(::NamedTuple) LVector(kwargs) ``` + The standard constructor for `LVector`. For example: + ```julia -LVector((a=1, b=2)) -LVector(a=1, b=2) +LVector((a = 1, b = 2)) +LVector(a = 1, b = 2) ``` """ LVector(tup::NamedTuple) = LArray((length(tup),), tup) @@ -193,12 +196,13 @@ Base.dataids(A::LArray) = Base.dataids(A.__x) @LArray Eltype Size Names @LArray Values Names ``` + The `@LArray` macro creates an `LArray` with names determined from the `Names` vector and values determined from the `Values` vector. Otherwise, the eltype and size are used to make an `LArray` with undefined values. ```julia -A = @LArray [1,2,3] (:a,:b,:c) +A = @LArray [1, 2, 3] (:a, :b, :c) A.a == 1 ``` @@ -207,23 +211,25 @@ the dimensions. This approach is useful if the user intends to pre-allocate an array for some later input. ```julia -A = @LArray Float64 (2,2) (:a,:b,:c,:d) -W = rand(2,2) +A = @LArray Float64 (2, 2) (:a, :b, :c, :d) +W = rand(2, 2) A .= W -A.d == W[2,2] +A.d == W[2, 2] ``` Users may also use an alternative constructor to set the Names and Values and ranges at the same time. ```julia -julia> z = @LArray [1.,2.,3.] (a = 1:2, b = 2:3); +julia> z = @LArray [1.0, 2.0, 3.0] (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 @@ -259,8 +265,9 @@ The `@LVector` macro creates an `LArray` of dimension 1 with eltype and undefine The vector's length is equal to the number of names given. As with an `LArray`, the user can initialize the vector and set its values later. + ```julia -A = @LVector Float64 (:a,:b,:c,:d) +A = @LVector Float64 (:a, :b, :c, :d) A .= rand(4) ``` @@ -268,7 +275,7 @@ On the other hand, users can also initialize the vector and set its values at th same time: ```julia -b = @LVector [1,2,3] (:a,:b,:c) +b = @LVector [1, 2, 3] (:a, :b, :c) ``` """ macro LVector(type, syms) @@ -291,9 +298,10 @@ For example: ```julia julia> z = @LVector Float64 (:a, :b, :c, :d); + julia> symbols(z) (:a, :b, :c, :d) -```` +``` """ function symbols(::LArray{T, N, D, Syms}) where {T, N, D, Syms} Syms isa NamedTuple ? keys(Syms) : Syms diff --git a/src/slarray.jl b/src/slarray.jl index 8c53aa9..b756f8f 100644 --- a/src/slarray.jl +++ b/src/slarray.jl @@ -62,12 +62,12 @@ labelled arrays, users need to specify the size (`Tuple{dim1,dim2,...}`) in the type parameter to the `SLArray` constructor: ```julia -julia> SLArray{Tuple{2,2}}((a=1, b=2, c=3, d=4)) +julia> SLArray{Tuple{2, 2}}((a = 1, b = 2, c = 3, d = 4)) 2×2 SLArray{Tuple{2, 2}, Int64, 2, 4, (:a, :b, :c, :d)} with indices SOneTo(2)×SOneTo(2): :a => 1 :c => 3 :b => 2 :d => 4 -julia> SLArray{Tuple{2,2}}(a=1, b=2, c=3, d=4) +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 @@ -78,9 +78,11 @@ a keyword constructor whose first argument is the source and whose additional keyword arguments indicate the changes. ```julia -julia> ABCD = @SLArray (2,2) (:a,:b,:c,:d); -julia> B = ABCD(1,2,3,4); -julia> B2 = SLArray(B; c=30 ) +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 @@ -89,7 +91,7 @@ julia> B2 = SLArray(B; c=30 ) Additional examples: ```julia -SLArray{Tuple{2,2}}((a=1, b=2, c=3, d=4)) +SLArray{Tuple{2, 2}}((a = 1, b = 2, c = 3, d = 4)) ``` """ function SLArray{Size}(tup::NamedTuple{Syms, Tup}) where {Size, Syms, Tup} @@ -103,10 +105,11 @@ SLArray{Size}(; kwargs...) where {Size} = SLArray{Size}(values(kwargs)) SLVector(::NamedTuple) SLVector(kwargs) ``` + The standard constructors for `SLArray`. ```julia -julia> SLVector(a=1, b=2, c=3) +julia> SLVector(a = 1, b = 2, c = 3) 3-element SLArray{Tuple{3},1,(:a, :b, :c),Int64}: 1 2 @@ -118,8 +121,9 @@ a keyword constructor whose first argument is the source and whose additional keyword arguments indicate the changes. ```julia -julia> v1 = SLVector(a=1.1, b=2.2, c=3.3); -julia> v2 = SLVector(v1; b=20.20, c=30.30 ) +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 @@ -129,8 +133,8 @@ julia> v2 = SLVector(v1; b=20.20, c=30.30 ) Additional examples: ```julia -SLVector((a=1, b=2)) -SLVector(a=1, b=2) +SLVector((a = 1, b = 2)) +SLVector(a = 1, b = 2) ``` """ SLVector(tup::NamedTuple) = SLArray{Tuple{length(tup)}}(tup) @@ -215,21 +219,23 @@ is given, then the eltype is determined from the arguments in the constructor. For example: ```julia -ABCD = @SLArray (2,2) (:a,:b,:c,:d) +ABCD = @SLArray (2, 2) (:a, :b, :c, :d) x = ABCD(1.0, 2.5, 3.0, 5.0) x.a == 1.0 x.b == 2.5 x.c == x[3] -x.d == x[2,2] -EFG = @SLArray (2,2) (e=1:3, f=4, g=2:4) -y = EFG(1.0,2.5,3.0,5.0) -EFG = @SLArray (2,2) (e=(2, :), f=4, g=2:4) +x.d == x[2, 2] +EFG = @SLArray (2, 2) (e = 1:3, f = 4, g = 2:4) +y = EFG(1.0, 2.5, 3.0, 5.0) +EFG = @SLArray (2, 2) (e = (2, :), f = 4, g = 2:4) ``` + Users 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) +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 @@ -241,7 +247,9 @@ julia> y.g 5.0 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 @@ -276,13 +284,12 @@ The array size is found from the input data. For example: ```julia -ABC = @SLVector (:a,:b,:c) -x = ABC(1.0,2.5,3.0) +ABC = @SLVector (:a, :b, :c) +x = ABC(1.0, 2.5, 3.0) x.a == 1.0 x.b == 2.5 x.c == x[3] ``` - """ macro SLVector(syms) syms = esc(syms) @@ -307,8 +314,9 @@ end Returns the labels of the `SLArray`. For example: + ```julia -julia> z = SLVector(a=1, b=2, c=3) +julia> z = SLVector(a = 1, b = 2, c = 3) 3-element SLArray{Tuple{3}, Int64, 1, 3, (:a, :b, :c)} with indices SOneTo(3): :a => 1 :b => 2