LabelledArrays.jl

https://docs.sciml.ai/LabelledArrays/stable/
Admin
LabelledArrays.jl is a Julia package that provides arrays with named labels, enabling component...
Tokens:7,032
Snippets:58
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install LabelledArrays.jl

Source: https://docs.sciml.ai/LabelledArrays/stable

Use the Julia package manager to add LabelledArrays.jl to your project. This is the standard way to install packages in Julia.

```julia
using Pkg
Pkg.add("LabelledArrays")
```

--------------------------------

### Get labels of an SLArray

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

The symbols function returns a tuple of the labels (symbols) associated with an SLArray.

```julia
z = SLVector(a = 1, b = 2, c = 3)
symbols(z)
```

--------------------------------

### Get LArray Labels

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Retrieve the labels of an LArray using the `symbols` function. This function is applicable to LArrays as well, providing access to their symbolic names.

```julia
symbols(::LArray)
```

```julia
z = @LVector Float64 (:a, :b, :c, :d)

symbols(z)
```

--------------------------------

### Get labels of an LArray

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

The symbols function returns a tuple of the labels (symbols) associated with an LArray.

```julia
z = @LVector Float64 (:a, :b, :c, :d)
symbols(z)
```

--------------------------------

### Get SLArray Labels

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Use the `symbols` function to retrieve the labels of an SLArray. This is useful for understanding the structure and accessing elements by name.

```julia
symbols(::SLArray)
```

```julia
z = SLVector(a = 1, b = 2, c = 3)

symbols(z)
```

--------------------------------

### Constructing a NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Demonstrates the basic syntax for creating a NamedTuple in Julia.

```julia
p = (σ = 10.0, ρ = 28.0, β = 8 / 3)
```

--------------------------------

### Constructing LVector with NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Shows how to initialize an LVector using a NamedTuple.

```julia
LVector((a = 1, b = 2))
```

--------------------------------

### Standard LArray constructors

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Demonstrates the standard constructors for LArray, requiring specification of dimensions and either a NamedTuple or keyword arguments for values.

```julia
LArray((2, 2), (a = 1, b = 2, c = 3, d = 4))  # need to specify size
```

```julia
LArray((2, 2); a = 1, b = 2, c = 3, d = 4)
```

--------------------------------

### Constructing LArray with NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Demonstrates creating an LArray with specified dimensions and initializing it using a NamedTuple.

```julia
LArray((2, 2), (a = 1, b = 2, c = 3, d = 4))
```

--------------------------------

### Constructing SLVector with NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Illustrates initializing an SLVector with a NamedTuple.

```julia
SLVector((a = 1, b = 2))
```

--------------------------------

### Constructing SLArray with NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Shows how to initialize an SLArray with a specific type and dimensions using a NamedTuple.

```julia
SLArray{Tuple{2, 2}}((a = 1, b = 2, c = 3, d = 4))
```

--------------------------------

### Copying and Modifying SLArrays/SLVectors

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Demonstrates how to create modified copies of existing SLArrays and SLVectors.

```APIDOC
## Copying and Modifying SLArrays/SLVectors

### Description
It's possible to create new `SLArray` or `SLVector` instances that are copies of existing ones, with specific elements modified.

### Example for `SLArray`
```julia
# Define an SLArray type
ABCD = @SLArray (2, 2) (:a, :b, :c, :d)

# Create an instance
B = ABCD(1, 2, 3, 4)

# Create a new instance with 'c' modified
B2 = SLArray(B; c = 30)
println(B2)
```

### Example for `SLVector`
```julia
# Create an SLVector instance
z = SLVector(a=1, b=2, c=3)

# Create a new instance with 'c' modified
z2 = SLVector(z; c=30)
println(z2)
```
```

--------------------------------

### `@SLArray` Macro

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Creates a labelled static array of arbitrary dimension. Users can specify element type, size, and names.

```APIDOC
## `@SLArray` Macro

### Description
Creates a labelled static array of arbitrary dimension.

### Syntax
```julia
@SLArray Size Names
@SLArray Eltype Size Names
```

### Parameters
- `Size`: A tuple specifying the dimensions of the array (e.g., `(2, 2)`).
- `Eltype`: (Optional) The element type of the array (e.g., `Float64`). If not provided, it's inferred from constructor arguments.
- `Names`: A tuple of symbols or a NamedTuple defining the names for the array elements.

### Example
```julia
ABCD = @SLArray (2, 2) (:a, :b, :c, :d)
x = ABCD(1.0, 2.5, 3.0, 5.0)
println(x.a) # Output: 1.0

EFG = @SLArray (2, 2) (e = 1:3, f = 4, g = 2:4)
y = EFG(1.0, 2.5, 3.0, 5.0)
println(y.g) # Output: a view of elements corresponding to 'g'
```
```

--------------------------------

### `LArray` and `LVector` constructors

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Standard constructors for creating LArray and LVector objects.

```APIDOC
## `LArray` and `LVector` constructors

The original constructors for `LArray`s and `LVector`s are as follows:

`LabelledArrays.LArray` — Type
```julia
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)
```

source

```julia
LVector(v1::Union{SLArray,LArray}; kwargs...)
```

Creates a copy of v1 with corresponding items in kwargs replaced.
For example:

```julia
ABCD = @SLArray (2,2) (:a,:b,:c,:d);
B = ABCD(1,2,3,4);
B2 = LArray(B; c=30 )
```

source

```julia
LabelledArrays.LVector` — Function
```julia
LVector(::NamedTuple)
LVector(kwargs)
```

The standard constructor for `LVector`.
For example:

```julia
LVector((a = 1, b = 2))
LVector(a = 1, b = 2)
```

source

```julia
LVector(v1::Union{SLArray,LArray}; kwargs...)
```

Creates a 1D copy of v1 with corresponding items in kwargs replaced.
For example:

```julia
z = LVector(a=1, b=2, c=3)
z2 = LVector(z; c=30)
```

source
```

--------------------------------

### `SLArray` Constructor

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Constructs a static labelled array using keyword arguments or a NamedTuple.

```APIDOC
## `SLArray` Constructor

### Description
Constructs a static labelled array. For N-dimensional arrays, the size must be specified in the type parameter.

### Syntax
```julia
SLArray{Tuple}(NamedTuple)
SLArray{Tuple}(kwargs)
```

### Parameters
- `Tuple`: A tuple specifying the dimensions of the array (e.g., `Tuple{2, 2}`).
- `NamedTuple`: A NamedTuple containing the elements and their names.
- `kwargs`: Keyword arguments where keys are names and values are elements.

### Example
```julia
# Using NamedTuple
arr1 = SLArray{Tuple{2, 2}}((a = 1, b = 2, c = 3, d = 4))
println(arr1)

# Using keyword arguments
arr2 = SLArray{Tuple{2, 2}}(a = 1, b = 2, c = 3, d = 4)
println(arr2)

# Constructing a copy with changes
ABCD = @SLArray (2, 2) (:a, :b, :c, :d)
B = ABCD(1, 2, 3, 4)
B2 = SLArray(B; c = 30)
println(B2)
```
```

--------------------------------

### Construct SLArray with keyword arguments

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Construct an SLArray by specifying the size in the type parameter and providing names and values as keyword arguments. This is an alternative to using the @SLArray macro.

```julia
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
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
```

```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
```

```julia
SLArray{Tuple{2, 2}}((a = 1, b = 2, c = 3, d = 4))
```

--------------------------------

### Construct SLVector with keyword arguments

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Construct an SLVector using keyword arguments for names and values. This method infers the size from the provided data.

```julia
julia> SLVector(a = 1, b = 2, c = 3)
3-element SLArray{Tuple{3},1,(:a, :b, :c),Int64}:
 1
 2
 3
```

```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
```

```julia
SLVector((a = 1, b = 2))
SLVector(a = 1, b = 2)
```

--------------------------------

### Create LArray with values and names

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Use the @LArray macro to create an LArray with specified values and corresponding names.

```julia
A = @LArray [1, 2, 3] (:a, :b, :c)
A.a == 1
```

--------------------------------

### Create LArray with ranges for names

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Use an alternative @LArray constructor to set names and ranges simultaneously, allowing for more complex indexing.

```julia
z = @LArray [1.0, 2.0, 3.0] (a = 1:2, b = 2:3)
z.b
```

```julia
z = @LArray [1 2; 3 4] (a = (2, :), b = 2:3)
z.a
```

--------------------------------

### `SLVector` Constructor

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Constructs a static labelled vector using keyword arguments or a NamedTuple.

```APIDOC
## `SLVector` Constructor

### Description
Constructs a static labelled vector. The size is determined from the input data.

### Syntax
```julia
SLVector(NamedTuple)
SLVector(kwargs)
```

### Parameters
- `NamedTuple`: A NamedTuple containing the elements and their names.
- `kwargs`: Keyword arguments where keys are names and values are elements.

### Example
```julia
# Using NamedTuple
vec1 = SLVector((a = 1, b = 2, c = 3))
println(vec1)

# Using keyword arguments
vec2 = SLVector(a = 1, b = 2, c = 3)
println(vec2)

# Constructing a copy with changes
v1 = SLVector(a = 1.1, b = 2.2, c = 3.3)
v2 = SLVector(v1; b = 20.20, c = 30.30)
println(v2)
```
```

--------------------------------

### `@LArray` and `@LVector` macros

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Macro constructors for creating LArray and LVector objects. `@LArray` can create arrays of arbitrary dimensions, while `@LVector` creates one-dimensional arrays.

```APIDOC
## `@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.

`LabelledArrays.@LArray` — Macro
```julia
@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.a == 1
```

Users can also generate a labelled array with undefined values by instead giving 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 .= W
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.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 by function `symbols`, which returns a tuple of symbols.

source`LabelledArrays.@LVector` — Macro
```julia
@LVector Type Names
```

The `@LVector` macro creates an `LArray` of dimension 1 with eltype and undefined values. 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 .= rand(4)
```

To initialize the vector and set its values at the same time, use `@LArray` instead:

```julia
b = @LArray [1, 2, 3] (:a, :b, :c)
```

source
```

--------------------------------

### `@SLVector` Macro

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Creates a one-dimensional labelled static vector. Users can specify element type and names.

```APIDOC
## `@SLVector` Macro

### Description
Creates a one-dimensional labelled static vector. The array size is determined from the input data.

### Syntax
```julia
@SLVector Names
@SLVector Eltype Names
```

### Parameters
- `Eltype`: (Optional) The element type of the vector (e.g., `Float64`). If not provided, it's inferred from constructor arguments.
- `Names`: A tuple of symbols or a NamedTuple defining the names for the vector elements.

### Example
```julia
ABC = @SLVector (:a, :b, :c)
x = ABC(1.0, 2.5, 3.0)
println(x.a) # Output: 1.0
```
```

--------------------------------

### Solve Lorenz Equation with Mutable LArray

Source: https://docs.sciml.ai/LabelledArrays/stable/Example_dsl

Use a mutable LArray for initial conditions and parameters to solve the Lorenz equation with the non-allocating OrdinaryDiffEq API. The solution can also be indexed by name.

```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
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())
# Now the solution can be indexed as .x/y/z as well!
sol[10].x
```

--------------------------------

### Create a 1D copy of SLArray with SLVector constructor

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Use the SLVector constructor with a source SLArray and keyword arguments to create a new 1D labelled array with specified elements updated.

```julia
z = SLVector(a=1, b=2, c=3)
z2 = SLVector(z; c=30)
```

--------------------------------

### Create LVector by copying and modifying (LVector)

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Create a new LVector by copying an existing LVector and overriding specific elements using keyword arguments.

```julia
z = LVector(a=1, b=2, c=3)
z2 = LVector(z; c=30)
```

--------------------------------

### Solve Lorenz Equation with Immutable SLVector

Source: https://docs.sciml.ai/LabelledArrays/stable/Example_dsl

Implement the Lorenz equation using an immutable SLVector for initial conditions and parameters, requiring the allocating form of the OrdinaryDiffEq API. This approach offers type safety and immutability.

```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)
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())
```

--------------------------------

### Iterating over Labelled Array Elements

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Demonstrates using `pairs` to iterate over the elements of a labelled array, similar to a NamedTuple.

```julia
pairs(x)
```

--------------------------------

### Standard LVector constructor

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

The standard constructor for LVector takes a NamedTuple or keyword arguments to define the vector's elements.

```julia
LVector((a = 1, b = 2))
```

```julia
LVector(a = 1, b = 2)
```

--------------------------------

### Create LArray with dimensions and names

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Generate an LArray with undefined values by specifying dimensions and names. This is useful for pre-allocating arrays.

```julia
A = @LArray Float64 (2, 2) (:a, :b, :c, :d)
W = rand(2, 2)
A .= W
A.d == W[2, 2]
```

--------------------------------

### Converting Labelled Array to NamedTuple

Source: https://docs.sciml.ai/LabelledArrays/stable/NamedTuples_relation

Provides the syntax for converting a labelled array to a NamedTuple.

```julia
convert(NamedTuple, x)
```

--------------------------------

### Create LVector by copying and modifying

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Create a new LVector by copying an existing SLArray or LArray and overriding specific elements using keyword arguments.

```julia
ABCD = @SLArray (2,2) (:a,:b,:c,:d)
B = ABCD(1,2,3,4)
B2 = LArray(B; c=30 )
```

--------------------------------

### Define SLArray with @SLArray macro

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Use the @SLArray macro to define a static labelled array with specified size, element type, and names. If eltype is omitted, it's inferred from constructor arguments.

```julia
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]
```

```julia
EFG = @SLArray (2, 2) (e = 1:3, f = 4, g = 2:4)
y = EFG(1.0, 2.5, 3.0, 5.0)
```

```julia
EFG = @SLArray (2, 2) (e = (2, :), f = 4, g = 2:4)
```

```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

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

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
```

--------------------------------

### Define SLVector with @SLVector macro

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Use the @SLVector macro to define a static labelled vector. The element type can be specified, otherwise it is inferred from constructor values. The array size is determined by the input data.

```julia
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]
```

--------------------------------

### symbols(::LArray)

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Retrieves the labels of an LArray. This is particularly useful for LArrays created with named dimensions.

```APIDOC
## symbols(::LArray)

### Description
Returns the labels of the `LArray`.

### Method
```julia
symbols(::LArray)
```

### Example
```julia
z = @LVector Float64 (:a, :b, :c, :d)
symbols(z)
```

### Returns
Tuple of array labels.
```

--------------------------------

### Create LVector with undefined values

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

The @LVector macro creates a 1D LArray with a specified eltype and names, initializing values later.

```julia
A = @LVector Float64 (:a, :b, :c, :d)
A .= rand(4)
```

--------------------------------

### Manipulating `LArrays` and `LVectors`

Source: https://docs.sciml.ai/LabelledArrays/stable/LArrays

Functions for accessing labels and symbols within LArrays and LVectors.

```APIDOC
## Manipulating `LArrays` and `LVectors`

Users may want a list of the labels or keys in an `LArray` or `LVector`. The `symbols(::LArray)` function returns a tuple of array labels.

`LabelledArrays.symbols` — Function
```julia
symbols(::SLArray)
```

Returns the labels of the `SLArray`.
For example:

```julia
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
 :c => 3

julia> symbols(z)
(:a, :b, :c)
```

source

```julia
symbols(::LArray)
```

Returns the labels of the `LArray`.
For example:

```julia
julia> z = @LVector Float64 (:a, :b, :c, :d)

julia> symbols(z)
(:a, :b, :c, :d)
```

source
```

--------------------------------

### symbols(::SLArray)

Source: https://docs.sciml.ai/LabelledArrays/stable/SLArrays

Retrieves the labels of an SLArray. This function is useful for understanding the named dimensions or elements within an SLArray.

```APIDOC
## symbols(::SLArray)

### Description
Returns the labels of the `SLArray`.

### Method
```julia
symbols(::SLArray)
```

### Example
```julia
z = SLVector(a = 1, b = 2, c = 3)
symbols(z)
```

### Returns
Tuple of array labels.
```
Tokens:
Raw