Prognostic and DiagnosticVariables array-agnostic

docs/src/analysis.md

@@ -146,7 +146,7 @@ function total_energy(u, v, η, model)
     E = @. h/2*(u^2 + v^2) + g*h^2  # vertically-integrated mechanical energy
 
     # transform to spectral, take l=m=0 mode at [1] and normalize for mean
-    return E_mean = real(spectral(E)[1]) / model.spectral_transform.norm_sphere
+    return E_mean = real(transform(E)[1]) / model.spectral_transform.norm_sphere
 end
 ```
 
@@ -262,7 +262,7 @@ function total_angular_momentum(u, η, model)
     Λ = @. (u*r + Ω*r^2) * h    # vertically-integrated AAM
 
     # transform to spectral, take l=m=0 mode at [1] and normalize for mean
-    return Λ_mean = real(spectral(Λ)[1]) / model.spectral_transform.norm_sphere
+    return Λ_mean = real(transform(Λ)[1]) / model.spectral_transform.norm_sphere
 end
 ```
 
@@ -299,7 +299,7 @@ function total_circulation(ζ, model)
     f = coriolis(ζ)         # create f on the grid of ζ
     C = ζ .+ f              # absolute vorticity
     # transform to spectral, take l=m=0 mode at [1] and normalize for mean
-    return C_mean = real(spectral(C)[1]) / model.spectral_transform.norm_sphere
+    return C_mean = real(transform(C)[1]) / model.spectral_transform.norm_sphere
 end
 
 total_circulation(ζ, model)
@@ -336,7 +336,7 @@ function total_enstrophy(ζ, η, model)
     Q = @. q^2 / 2      # Potential enstrophy
 
     # transform to spectral, take l=m=0 mode at [1] and normalize for mean
-    return Q_mean = real(spectral(Q)[1]) / model.spectral_transform.norm_sphere
+    return Q_mean = real(transform(Q)[1]) / model.spectral_transform.norm_sphere
 end
 ```
 
@@ -373,14 +373,14 @@ to show how to global integral ``\iint dV`` can be written more efficiently
 # define a global integral, reusing a precomputed SpectralTransform S
 # times surface area of sphere omitted
 function ∬dA(v, h, S::SpectralTransform)
-    return real(spectral(v .* h, S)[1]) / S.norm_sphere
+    return real(transform(v .* h, S)[1]) / S.norm_sphere
 end
 
 # use SpectralTransform from model
 ∬dA(v, h, model::ModelSetup) = ∬dA(v, h, model.spectral_transform)
 ```
 By reusing `model.spectral_transform` we do not have to re-precompute
-the spectral tranform on every call to `spectral`. Providing
+the spectral tranform on every call to `transform`. Providing
 the spectral transform from model as the 2nd argument simply reuses
 a previously precomputed spectral transform which is much faster
 and uses less memory.

docs/src/gradients.md

@@ -60,7 +60,7 @@ using SpeedyWeather, CairoMakie
 trunc = 64                  # 1-based maximum degree of spherical harmonics
 L = randn(LowerTriangularMatrix{ComplexF32}, trunc, trunc)
 spectral_truncation!(L, 5)              # remove higher wave numbers
-G = gridded(L)
+G = transform(L)
 heatmap(G, title="Some fake data G")    # requires `using CairoMakie`
 save("gradient_data.png", ans) # hide
 nothing # hide
@@ -136,8 +136,8 @@ RingGrids.scale_coslat⁻¹!(u)
 RingGrids.scale_coslat⁻¹!(v)
 
 S = SpectralTransform(u, one_more_degree=true)
-us = spectral(u, S)
-vs = spectral(v, S)
+us = transform(u, S)
+vs = transform(v, S)
 
 vor = curl(us, vs, radius = spectral_grid.radius)
 ```
@@ -172,7 +172,7 @@ that we also used in `spectral_grid`. The Coriolis parameter for a grid like `vo
 is obtained, and we do the following for ``f\zeta/g``.
 
 ```@example gradient
-vor_grid = gridded(vor, Grid=spectral_grid.Grid)
+vor_grid = transform(vor, Grid=spectral_grid.Grid)
 f = coriolis(vor_grid)      # create Coriolis parameter f on same grid with default rotation
 g = model.planet.gravity
 fζ_g = @. vor_grid * f / g  # in-place and element-wise
@@ -181,11 +181,11 @@ nothing # hide
 Now we need to apply the inverse Laplace operator to ``f\zeta/g`` which we do as follows
 
 ```@example gradient
-fζ_g_spectral = spectral(fζ_g, one_more_degree=true)
+fζ_g_spectral = transform(fζ_g, one_more_degree=true)
 
 R = spectral_grid.radius
 η = SpeedyTransforms.∇⁻²(fζ_g_spectral) * R^2
-η_grid = gridded(η, Grid=spectral_grid.Grid)
+η_grid = transform(η, Grid=spectral_grid.Grid)
 nothing # hide
 ```
 Note the manual scaling with the radius ``R^2`` here. We now compare the results

docs/src/particles.md

@@ -186,9 +186,9 @@ would not just convert from `Float64` to `Float32` but also
 from an active to an inactive particle. In SpeedyWeather all particles can be
 activated or deactivated at any time.
 
-First, you create a [`SpectralGrid`](@ref) with the `n_particles` keyword
+First, you create a [`SpectralGrid`](@ref) with the `nparticles` keyword
 ```@example particle
-spectral_grid = SpectralGrid(n_particles = 3)
+spectral_grid = SpectralGrid(nparticles = 3)
 ```
 Then the particles live as `Vector{Particle}` inside the prognostic variables
 ```@example particle
@@ -246,7 +246,7 @@ the particle locations via netCDF. We can create it like
 
 ```@example particle_tracker
 using SpeedyWeather
-spectral_grid = SpectralGrid(n_particles = 100)
+spectral_grid = SpectralGrid(nparticles = 100)
 particle_tracker = ParticleTracker(spectral_grid, schedule=Schedule(every=Hour(3)))
 ```
 
@@ -285,18 +285,18 @@ ds["lat"]
 ```
 where the last two lines are lazy loading a matrix with each row a particle and each column a time step.
 You may do `ds["lon"][:,:]` to obtain the full `Matrix`. We had specified
-`spectral_grid.n_particles` above and we will have time steps in this file
+`spectral_grid.nparticles` above and we will have time steps in this file
 depending on the `period` the simulation ran for and the `particle_tracker.Δt` output
 frequency. We can visualise the particles' trajectories with
 
 ```@example particle_tracker
 lon = ds["lon"][:,:]
 lat = ds["lat"][:,:]
-n_particles = size(lon,1)
+nparticles = size(lon,1)
 
 using CairoMakie
 fig = lines(lon[1, :], lat[1, :])                               # first particle only
-[lines!(fig.axis, lon[i,:], lat[i,:]) for i in 2:n_particles]   # add lines for other particles
+[lines!(fig.axis, lon[i,:], lat[i,:]) for i in 2:nparticles]   # add lines for other particles
 
 # display updated figure
 fig
@@ -319,7 +319,7 @@ using GeoMakie, CairoMakie
 
 fig = Figure()
 ga = GeoAxis(fig[1, 1]; dest = "+proj=ortho +lon_0=45 +lat_0=45")
-[lines!(ga, lon[i,:], lat[i,:]) for i in 1:n_particles]
+[lines!(ga, lon[i,:], lat[i,:]) for i in 1:nparticles]
 fig
 save("particles_geomakie.png", fig) # hide
 nothing # hide

docs/src/speedytransforms.md

@@ -36,23 +36,23 @@ alms = zeros(LowerTriangularMatrix{ComplexF64}, 6, 6)     # spectral coefficient
 alms[2, 2] = 1                                           # only l=1, m=1 harmonic
 alms
 ```
-Now `gridded` is the function that takes spectral coefficients `alms` and converts
-them a grid-point space `map`
+Now `transform` is the function that takes spectral coefficients `alms` and converts
+them a grid-point space `map` (or vice versa)
 
 ```@example speedytransforms
-map = gridded(alms)
+map = transform(alms)
 ```
-By default, the `gridded` transforms onto a [`FullGaussianGrid`](@ref FullGaussianGrid) unravelled here
+By default, the `transforms` transforms onto a [`FullGaussianGrid`](@ref FullGaussianGrid) unravelled here
 into a vector west to east, starting at the prime meridian, then north to south, see [RingGrids](@ref).
 We can visualize `map` quickly with a UnicodePlot via `plot` (see [Visualising RingGrid data](@ref))
 ```@example speedytransforms
 import SpeedyWeather.RingGrids: plot    # not necessary when `using SpeedyWeather`
 plot(map)
 ```
 Yay! This is the what the ``l=m=1`` spherical harmonic is supposed to look like!
-Now let's go back to spectral space with `spectral`
+Now let's go back to spectral space with `transform`
 ```@example speedytransforms
-alms2 = spectral(map)
+alms2 = transform(map)
 ```
 Comparing with `alms` from above you can see that the transform is exact up to a typical rounding error
 from `Float64`. 
@@ -70,15 +70,15 @@ a transform error that is larger than the rounding error from floating-point ari
 While the default grid for [SpeedyTransforms](@ref) is the [`FullGaussianGrid`](@ref FullGaussianGrid)
 we can transform onto other grids by specifying `Grid` too
 ```@example speedytransforms
-map = gridded(alms, Grid=HEALPixGrid)
+map = transform(alms, Grid=HEALPixGrid)
 plot(map)
 ```
 which, if transformed back, however, can yield a larger transform error as discussed above
 ```@example speedytransforms
-spectral(map)
+transform(map)
 ```
 On such a coarse grid the transform error (absolute and relative) is about ``10^{-2}``, this decreases
-for higher resolution. The `gridded` and `spectral` functions will choose a corresponding
+for higher resolution. The `transform` function will choose a corresponding
 grid-spectral resolution (see [Matching spectral and grid resolution](@ref)) following quadratic
 truncation, but you can always truncate/interpolate in spectral space with `spectral_truncation`,
 `spectral_interpolation` which takes `trunc` = ``l_{max} = m_{max}`` as second argument
@@ -90,13 +90,16 @@ order 5 before.
 If the second argument in `spectral_truncation` is larger than `alms` then it will automatically
 call `spectral_interpolation` and vice versa. Also see [Interpolation on RingGrids](@ref)
 to interpolate directly between grids. If you want to control directly the resolution of the
-grid `gridded` is supposed to transform onto you have to provide a `SpectralTransform` instance.
+grid you want to `transform` onto, use the keyword `dealiasing` (default: 2 for quadratic,
+see [Matching spectral and grid resolution](@ref)).
+But you can also provide a `SpectralTransform` instance to reuse a precomputed spectral transform.
 More on that now.
 
 ## [The `SpectralTransform` struct](@id SpectralTransform)
 
-Both `spectral` and `gridded` create an instance of `SpectralTransform` under the hood. This object
-contains all precomputed information that is required for the transform, either way: 
+The function `transform` only with arguments as shown above,
+will create an instance of `SpectralTransform` under the hood.
+This object contains all precomputed information that is required for the transform, either way: 
 The Legendre polynomials, pre-planned Fourier transforms, precomputed gradient, divergence and
 curl operators, the spherical harmonic eigenvalues among others. Maybe the most intuitive way to
 create a `SpectralTransform` is to start with a `SpectralGrid`, which already defines
@@ -121,15 +124,15 @@ recomputation or pre-computation of the Legendre polynomials, fore more informat
 Passing on `S` the `SpectralTransform` now allows us to transform directly on the grid
 defined therein.
 ```@example speedytransforms
-map = gridded(alms, S)
+map = transform(alms, S)
 plot(map)
 ```
 Yay, this is again the ``l=m=1`` harmonic, but this time on a slightly higher resolution
 `OctahedralGaussianGrid` as specified in the `SpectralTransform` `S`.
 Note that also the number format was converted on the fly to Float32 because that is the number
 format we specified in `S`! And from grid to spectral
 ```@example speedytransforms
-alms2 = spectral(map, S)
+alms2 = transform(map, S)
 ```
 As you can see the rounding error is now more like ``10^{-8}`` as we are using Float32
 (the [OctahedralGaussianGrid](@ref OctahedralGaussianGrid) is another _exact_ grid).
@@ -166,7 +169,7 @@ Say you have some global data in a matrix `m` that looks, for example, like
 ```@example speedytransforms
 alms = randn(LowerTriangularMatrix{Complex{Float32}}, 32, 32) # hide
 spectral_truncation!(alms, 10) # hide
-map = gridded(alms, Grid=FullClenshawGrid) # hide
+map = transform(alms, Grid=FullClenshawGrid) # hide
 m = Matrix(map) # hide
 m
 ```
@@ -189,7 +192,7 @@ nothing # hide
 
 Now we transform into spectral space and call `power_spectrum(::LowerTriangularMatrix)`
 ```@example speedytransforms
-alms = spectral(map)
+alms = transform(map)
 power = SpeedyTransforms.power_spectrum(alms)
 nothing # hide
 ```
@@ -232,7 +235,7 @@ is correctly applied across dimensions of `A` and then convert to a
 Awesome. For higher degrees and orders the amplitude clearly decreases!
 Now to grid-point space and let us visualize the result
 ```@example speedytransforms
-map = gridded(alms)
+map = transform(alms)
 
 using CairoMakie
 heatmap(map, title="k⁻²-distributed noise")

src/LowerTriangularMatrices/LowerTriangularMatrices.jl

@@ -12,7 +12,6 @@ import LinearAlgebra: tril!
 
 # VISUALISATION
 import UnicodePlots
-# export plot
 
 export LowerTriangularMatrix, LowerTriangularArray
 export eachharmonic, eachmatrix

src/LowerTriangularMatrices/lower_triangular_matrix.jl

@@ -475,16 +475,27 @@ function _copyto_core!(
     L1
 end 
 
-function Base.copyto!(  L::LowerTriangularArray{T},    # copy to L
-                        M::AbstractArray) where T    # copy from M
-    @boundscheck size(L, as=Matrix) == size(M) || throw(BoundsError)
-    L.data .= convert.(T, M[lowertriangle_indices(M)])
-
+function Base.copyto!(
+    L::LowerTriangularArray{T},     # copy to L
+    M::AbstractArray,               # copy from M
+) where T
+
+    # if matrix sizes agree copy over the non-zero elements
+    if size(L, as=Matrix) == size(M)
+        L.data .= convert.(T, M[lowertriangle_indices(M)])
+
+    # if vector sizes agree copy straight into underlying data array
+    elseif size(L) == size(M)
+        L.data .= convert.(T, M)
+    else    # not matching sizes
+        throw(DimensionMismatch)
+    end
     L
 end
 
 function Base.copyto!(  M::AbstractArray{T},               # copy to M
                         L::LowerTriangularArray) where T   # copy from L
+
     @boundscheck size(L, as=Matrix) == size(M) || throw(BoundsError)
 
     lower_triangle_indices = lowertriangle_indices(M)