refactor(us-ci-018): replace empty updateparameters with invalidoperationexception in specialized networks

[ooples]

Summary

Replace empty UpdateParameters method implementations with InvalidOperationException in neural network classes that don't support traditional gradient-based parameter updates. This provides clearer API semantics and better error messages explaining why the operation isn't supported and what alternative methods should be used instead.

Changes

• EchoStateNetwork: Throw InvalidOperationException explaining that only output layer weights are trained via Train method; reservoir weights remain fixed
• ExtremeLearningMachine: Throw InvalidOperationException explaining that input-to-hidden weights are randomly initialized and remain fixed; only output layer weights are computed analytically
• NEAT: Throw InvalidOperationException explaining to use EvolvePopulation method instead of gradient-based updates
• RestrictedBoltzmannMachine: Throw InvalidOperationException explaining to use Train method with Contrastive Divergence

Rationale

Previously, these methods had empty implementations with only comments. According to the user story US-CI-018, classes that don't use traditional parameter updates should throw InvalidOperationException with clear explanatory messages. This change:

1. Makes the API contract more explicit - these are design choices, not missing implementations
2. Provides helpful error messages guiding users to the correct methods
3. Follows the pattern already established in HopfieldNetwork
4. Improves code maintainability and developer experience

Testing

• Build successful for all target frameworks (net462, net6.0, net7.0, net8.0)
• No breaking changes to public API surface
• Error messages are descriptive and actionable

Related

• User Story: US-CI-018

🤖 Generated with Claude Code

[coderabbitai]

Summary by CodeRabbit

• Bug Fixes
  • Enhanced error handling across multiple neural network implementations. Direct parameter updates now throw explicit exceptions with descriptive messages, preventing silent failures and guiding users toward correct training workflows.

Walkthrough

Four neural network implementations (EchoStateNetwork, ExtremeLearningMachine, NEAT, and RestrictedBoltzmannMachine) have been updated to replace no-op behavior in their UpdateParameters methods with explicit exception throwing, providing descriptive messages explaining why direct parameter updates are unsupported for each architecture.

Changes

Cohort / File(s)

Summary

Neural Network Parameter Update Behavior src/NeuralNetworks/EchoStateNetwork.cs, src/NeuralNetworks/ExtremeLearningMachine.cs, src/NeuralNetworks/NEAT.cs, src/NeuralNetworks/RestrictedBoltzmannMachine.cs

UpdateParameters method now throws InvalidOperationException with architecture-specific message instead of no-op behavior. ESN indicates only output layer weights are trained; ELM indicates only Train method computes output-layer weights; NEAT provides NEAT-specific rationale; RBM indicates training should use Train/Contrastive Divergence. Minor comment refinements in NEAT's InitializePopulation path.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Homogeneous changes across all four files following identical pattern (no-op → exception throwing)
• No complex logic or control flow modifications
• Straightforward message updates aligned with each architecture's constraints
• Each method change is self-contained with descriptive exception messages

Poem

🐰 Four networks learned their limits true,
No more shall parameters bend askew!
"Not supported!" their methods cry,
With messages clear—now we know why.
Reserved weights and trained layers aligned,
Leave UpdateParameters behind! 🎯

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "refactor(us-ci-018): replace empty updateparameters with invalidoperationexception in specialized networks" directly and accurately describes the main changes in the changeset. The title explicitly states what is being done (replacing empty implementations with exceptions), which is exactly what the modifications to EchoStateNetwork, ExtremeLearningMachine, NEAT, and RestrictedBoltzmannMachine demonstrate. The title is specific, avoids vague terminology, and includes a user story reference for additional context, making it clear for teammates scanning the repository history.
Description Check	✅ Passed	The pull request description is clearly related to the changeset and provides meaningful information about the modifications. It summarizes the purpose of the changes, lists specific updates for each affected class with details about the error messages, explains the rationale by referencing user story US-CI-018 and the existing HopfieldNetwork pattern, and includes testing verification. The description is neither vague nor generic; it demonstrates a clear understanding of what is being changed and why, making it helpful for reviewers to understand the intent and scope of the changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/us-ci-018-neuralnetworkbase-exceptions

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

src/NeuralNetworks/RestrictedBoltzmannMachine.cs (1)

431-454: Fix XML documentation inconsistency with exception type.

The XML documentation at line 434 references NotImplementedException:

/// <exception cref="NotImplementedException">
/// Always thrown because ELM does not support traditional parameter updates.
/// </exception>

However, the implementation at line 453 now throws InvalidOperationException. Update the XML documentation to match the actual exception type.

Apply this diff:

     /// <param name="parameters">The vector of parameter updates to apply.</param>
-    /// <exception cref="NotImplementedException">Always thrown as this method is not implemented for RBMs.</exception>
+    /// <exception cref="InvalidOperationException">Always thrown as this method is not supported for RBMs.</exception>
     /// <remarks>

src/NeuralNetworks/EchoStateNetwork.cs (1)

1020-1047: Fix XML documentation inconsistency with exception type.

The XML documentation at line 1024 references NotImplementedException:

/// <exception cref="NotImplementedException">
/// Always thrown because ESN does not support traditional parameter updates.
/// </exception>

However, the implementation at line 1046 now throws InvalidOperationException. Update the XML documentation to match.

Apply this diff:

     /// <param name="parameters">A vector containing the parameters to update all layers with.</param>
-    /// <exception cref="NotImplementedException">
+    /// <exception cref="InvalidOperationException">
     /// Always thrown because ESN does not support traditional parameter updates.
     /// </exception>

src/NeuralNetworks/ExtremeLearningMachine.cs (1)

121-148: Fix XML documentation inconsistency with exception type.

The XML documentation at line 125 references NotImplementedException:

/// <exception cref="NotImplementedException">
/// Always thrown because ELM does not support traditional parameter updates.
/// </exception>

However, the implementation at line 147 now throws InvalidOperationException. Update the XML documentation to match.

Apply this diff:

     /// <param name="parameters">A vector containing the parameters to update all layers with.</param>
-    /// <exception cref="NotImplementedException">
+    /// <exception cref="InvalidOperationException">
     /// Always thrown because ELM does not support traditional parameter updates.
     /// </exception>

src/NeuralNetworks/NEAT.cs (1)

582-612: Fix XML documentation inconsistency with exception type.

The XML documentation at line 586 references NotImplementedException:

/// <exception cref="NotImplementedException">Always thrown, as this method is not applicable to NEAT.</exception>

However, the implementation at line 611 now throws InvalidOperationException. Update the XML documentation to match.

Apply this diff:

     /// <param name="parameters">A vector containing parameters to update.</param>
-    /// <exception cref="NotImplementedException">Always thrown, as this method is not applicable to NEAT.</exception>
+    /// <exception cref="InvalidOperationException">Always thrown, as this method is not applicable to NEAT.</exception>
     /// <remarks>

🧹 Nitpick comments (3)

src/NeuralNetworks/RestrictedBoltzmannMachine.cs (1)

113-113: Optional cosmetic improvement: multiplication symbol.

The change from 28x28 to 28×28 uses the proper multiplication symbol, improving readability. This is a minor refinement and acceptable.

src/NeuralNetworks/ExtremeLearningMachine.cs (1)

228-291: Optional: Improved mathematical notation in comments.

The use of the proper pseudoinverse symbol (A†) and multiplication symbols (·) in the comments at lines 228, 260, 271, 278, 284, and 291 improves mathematical precision and readability. These cosmetic refinements are acceptable.

src/NeuralNetworks/NEAT.cs (1)

299-299: Optional cosmetic improvement: multiplication symbol.

The change from 3 inputs x 2 outputs to 3 inputs × 2 outputs uses the proper multiplication symbol, consistent with the other cosmetic improvements in this PR.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 129830d and 4917acb.

📒 Files selected for processing (4)

• src/NeuralNetworks/EchoStateNetwork.cs (1 hunks)
• src/NeuralNetworks/ExtremeLearningMachine.cs (4 hunks)
• src/NeuralNetworks/NEAT.cs (2 hunks)
• src/NeuralNetworks/RestrictedBoltzmannMachine.cs (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/NeuralNetworks/ExtremeLearningMachine.cs (1)

src/NeuralNetworks/EchoStateNetwork.cs (3)

• Matrix (629-648)
• Matrix (1319-1405)
• Matrix (1687-1703)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build All Frameworks

🔇 Additional comments (4)

src/NeuralNetworks/RestrictedBoltzmannMachine.cs (1)

453-453: Excellent error message: descriptive and actionable.

The exception message clearly explains why direct parameter updates aren't supported and directs users to the appropriate alternative (Train method with Contrastive Divergence). This follows good API design practices.

src/NeuralNetworks/EchoStateNetwork.cs (1)

1046-1046: Clear and accurate exception message.

The message correctly explains that ESN reservoir weights remain fixed and only output layer weights are trained via ridge regression in the Train method. This aligns well with ESN architecture principles.

src/NeuralNetworks/ExtremeLearningMachine.cs (1)

147-147: Well-crafted exception message for ELM.

The message precisely describes the ELM training paradigm: fixed random input-to-hidden weights and analytically computed output weights. This provides clear guidance to users.

src/NeuralNetworks/NEAT.cs (1)

611-611: Comprehensive exception message for NEAT.

The exception message effectively communicates that NEAT uses evolutionary algorithms (EvolvePopulation) rather than gradient-based parameter updates. The message is clear and actionable.