Skip to content

Add scale-free reservoir initializer - #578

Open
aviralgarg05 wants to merge 2 commits into
SciML:masterfrom
aviralgarg05:feat/scale-free-topology-387
Open

aviralgarg05 wants to merge 2 commits into
SciML:masterfrom
aviralgarg05:feat/scale-free-topology-387

Conversation

@aviralgarg05

@aviralgarg05 aviralgarg05 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • add an undirected Barabási–Albert reservoir initializer
  • support reproducible weights, spectral-radius scaling, and sparse output
  • document the initializer and cover its topology, validation, and boundary cases

Tests

  • GROUP=Core julia --project -e 'using Pkg; Pkg.test()'
  • julia --project -e 'using Test; include("test/inits_tests.jl")'
  • Runic formatting check

Fixes #387

Implement an undirected Barabasi-Albert topology with reproducible weighted connections, spectral-radius scaling, and sparse output support. Add validation, API docs, and focused topology tests.
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

🤖 Automated comment from an AI agent running as @ChrisRackauckas — not written or reviewed by Chris.

PR: #578

Reviewed head: 8355a14
Raw SHA-256: d5000c73b84729fc6328eb3b6f23ac4073f822f7adc81ccdc18e9b6ac6e80741
Source SHA-256: 942cf023c882c4e8d3b2215a53bd2a65891910f5fb87e4743a4eb857f5beaf92
Source: standard-review-v1 (harness-log)
Reviewer session: 01a1f828-68f4-75e3-8622-b0a4e040c4bb
Slot: 1
Confidence: unknown
Own risk fixed before author rating/discussion: yes
Redaction: ran (substitutions=0)

Risk assessment

  • Risk: medium-low (ML7)
  • Verdict: CHANGES
  • Reviewed head: 8355a14

Review report

VERDICT: CHANGES
Round: 1
Head: 8355a14
Slot: 1
CI: CI is not green
Session: 01a1f828-68f4-75e3-8622-b0a4e040c4bb
Reviewer: codex-cli 0.170.0; model: gpt-6.2-astra

Risk

medium-low (ML7: new exported initializer with a docstring, rendered API entry and tests)

Blocking findings

  • [P1] src/inits/inits_reservoir.jl:306 silently returns the wrong spectral radius for valid inputs, including the default element type. With Julia 1.12.4, A = scale_free(Xoshiro(1971721), 3, 3; initial_nodes=2, attachments=1) requests 1 and returns 0.357977. This graph is the path 1–2–3, so its exact radius is sqrt(abs(A[1,2]*A[2,1] + A[2,3]*A[3,2])) evaluated on the stored entries in Float64. Independently, maximum(abs, eigvals(Float64.(A))) gave 0.3579769865. The Float32 eigensolve overestimates the radius before scaling. Output rounding can also dominate: the same call with Xoshiro(19672), Float16 returns radius 2.755676, even though all entries are finite. Use a wider working type for the eigenvalue calculation and verify the realized radius after conversion to the output type. If rounding makes the target unattainable for those weights, redraw weights on the same topology or report an explicit error. Add regression coverage for both cases.

  • [P2] test/inits_tests.jl:75 lets uniform attachment pass as preferential attachment. I changed both degree contributions in the sampler to 1 in a scratch copy. All 18 new assertions still passed. A deterministic four-node test distinguishes the models: start with two nodes, one attachment, and have the RNG return 1 for the first parent draw and 2 for the second. Node 3 then joins node 1, giving degrees [2,1,1]. Draw 2 must attach node 4 to node 1. I observed node 1 at the reviewed head and node 2 with uniform sampling. Add that assertion to protect the defining property without fitting a degree-distribution tolerance.

  • [P2] src/inits/inits_reservoir.jl:248 accepts negative radii. With Xoshiro(1), Float64, 4, 4; initial_nodes=2, attachments=1, radius=-0.75, the call succeeded and returned spectral radius 0.75. Reject negative targets before consuming the RNG and test that input.

  • Blocking priorities: P1, P2, P2

Non-blocking findings

  • src/inits/inits_reservoir.jl:250 accepts any Number, but Int failed inside eps(Int) and ComplexF32 failed when its default radius reached the Real keyword. Document the supported real floating-point element types and give unsupported callers a clear error.
  • Project.toml:3 still declares 0.12.47. Include the new export in a minor release under the supplied versioning policy.

What I ran

  • Julia 1.12.4, with the repository's project and test dependencies resolved in scratch. GROUP=Core julia --project=. -e 'using Pkg; Pkg.test(julia_args=["--compiled-modules=existing"])' passed all nine Core files, including Core/inits_tests.jl | 965 965. The first plain run exited with signal 11. A retry with compiled modules and package images disabled failed the explicit precompilation assertion in test/deprecated.jl:27. The standalone strict precompile and final Core run both exited 0.
  • Ran the added testset against origin/master using the same resolved dependencies. It errored on its first call with UndefVarError: scale_free. Ran the uniform-sampling mutation and scripted draws described above. Across 4,096 seeds, node 4 picked the degree-two parent 2,007 times, consistent with its model probability of 1/2.
  • Checked 480 growth-prefix assertions over Float16, Float32 and Float64, plus seven call-form, RNG and integer-size assertions. All passed. The seed clique was complete and every later node had exactly the requested number of distinct older neighbors, establishing connectivity. The committed seeded dense/sparse equivalence test also passed.
  • julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include("docs/make.jl")' exited 0 with doctests enabled. Verified that the generated initializer index links to the rendered scale_free page and that the page contains both examples. Runic.jl 1.13.0 in whole-tree --check mode and git diff --check origin/master...HEAD both exited 0.
  • uv run --locked python --version printed Python 3.13.13 and warned that --locked has no effect outside a project. The checkout provides a Julia project and has no Python lockfile or committed Julia manifest.

What I did not verify

GPU behavior, large-reservoir performance and test groups outside Core. I did not inspect remote CI.

AUTHOR_GRADE: {"task":"feature","score":3,"difficulty":3,"rounds":1,"author_harness":"unknown","author_model":"unknown","note":"The attachment implementation, call forms, sparse output and docs passed independent checks. The tests accept uniform attachment, and valid Float32 and Float16 calls silently miss the requested spectral radius."}

Head link: 8355a14


🤖 Posted by an AI agent — harness: codex-cli 0.170.0 · model: gpt-6.2-astra
Conversation: local session 01a1f828-68f4-75e3-8622-b0a4e040c4bb (no session URL)

@aviralgarg05

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed reproductions. I reproduced all three blocking cases locally and addressed them. Radius scaling now uses widened precision, verifies the realized output radius, and redraws weights on the same topology when output rounding makes a sample unsuitable. Invalid radii and unsupported element types are rejected before the RNG is consumed. I also added a deterministic preferential-attachment regression and the reported Float32/Float16 cases. The full Core suite passes, including 974 initializer tests, along with 1,500 additional seed/type radius checks.

@ChrisRackauckas

Copy link
Copy Markdown
Member

🤖 Automated comment from an AI agent running as @ChrisRackauckas — not written or reviewed by Chris.

PR: #578

Reviewed head: 819f564
Raw SHA-256: 6cd8bd9010d26b3786f7a0da32ea1c493a8bae47ec50912c17f77332c9083b14
Source SHA-256: 5f782096f65b5b72f50a5355417362e0505df98a0d445b6037b2d02cb8f79440
Source: standard-review-v1 (harness-log)
Reviewer session: 01a1faa0-990f-7773-95d9-0d82be0fb5bb
Slot: 1
Confidence: unknown
Own risk fixed before author rating/discussion: yes
Redaction: ran (substitutions=0)

Risk assessment

  • Risk: medium-low (ML7)
  • Verdict: CHANGES
  • Reviewed head: 819f564

Review report

VERDICT: CHANGES
Round: 2
Head: 819f564
Slot: 1
CI: green
Session: 01a1faa0-990f-7773-95d9-0d82be0fb5bb
Reviewer: codex-cli 0.169.0; model: gpt-6.2-astra

Risk

medium-low (ML7: new exported initializer with a docstring, rendered API entry and tests. Existing initializer calls retain their behavior.)

Blocking findings

  • [P1] src/inits/inits_reservoir.jl:341 accepts a spectral radius more than twice the target. I ran scale_free(Xoshiro(19672), Float16, 3, 3; initial_nodes=2, attachments=1, radius=0.01). The target rounds to 0.01000213623 in Float16, but the stored matrix has radius 0.02073902401. With Xoshiro(1971721), Float32 and radius=0.001, the same call returns radius 0.0009785848393, a 2.14% error. I verified both with Float64 eigenvalues and independently with the three-node tree formula sqrt(abs(Σ A[i,j]*A[j,i])), summing over i < j in BigFloat. The absolute tolerance floors its scale at one, so substantial relative errors pass for small positive targets. Use a relative tolerance for positive targets at both acceptance checks, keep zero explicit, and add a subunit-target regression using the tree formula.

  • [P2] src/inits/inits_reservoir.jl:260 converts the radius before checking its sign. I ran scale_free(Xoshiro(1), Float16, 4, 4; initial_nodes=2, attachments=1, radius=-1e-8). The target rounds to negative zero, the call returns an all-zero matrix, and it advances the RNG. Float32 with radius=-1e-100 does the same. Check the original real argument for negativity before narrowing it, and cover a negative input that rounds to zero.

  • Blocking priorities: P1, P2

Non-blocking findings

  • src/inits/inits_reservoir.jl:347 repeats the dense eigensolve that just accepted the same matrix at line 337. At 128 nodes, a warmed Float32 initialization allocated 1,270,696 bytes. Evaluating that last check alone on its output allocated 308,536 bytes. Return the accepted matrix directly or retain the acceptance result through loop exit.

What I ran

  • Julia 1.13.2, using the package project and its declared test dependencies in a scratch copy of the head. GROUP=Core julia --project=. -e 'using Pkg; Pkg.test(; julia_args=["--compiled-modules=existing"])' passed all nine Core files, including Core/inits_tests.jl | 974 974. git diff --check origin/master...HEAD passed. uv run --locked python --version printed Python 3.15.0 and warned that the lock flag has no effect outside a Python project. The checkout has neither a Python lockfile nor a committed Julia manifest.
  • Replayed the earlier seeds at radius one. The stored matrices had radii 1.00000000108 for Float32 and 1.00015257625 for Float16. Across 288 Float32/Float64 seed, shape and target combinations, dense and sparse results agreed exactly. Sizes ranged from 2 to 32 and included cliques and single-attachment trees. The largest Float64 relative error was 5.33e-15.
  • Replaced both degree weights with unit weights in the sampler in an isolated Julia process and ran the committed initializer test file. The scale-free testset reported 25 passes and two failures, precisely at test/inits_tests.jl:121 and :122. Node 4 attached to node 2. The unmodified sampler passed both assertions.
  • Ordinary negative radii, NaN, both infinities, a complex radius, invalid element types and out-of-range node or attachment counts raised ArgumentError. An exact zero target returned a zero matrix. Non-square dimensions and wrong arity raised the package's DimensionMismatch.
  • Confirmed the export and exact seeded repeatability. Julia inferred a union of the dense and sparse matrix types even for wrappers with a fixed output choice. Warmed dense Float32 calls allocated 128,344 bytes at 16 nodes, 411,712 at 64 and 1,270,696 at 128.
  • Ran the project's Documenter build through makedocs with doctests enabled. It exited 0. Verified the rendered initializer index links to the scale-free API page and the page contains the model description and both examples.

What I did not verify

Other Julia versions, groups outside Core and large-reservoir timing. The CI status above was supplied for this head.

AUTHOR_GRADE: {"task":"feature","score":3,"difficulty":3,"rounds":2,"author_harness":"unknown","author_model":"unknown","note":"The new test detects uniform attachment and both unit-radius regressions pass. Representable subunit targets can still miss by over 100%, and narrowing accepts some negative inputs."}

Head link: 819f564


🤖 Posted by an AI agent — harness: codex-cli 0.169.0 · model: gpt-6.2-astra
Conversation: local session 01a1faa0-990f-7773-95d9-0d82be0fb5bb (no session URL)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scale free topology

3 participants