Add opt-in scale-test tier

.github/workflows/scale-tests.yml

@@ -0,0 +1,29 @@
+name: Scale Tests
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "37 8 * * 0"
+
+permissions:
+  contents: read
+
+jobs:
+  scale:
+    name: Julia 1 - ubuntu-latest - x64 - scale
+    runs-on: ubuntu-latest
+    timeout-minutes: 75
+    env:
+      QUBOTOOLS_SCALE_TESTS: true
+      QUBOTOOLS_SCALE_MAX_N: 100000
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: julia-actions/setup-julia@v3
+        with:
+          version: "1"
+          arch: x64
+      - uses: julia-actions/cache@v3
+      - uses: julia-actions/julia-buildpkg@v1
+      - name: Run scale tests
+        run: julia --project=. -e 'using Pkg; Pkg.test(; test_args = ["scale-only"])'

docs/build.jl

@@ -30,6 +30,7 @@ const DOCS_PAGES = [
         "File Formats"             => "manual/5-formats.md",
         "Solutions"                => "manual/6-solutions.md",
         "Analysis"                 => "manual/7-analysis.md",
+        "Scalability"              => "manual/8-scalability.md",
     ],
     "Formats" => [
         "BQPJSON"  => "formats/bqpjson.md",

docs/src/manual/8-scalability.md

@@ -0,0 +1,54 @@
+# Scalability
+
+QUBOTools keeps the default test suite focused on small fixtures so that
+`Pkg.test("QUBOTools")` remains suitable for pull requests and local
+development. Large generated instances are covered by an opt-in scale-test tier.
+
+Run the full scale tier from the repository root with:
+
+```bash
+QUBOTOOLS_SCALE_TESTS=true julia --project=. -e 'using Pkg; Pkg.test(; test_args = ["scale-only"])'
+```
+
+To run a smaller local smoke pass, cap the maximum generated dimension:
+
+```bash
+QUBOTOOLS_SCALE_TESTS=true QUBOTOOLS_SCALE_MAX_N=5000 julia --project=. -e 'using Pkg; Pkg.test(; test_args = ["scale-only"])'
+```
+
+The scheduled GitHub Actions scale job runs generated sparse cases at
+`n = 1000`, `5000`, `20000`, and `100000` with average degree 4. These cases
+exercise:
+
+- sparse model construction from generated linear and quadratic dictionaries;
+- dense Sherrington-Kirkpatrick and Wishart synthesis smoke cases at `n = 1000`;
+- energy evaluation on random states;
+- sparse, dictionary, and dense form agreement at `n = 1000`;
+- sparse and dictionary form agreement at larger sizes;
+- QUBin round-trips at every scale-test size;
+- QUBO text round-trips at `n = 20000` and `n = 100000`;
+- exact Float64 preservation for a portfolio-like numerical range from
+  `1e-3` through `2e10`;
+- `SampleSet` construction and duplicate-state merging with large states.
+
+## Practical Envelope
+
+Sparse forms are the intended representation for large generated and archived
+instances. A sparse quadratic form is backed by Julia's `SparseMatrixCSC`, which
+stores one row index and one value per nonzero term plus one column pointer per
+variable. With 64-bit indices and `Float64` coefficients, the dominant storage
+is about 16 bytes per quadratic nonzero plus about 8 bytes per variable for
+column pointers. Sparse linear terms add about 16 bytes per nonzero. Temporary
+construction dictionaries and I/O buffers require additional memory, so peak
+memory is higher than the final sparse form.
+
+Dense forms use an `n x n` `Float64` matrix for quadratic terms. That is about
+`8n^2` bytes before Julia array overhead, so dense forms are practical only for
+small cross-checks. The scale tier limits dense correctness checks to
+`n = 1000`.
+
+The current scheduled envelope is sparse instances with 100000 variables and
+about 200000 quadratic terms. Denser QOBLib-style archives with millions of
+terms should be tested with a dedicated benchmark or data-validation workflow so
+their time and memory budgets can be reviewed separately from regular package
+tests.

src/library/form/sparse.jl

@@ -6,12 +6,19 @@ struct SparseLinearForm{T} <: AbstractLinearForm{T}
 end
 
 function SparseLinearForm{T}(n::Integer, lf::LF) where {T,S,LF<:AbstractLinearForm{S}}
-    data = spzeros(T, n)
+    indices = Int[]
+    values = T[]
+    sizehint!(indices, linear_size(lf))
+    sizehint!(values, linear_size(lf))
 
     for (i, v) in linear_terms(lf)
-        data[i] = convert(T, v)
+        push!(indices, i)
+        push!(values, convert(T, v))
     end
 
+    data = sparsevec(indices, values, n)
+    dropzeros!(data)
+
     return SparseLinearForm{T}(data)
 end
 
@@ -55,12 +62,22 @@ struct SparseQuadraticForm{T} <: AbstractQuadraticForm{T}
 end
 
 function SparseQuadraticForm{T}(n::Integer, qf::QF) where {T,S,QF<:AbstractQuadraticForm{S}}
-    data = zeros(T, n, n)
+    rows = Int[]
+    cols = Int[]
+    values = T[]
+    sizehint!(rows, quadratic_size(qf))
+    sizehint!(cols, quadratic_size(qf))
+    sizehint!(values, quadratic_size(qf))
 
     for ((i, j), v) in quadratic_terms(qf)
-        data[i, j] = convert(T, v)
+        push!(rows, i)
+        push!(cols, j)
+        push!(values, convert(T, v))
     end
 
+    data = sparse(rows, cols, values, n, n)
+    dropzeros!(data)
+
     return SparseQuadraticForm{T}(data)
 end
 

src/library/format/qubo/parser.jl

@@ -49,7 +49,10 @@ function _parse_entry!(
     L = data[:linear_terms]
     Q = data[:quadratic_terms]
 
-    m = match(r"^([0-9]+)\s+([0-9]+)\s+([+-]?([0-9]*[.])?[0-9]+)$", line)
+    m = match(
+        r"^([0-9]+)\s+([0-9]+)\s+([+-]?(([0-9]+([.][0-9]*)?)|([.][0-9]+))([eE][+-]?[0-9]+)?)$",
+        line,
+    )
 
     if isnothing(m)
         return false
@@ -72,7 +75,10 @@ function _parse_entry!(data::Dict{Symbol,Any}, line::AbstractString, ::Format{:q
     L = data[:linear_terms]
     Q = data[:quadratic_terms]
 
-    m = match(r"^([0-9]+)\s+([0-9]+)\s+([+-]?([0-9]*[.])?[0-9]+)$", line)
+    m = match(
+        r"^([0-9]+)\s+([0-9]+)\s+([+-]?(([0-9]+([.][0-9]*)?)|([.][0-9]+))([eE][+-]?[0-9]+)?)$",
+        line,
+    )
 
     if isnothing(m)
         return false

src/library/format/rudy/format.jl

@@ -38,7 +38,7 @@ function parse_comment!(data, line::AbstractString, ::Format{:rudy})
     end
 
     # Constant term of objective = 66363.47
-    let m = match(r"^# Constant term of objective = ([+-]?([0-9]+([.][0-9]*)?|[.][0-9]+))$", line)
+    let m = match(r"^# Constant term of objective = ([+-]?(([0-9]+([.][0-9]*)?)|([.][0-9]+))([eE][+-]?[0-9]+)?)$", line)
         if !isnothing(m)
             data.offset = parse(Float64, m[1])
 
@@ -52,7 +52,7 @@ end
 function parse_line!(data::RUDY_DATA{T}, line::AbstractString, fmt::Format{:rudy}) where {T}
     startswith(line, "#") && return parse_comment!(data, line, fmt)
 
-    let m = match(r"^(\d+)\s+(\d+)\s+([+-]?([0-9]+([.][0-9]*)?|[.][0-9]+))$", line)
+    let m = match(r"^(\d+)\s+(\d+)\s+([+-]?(([0-9]+([.][0-9]*)?)|([.][0-9]+))([eE][+-]?[0-9]+)?)$", line)
         if !isnothing(m)
             # Note: rudy is 0-indexed!
             i = parse(Int, m[1]) + 1
@@ -72,6 +72,26 @@ function parse_line!(data::RUDY_DATA{T}, line::AbstractString, fmt::Format{:rudy
     end
 end
 
+function QUBOTools.write_model(io::IO, model::QUBOTools.AbstractModel, fmt::QUBOTools.Format{:rudy})
+    Φ = QUBOTools.form(model, :sparse; domain = fmt[:domain])
+    α = QUBOTools.scale(Φ)
+
+    println(io, "# Constant term of objective = $(α * QUBOTools.offset(Φ))")
+    println(io, "# Diagonal terms")
+
+    for (i, h) in QUBOTools.linear_terms(Φ)
+        println(io, "$(i - 1) $(i - 1) $(α * h)")
+    end
+
+    println(io, "# Off-Diagonal terms")
+
+    for ((i, j), J) in QUBOTools.quadratic_terms(Φ)
+        println(io, "$(i - 1) $(j - 1) $(α * J)")
+    end
+
+    return nothing
+end
+
 function QUBOTools.read_model(io::IO, fmt::QUBOTools.Format{:rudy})
     data = RUDY_DATA{Float64}(; domain = QUBOTools.domain(fmt[:domain]))
 

test/runtests.jl

@@ -28,14 +28,26 @@ const QUBOModel     = QUBOTools_MOI.QUBOModel
 const NumberOfReads = QUBOTools_MOI.NumberOfReads
 
 const __TEST_PATH__ = @__DIR__
+const __SCALE_ONLY__ = "scale-only" in ARGS
+
+function _scale_tests_requested()
+    return lowercase(get(ENV, "QUBOTOOLS_SCALE_TESTS", "false")) in
+           Set(["1", "true", "yes", "on"])
+end
 
 # Include assets
 include("assets/comparison.jl")
 include("assets/foreign_tests.jl")
 
 # Include test functions
-include("unit/unit.jl")
-include("integration/integration.jl")
+if __SCALE_ONLY__ || _scale_tests_requested()
+    include("scale/scale.jl")
+end
+
+if !__SCALE_ONLY__
+    include("unit/unit.jl")
+    include("integration/integration.jl")
+end
 
 function test_main()
     @testset "◈ ◈ ◈ QUBOTools.jl Test Suite ◈ ◈ ◈" verbose = true begin
@@ -46,4 +58,12 @@ function test_main()
     return nothing
 end
 
-test_main() # Here we go!
+if __SCALE_ONLY__
+    test_scale()
+else
+    test_main() # Here we go!
+
+    if _scale_tests_requested()
+        test_scale()
+    end
+end

test/scale/runtests.jl

@@ -0,0 +1,11 @@
+using Test
+using Random
+using QUBOTools
+
+include("scale.jl")
+
+if _scale_tests_enabled()
+    test_scale()
+else
+    @info "Set QUBOTOOLS_SCALE_TESTS=true to run the scale-test tier"
+end