Aqua without broken, documented and owned exports, drop export Array

CHANGELOG.md

@@ -12,6 +12,69 @@ tags. It is named as a gap rather than reconstructed, because a changelog assemb
 fact loses exactly the reasoning that makes it worth keeping. The `[Unreleased]` section below
 holds the changes since the last release until that release is cut.
 
+## [Unreleased]
+
+### Breaking Changes
+
+- `ReducedComplexityModeling` no longer exports `Array`. The binding is `Core`'s, and every module
+  sees it without the export, so `Array` keeps its meaning in a caller's code; what changes is the
+  export list that `names(ReducedComplexityModeling)` returns.
+
+### Bug Fixes
+
+- `Parameter` takes a `Symbol` or a string name in every constructor form. The call
+  `Parameter("μ", minimum, maximum, n)` returns a `Parameter` whose samples are those of
+  `LinRange(minimum, maximum, n)` when the bounds differ, without duplicates. Equal bounds and a
+  positive count give the one sample `minimum`. A count of 0 gives no sample. It threw a
+  `MethodError` before, because two methods matched it equally well. This relates to issue #38:
+  the two string-name methods that clashed are deleted, and
+  `detect_ambiguities(ReducedComplexityModeling)` reports no ambiguity. A gap remains: unequal
+  integer bounds with a sample count still throw a `MethodError`. Their `LinRange` has a float
+  element type, so `Parameter(:a, 0, 10, 5)` throws.
+
+- `GeometricIntegratorEnsembleData(solutions, Independent())` builds its snapshot (K16). It threw
+  an `ErrorException` before. The snapshot is an array of size `ny × nx × ns`, for `ns` solutions
+  with `nx` entries of a state `q` with `ny` components. Its slice `[:, :, i]` is the snapshot
+  matrix of solution `i`, in the layout of `GeometricIntegratorData`. Solutions with different
+  numbers of entries in `q` throw an `ArgumentError`. Solutions with different numbers of
+  components of `q` also throw an `ArgumentError`.
+
+- `GeometricIntegratorEnsembleData(solutions, Dependent())` sizes its snapshot from the total number
+  of entries of all solutions. It was sized from the first solution alone: a later solution with
+  fewer entries left zero-filled trailing columns, and one with more entries threw a `BoundsError`.
+  The solutions may now have different numbers of entries in `q`. Solutions with different numbers
+  of components of `q` throw an `ArgumentError` (K26). A solution with one component after one with
+  two was copied into both rows without an error before. The snapshot of one solution and the
+  `Dependent` snapshot change their layout with `permutedims`. `Array(Z')` conjugated complex
+  values. No complex state reaches them today, because `integrate` does not take one.
+
+- In both layouts, the snapshot of `GeometricIntegratorEnsembleData` has the `promote_type` of
+  the element types of the states `q` of all solutions. A `Float32` solution followed by a
+  `Float64` solution gives a `Float64` snapshot, so a value of `1e40`, which is above
+  `floatmax(Float32)`, is kept. The order of the columns is unchanged.
+
+- `GeometricIntegratorEnsembleData` and both `Base.Array(solutions, ::Dependent)` and
+  `Base.Array(solutions, ::Independent)` take a vector with a concrete element type, such as
+  `[sol, sol]`. `GeometricIntegratorEnsembleData([sol, sol], Dependent())` threw a `MethodError`
+  before.
+
+- `reduce!(model, k, CotangentLiftEVD())` (K17) and `reduce!(model, k, ComplexSVD())` (K18) no
+  longer throw on every call. Each stores a `2n × 2k` basis in `model.reduced_basis`, orthonormal
+  and symplectic (`AᵀJA = J`). Neither algorithm type is exported: a caller reaches them as
+  `ReducedComplexityModeling.CotangentLiftEVD` and `ReducedComplexityModeling.ComplexSVD`.
+
+- Help text: the module and every exported name have a docstring with text. `Parameter`,
+  `ParameterSampler` and `CartesianParameterSampler` replace their empty docstrings, and `POD`,
+  `reduce!`, `compose`, `project`, `hassamples`, `GeometricIntegratorData`,
+  `GeometricIntegratorEnsembleData`, `Dependent` and `Independent` gain one. The exports test
+  requires the docstring of every exported or public name to contain that name. The docstrings of
+  `h5save` and `h5load` name their three methods and their arguments (K21). Each shows a round
+  trip, as a doctest. `h5save` writes a `ParameterSpace`, and `h5load` reads it back.
+  `h5save(file, p)` writes a `Parameter` `p` to the group of its name.
+  `h5load(Parameter, file; path = string(p.name))` reads it back. With the default
+  `path = "/"`, `h5load(Parameter, file)` throws a `KeyError`. The docstring of
+  `ReducedBasisModel` no longer names packages that are not dependencies of this package.
+
 ## [0.4.1] — 2026-10-29
 
 ### Changed

KNOWN_ISSUES.md

@@ -67,15 +67,15 @@
 
 ### K13 · Explicit import checks report implicit and non-public dependency accesses
 
-- **Location:** `src/ReducedComplexityModeling.jl:4`, the dependency imports, and their uses in
+- **Location:** `src/ReducedComplexityModeling.jl:13`, the dependency imports, and their uses in
   included source files.
 - **Evidence:** on Julia 1.13.3, ExplicitImports 1.15.0,
   `print_explicit_imports(ReducedComplexityModeling; report_non_public = true)` reports 25
   implicitly imported names, 5 non-public explicit imports (`AbstractDataType`, `AbstractSystem`,
   `ArrayOrNamedTuple`, `H5DataStore`, `NamedTupleOfArrays`), and 8 non-public qualified accesses.
   `test_explicit_imports(ReducedComplexityModeling)` fails the implicit-import, public-import and
   public-qualified-access checks. `ArrayOrNamedTuple` and `NamedTupleOfArrays` are imported at
-  `src/ReducedComplexityModeling.jl:26`, for the data loader's dispatch; the other import
+  `src/ReducedComplexityModeling.jl:35`, for the data loader's dispatch; the other import
   statements are present at merge base `3b0554e`. The `Chain` and `NeuralNetwork` imports have no
   diagnostic.
 - **Kind:** defect
@@ -111,3 +111,56 @@
   third element is a fallback that no build reads.
 - **Kind:** defect
 - **Found:** 2026-10-28 (critic round 1b)
+
+### K22 · `reduce!` with `CotangentLiftEVD` or `ComplexSVD` throws when `k` exceeds the columns of the thin SVD
+
+- **Location:** `src/Models/ReducedBasis.jl`, `reduce!(model, k, ::CotangentLiftEVD)` and
+  `reduce!(model, k, ::ComplexSVD)`, at `svd(...).U[:, 1:k]`.
+- **Evidence:** on a `6 × 1` snapshot, `reduce!(ReducedBasisModel(ComplexSVD(), S), 2,
+  ComplexSVD())` throws `BoundsError: attempt to access 3×1 Matrix{ComplexF64} at index [1:3,
+  1:2]`, and `CotangentLiftEVD` with `k = 3` throws `BoundsError: attempt to access 3×2
+  Matrix{Float64} at index [1:3, 1:3]`. The thin SVD has `min(n, columns)` left singular vectors,
+  while a `2n × 2k` basis exists for every `k ≤ n`.
+- **Kind:** defect
+- **Found:** PR #64 (CodeRabbit review on a9d6a90)
+
+### K23 · `reduce!` with `CotangentLiftEVD` or `ComplexSVD` returns a `Float64` basis for a `Float32` snapshot
+
+- **Location:** `src/Models/ReducedBasis.jl`, `reduce!(model, k, ::CotangentLiftEVD)` and
+  `reduce!(model, k, ::ComplexSVD)`, at `zeros(2*n, 2*k)`.
+- **Evidence:** on a `6 × 4` `Float32` snapshot, `eltype(reduce!(model, 1, alg))` is `Float64` for
+  `CotangentLiftEVD()` and `ComplexSVD()`, and `Float32` for `POD()`. `compose` then promotes the
+  reduced problem to `Float64`.
+- **Kind:** defect
+- **Found:** PR #64 (CodeRabbit review on a9d6a90)
+
+### K24 · `GeometricIntegratorEnsembleData` rejects an offset-indexed vector of solutions
+
+- **Location:** `src/TrainingData/GeometricData.jl`, both `Base.Array(solutions, ::Dependent)` and
+  `Base.Array(solutions, ::Independent)`, which read `solutions[1]`, and the constructor, which
+  stores a `Vector{GeometricSolution}`.
+- **Evidence:** `GeometricIntegratorEnsembleData(OffsetVector([s, s], 0:1), deps)` throws
+  `DimensionMismatch: axes must agree, got (Base.OneTo(2),) and
+  (OffsetArrays.IdOffsetRange(values=0:1, indices=0:1),)` for `Dependent()` and for
+  `Independent()`.
+- **Kind:** defect
+- **Found:** PR #64 (CodeRabbit review on a9d6a90)
+
+### K25 · The snapshot functions read `q[1]`, which a solution with only its initial entry does not have
+
+- **Location:** `src/TrainingData/GeometricData.jl`, `snapshot_matrix`, `_snapshot_eltype` and both
+  `Base.Array` methods, at `q[1]`.
+- **Evidence:** CodeRabbit states that GeometricSolutions permits a `step` larger than the number of
+  time steps, and that `q` then holds only its entry at index `0`, so `q[1]` throws. No such
+  solution was built to check this.
+- **Kind:** not verified
+- **Found:** PR #64 (CodeRabbit review on a9d6a90)
+
+### K27 · `Parameter` with a count throws for distinct bounds one or a few ULPs apart
+
+- **Location:** `src/parameters/parameter.jl`, `Parameter(name, minimum, maximum, n::Int)`.
+- **Evidence:** `Parameter(:a, 0.1, nextfloat(0.1), 22)` throws an `AssertionError`, because
+  `LinRange(0.1, nextfloat(0.1), n)` has a point outside the bounds for 368 of the counts in
+  `2:500`. The special case for equal bounds does not cover distinct bounds.
+- **Kind:** defect
+- **Found:** PR #64 (pre-PR verification, 2026-10-29)

docs/make.jl

@@ -33,6 +33,7 @@ makedocs(;
     authors = "Michael Kraus",
     repo = "https://github.com/JuliaRCM/ReducedComplexityModeling.jl/blob/{commit}{path}#{line}",
     sitename = "ReducedComplexityModeling.jl",
+    checkdocs = :all,
     format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
         canonical = "https://JuliaRCM.github.io/ReducedComplexityModeling.jl",

src/Models/ReducedBasis.jl

@@ -1,14 +1,20 @@
+"""
+    POD()
+
+Proper orthogonal decomposition: `reduce!(model, k, POD())` takes the first `k` left singular
+vectors of the snapshot matrix as the reduced basis.
+"""
 struct POD end
 struct CotangentLiftSVD end
 struct CotangentLiftEVD end
 struct ComplexSVD end
 
 """
-Reduced Basis
-
-Uses ModelOrderReduction methods from ReducedBasisMethods.jl
-to represent the data in latent space.
+    ReducedBasisModel(alg, snapshot)
 
+A reduced-basis model of the snapshot matrix `snapshot`, whose columns are the snapshots, with
+the reduction scheme `alg`, such as [`POD`](@ref). [`reduce!`](@ref) computes the reduced basis
+and stores it in the field `reduced_basis`, which is undefined until then.
 """
 mutable struct ReducedBasisModel <: AbstractModel
     reduction_scheme::Any
@@ -20,6 +26,19 @@ mutable struct ReducedBasisModel <: AbstractModel
     end
 end
 
+"""
+    reduce!(model::ReducedBasisModel, k::Int, ::POD)
+    reduce!(model::ReducedBasisModel, k::Int, ::CotangentLiftEVD)
+    reduce!(model::ReducedBasisModel, k::Int, ::ComplexSVD)
+
+Compute a reduced basis from the snapshot matrix of `model`, whose columns are the snapshots,
+store it in `model.reduced_basis` and return it. With [`POD`](@ref), the basis is the matrix of
+the first `k` left singular vectors of the snapshot matrix. With `CotangentLiftEVD()` and
+`ComplexSVD()`, which the package does not export, the snapshot has `2n` rows, `q` above `p`, and
+the basis is an orthonormal and symplectic `2n × 2k` matrix: the cotangent lift of the first `k`
+left singular vectors of `[q p]`, or the real form of the first `k` left singular vectors of
+`q + im * p`.
+"""
 function reduce!(model::ReducedBasisModel, k::Int, ::POD)
     U, _, _ = svd(model.snapshot)
     model.reduced_basis = U[:, 1:k]
@@ -31,7 +50,7 @@ function reduce!(model::ReducedBasisModel, k::Int, ::CotangentLiftEVD)
     n = floor(Int, size(snapshot, 1)/2)
     q, p = snapshot[1:n, :], snapshot[(n + 1):end, :]
     cotangent_snap = hcat(q, p)
-    U, _, _ = svd(cotangent_snap)[:, 1:k]
+    U = svd(cotangent_snap).U[:, 1:k]
     reduced_basis = zeros(2*n, 2*k)
     reduced_basis[1:n, 1:k] = U
     reduced_basis[(n + 1):(2 * n), (k + 1):(2 * k)] = U
@@ -57,16 +76,24 @@ function reduce!(model::ReducedBasisModel, k::Int, ::ComplexSVD)
     n = floor(Int, size(snapshot, 1)/2)
     q, p = snapshot[1:n, :], snapshot[(n + 1):end, :]
     csvd_snap = q + 1im * p
-    U, _, _ = svd(csvd_snap)
-    ϕ, Ψ = real.(U), imag.(U)
+    U = svd(csvd_snap).U[:, 1:k]
+    Φ, Ψ = real.(U), imag.(U)
     reduced_basis = zeros(2*n, 2*k)
     reduced_basis[1:n, 1:k] = Φ
     reduced_basis[1:n, (k + 1):(2 * k)] = -Ψ
     reduced_basis[(n + 1):(2 * n), 1:k] = Ψ
-    reduced_basis[((n + 1):(2 * n):(k + 1)):(2 * k)] = Φ
+    reduced_basis[(n + 1):(2 * n), (k + 1):(2 * k)] = Φ
     model.reduced_basis = reduced_basis
 end
 
+"""
+    compose(prob::ODEProblem, model::ReducedBasisModel)
+
+The reduced problem of `prob` in the reduced basis `R = model.reduced_basis`: an `ODEProblem` in
+the reduced coordinates `u`, with the vector field `R' * v(R * u)`, where `v` is the vector field
+of `prob`, and the initial condition `R' * q₀`. The time span, the time step and the parameters
+are those of `prob`. Call [`reduce!`](@ref) on `model` first.
+"""
 function compose(prob::ODEProblem, model::ReducedBasisModel)
     Rᵦ = model.reduced_basis
 
@@ -84,6 +111,13 @@ function compose(prob::ODEProblem, model::ReducedBasisModel)
     red_prob
 end
 
+"""
+    project(rsol::GeometricSolution, model::ReducedBasisModel)
+
+Map the solution `rsol` of a reduced problem (see [`compose`](@ref)) back to the full space. The
+result is the matrix `model.reduced_basis * Q`, where the columns of `Q` are the entries of
+`rsol.q`; its columns are the states in the full space.
+"""
 function project(rsol::GeometricSolution, model::ReducedBasisModel)
     Rᵦ = model.reduced_basis
     Rᵦ * snapshot_matrix(rsol.q)

src/ReducedComplexityModeling.jl

@@ -1,3 +1,12 @@
+"""
+    ReducedComplexityModeling
+
+Reduced models of the solutions of geometric integrators: the snapshot data of a solution or an
+ensemble of solutions, reduced bases ([`ReducedBasisModel`](@ref), [`POD`](@ref)), parameters
+and parameter spaces with their samplers, the fit of a model's parameters to data
+([`TrainingProblem`](@ref), [`train`](@ref)), and the loaders that draw batches of data for a
+neural network ([`DataLoader`](@ref), [`Batch`](@ref)).
+"""
 module ReducedComplexityModeling
 
 using ForwardDiff
@@ -62,7 +71,6 @@ export ObservableSpace, IntrinsicSpace, TrainingData
 
 include("Models/Models.jl")
 
-export Array
 export GeometricIntegratorData, GeometricIntegratorEnsembleData
 export Dependent, Independent
 export ReducedBasisModel

src/TrainingData/GeometricData.jl

@@ -8,9 +8,16 @@ function snapshot_matrix(sol::DataSeries)
     for (i, elem) in enumerate(sol)
         Z[i, :] .= elem
     end
-    Array(Z')
+    permutedims(Z)
 end
 
+"""
+    GeometricIntegratorData(solution::GeometricSolution)
+
+The solution of a geometric integrator and its snapshot matrix: the field `snapshot` is a matrix
+with one row per component of the state `q` and one column per entry of `solution.q`, the
+initial state included.
+"""
 struct GeometricIntegratorData
     solution::GeometricSolution
     snapshot::Matrix
@@ -29,15 +36,40 @@ end
 
 abstract type AbstractDependence end
 
+"""
+    Dependent()
+
+The layout of the snapshot of a [`GeometricIntegratorEnsembleData`](@ref) in which the solutions
+form one snapshot matrix: one row per component of the state `q`, and the entries of `q` of the
+first solution, then those of the second, and so on, as its columns. The solutions may have
+different numbers of entries in `q`, but all must have the same number of components of `q`;
+otherwise the constructor throws an `ArgumentError`.
+"""
 struct Dependent <: AbstractDependence end
 
+"""
+    Independent()
+
+The layout of the snapshot of a [`GeometricIntegratorEnsembleData`](@ref) in which each solution
+keeps its own snapshot, along a third dimension: an array of size `ny × nx × ns`, for `ns`
+solutions with `nx` entries of a state `q` with `ny` components. Its slice `[:, :, i]` is the
+snapshot matrix of solution `i`, in the layout of [`GeometricIntegratorData`](@ref). All
+solutions must have the same number of entries in `q` and the same number of components of `q`;
+otherwise the constructor throws an `ArgumentError`.
+"""
 struct Independent <: AbstractDependence end
 
-function Base.Array(solutions::Vector{GeometricSolution}, ::Dependent)
-    ns = length(solutions)
-    nx = length(solutions[1].q)
+# the element type that holds the state `q` of every solution without loss
+function _snapshot_eltype(solutions)
+    mapreduce(solution -> eltype(solution.q[1]), promote_type, solutions)
+end
+
+function Base.Array(solutions::AbstractVector{<:GeometricSolution}, ::Dependent)
+    nx = sum(solution -> length(solution.q), solutions)
     ny = length(solutions[1].q[1])
-    Z = zeros(eltype(solutions[1].q[1]), ns*nx, ny)
+    all(solution -> length(solution.q[1]) == ny, solutions) ||
+        throw(ArgumentError("the Dependent layout needs solutions with equal state dimensions"))
+    Z = zeros(_snapshot_eltype(solutions), nx, ny)
 
     i = 1
     for solution in solutions
@@ -46,28 +78,40 @@ function Base.Array(solutions::Vector{GeometricSolution}, ::Dependent)
             i += 1
         end
     end
-    Array(Z')
+    permutedims(Z)
 end
 
-function Base.Array(solutions::Vector{GeometricSolution}, ::Independent)
+function Base.Array(solutions::AbstractVector{<:GeometricSolution}, ::Independent)
     ns = length(solutions)
     nx = length(solutions[1].q)
     ny = length(solutions[1].q[1])
-    Z = zeros(eltype(solutions[1].q[1]), nx, ny, ns)
+    all(solution -> length(solution.q) == nx, solutions) ||
+        throw(ArgumentError("the Independent layout needs solutions with equal numbers of entries"))
+    all(solution -> length(solution.q[1]) == ny, solutions) ||
+        throw(ArgumentError("the Independent layout needs solutions with equal state dimensions"))
+    Z = zeros(_snapshot_eltype(solutions), nx, ny, ns)
 
     for (i, solution) in enumerate(solutions)
         for (j, elem) in enumerate(solution.q)
             Z[j, :, i] .= elem
         end
     end
-    Array(Z')
+    permutedims(Z, (2, 1, 3))
 end
 
+"""
+    GeometricIntegratorEnsembleData(solutions::AbstractVector{<:GeometricSolution}, deps)
+
+The solutions of an ensemble of geometric integrations and their snapshot, in the layout that
+`deps` selects: [`Dependent`](@ref) or [`Independent`](@ref). The element type of the snapshot
+is the promotion of the element types of the states `q` of all solutions.
+"""
 struct GeometricIntegratorEnsembleData
     solutions::Vector{GeometricSolution}
     snapshot::Array
 
-    function GeometricIntegratorEnsembleData(solutions::Vector{GeometricSolution}, deps::AbstractDependence)
+    function GeometricIntegratorEnsembleData(
+            solutions::AbstractVector{<:GeometricSolution}, deps::AbstractDependence)
         new(solutions, Array(solutions, deps))
     end