Merge pull request #147 from USACE-RMC/bug-fixes-and-enhancements

Prepare v2.2.0 release

Author: HadenSmith

.github/workflows/Integration.yml

@@ -6,7 +6,31 @@ on:
 
 jobs:
   CI:
-    uses: HydrologicEngineeringCenter/dotnet-workflows/.github/workflows/integration.yml@main
-    with:
-      dotnet-version: '10.0.x'
-      run-tests: true
+    # Preserve the check name used by the previous reusable workflow.
+    name: CI / CI
+    runs-on: windows-latest
+    timeout-minutes: 90
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET SDKs
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+            9.0.x
+            10.0.x
+
+      - name: Build
+        run: dotnet build -c Release
+
+      - name: Test
+        env:
+          VSTEST_CONNECTION_TIMEOUT: '600'
+        # Live provider outages and full-record download timeouts must not block PRs.
+        # Keep deterministic download, parsing, validation, and numerical tests in the gate.
+        run: dotnet test -c Release --no-build --filter "TestCategory!=LiveServiceIntegration"

.github/workflows/Snapshot.yml

@@ -10,8 +10,8 @@ jobs:
     with:
       dotnet-version: '10.0.x'
       project-names: 'Numerics'
-      # Snapshot workflow appends .<run_number>-dev, so this tracks the next development patch after v2.1.4.
-      version: '2.1.5'
+      # Snapshot workflow appends .<run_number>-dev, so this tracks the next development patch after v2.2.0.
+      version: '2.2.1'
       # PR integration already runs the full multi-target test suite.
       run-tests: false
       nuget-source: 'https://www.hec.usace.army.mil/nexus/repository/consequences-nuget-public/'

.gitignore

@@ -372,9 +372,5 @@ MigrationBackup/
 /TestResults
 
 # Local developer guidance and settings. These files are for developer machines only.
-/CLAUDE.md
-/Claude.md
-/AGENTS.md
-/Agents.md
 /.claude/
 /.agents/

AGENTS.md

@@ -0,0 +1,121 @@
+# Numerics Local Development Rules
+
+## Technical Authority and Algorithm Change Control (NON-NEGOTIABLE)
+
+Haden Smith is the final technical and numerical authority for this repository. AI agents,
+including Codex and Claude, must never change an established algorithm, formula,
+probability-combination rule, numerical method, convergence rule, default tolerance,
+random-seed behavior, clipping or normalization policy, or reference-result contract without
+Haden Smith's explicit prior approval. A failing test authorizes diagnosis and a proposed fix
+only; it does not authorize tuning or replacing the algorithm. When an agent's reasoning
+conflicts with Haden Smith's direction or domain judgment, the agent must stop, present the
+evidence, and request a decision. AI confidence is not technical authority.
+
+## Quality Gate
+
+- No compiler errors.
+- No compiler warnings.
+- Do not suppress warnings to make a build pass; fix the code, XML documentation, or invalid reference.
+- Empty catch blocks are not allowed. Preserve exception context when rethrowing or wrapping.
+
+## XML Documentation
+
+- XML documentation is mandatory for all public API additions and changes.
+- Public classes, structs, interfaces, enums, constructors, properties, methods, events, and fields require accurate XML documentation.
+- Private or internal methods with non-obvious algorithms should also be documented.
+- Include `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` whenever they apply.
+- Use `<remarks>` for numerical method notes, assumptions, references, and domain-specific constraints.
+- XML documentation warnings `CS1570`, `CS1571`, `CS1572`, `CS1573`, `CS1574`, `CS1584`, `CS1587`, `CS1589`, and `CS1591` are build errors when `EnforceXmlDocumentation=true`.
+
+## Unit Tests
+
+- Every behavior change must include unit tests or an explicit reason no test is useful.
+- Every new public class requires corresponding coverage in `Test_Numerics`.
+- Statistical and numerical methods must cover known values, edge cases, invalid inputs, and regression cases.
+- Use small inline fixtures in tests unless a shared fixture already exists for the exact scenario.
+
+## Required Validation
+
+Run validation before committing:
+
+```powershell
+dotnet build -c Release
+dotnet test -c Release --no-build
+```
+
+Both commands must complete with zero errors, zero warnings, and zero failed tests. If validation fails, fix the issue before committing.
+
+## Git Workflow
+
+- Commit after successful build and test validation for the completed logical change.
+- Stage only files that belong to the validated change.
+- Do not include unrelated tracked changes or untracked local files.
+- Use concise commit messages that describe the change.
+- Do not push unless explicitly asked.
+
+## PR and Release Workflow
+
+Use this workflow for release-preparation pull requests and public package releases.
+
+### Release PR Planning
+
+- Base release PRs on `bug-fixes-and-enhancements` targeting `main` unless the user gives a different branch plan.
+- Identify the last merged PR from the release branch and list every commit since that merge.
+- Merge `origin/main` into the release branch before editing so current README, JOSS, citation, and metadata updates are preserved.
+- Define the release outcome up front, including the exact `RMC.Numerics` version that NuGet.org must show as the latest public package after publishing.
+
+### Version and Metadata Checklist
+
+Update and cross-check every version-bearing file for each release:
+
+- `Numerics/Numerics.csproj`: set `Version`, `AssemblyVersion`, and `PackageReleaseNotes`.
+- `CITATION.cff`: set `version` and `date-released`.
+- `codemeta.json`: set `version` and `dateModified`.
+- `.github/workflows/Snapshot.yml`: advance the snapshot version to the next patch after the release.
+- Keep `PackageReleaseNotes` concise because NuGet.org displays this field on the package page.
+
+### PR Message Checklist
+
+Use a title like `Prepare vX.Y.Z release`.
+
+Include these sections in the PR body:
+
+- `Summary`: package, citation, CodeMeta, and snapshot metadata updates.
+- `Summary`: user-facing fixes, reliability changes, API changes, and test coverage added since the previous release branch merge.
+- `Validation`: required commands and package inspection results.
+
+Use this validation checklist:
+
+```markdown
+- [ ] `dotnet restore`
+- [ ] `dotnet build Numerics/Numerics.csproj -c Release /p:Version=X.Y.Z`
+- [ ] `dotnet test -c Release` with `VSTEST_CONNECTION_TIMEOUT=600`
+- [ ] `dotnet pack Numerics/Numerics.csproj -c Release /p:Version=X.Y.Z --no-build -o ./packages`
+- [ ] Inspect the `.nupkg` metadata and confirm version `X.Y.Z` and release notes are correct.
+```
+
+### Release Message Checklist
+
+Create a GitHub Release titled `Numerics vX.Y.Z`.
+
+Include these sections in the release body:
+
+- `Highlights`: short release overview.
+- `Reliability and Fixes`: behavior fixes and reliability improvements.
+- Domain-specific sections for API, statistics, time-series, numerical methods, or other notable changes.
+- `Install`: package install command.
+
+Use this install command format:
+
+```bash
+dotnet add package RMC.Numerics --version X.Y.Z
+```
+
+### Publish Workflow
+
+- Merge the validated PR to `main`.
+- Tag the merge commit as `vX.Y.Z`.
+- Push the tag so `.github/workflows/Release.yml` publishes to the internal Nexus feed.
+- Create and publish a non-draft, non-prerelease GitHub Release for `vX.Y.Z`.
+- Confirm `.github/workflows/NuGetPublish.yml` publishes `RMC.Numerics.X.Y.Z.nupkg` to NuGet.org.
+- Verify NuGet.org shows `RMC.Numerics X.Y.Z` as the latest public package.

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software, please cite our article in the Journal of Open Source Software."
 type: software
 title: "Numerics: A .NET Library for Numerical Computing, Statistical Analysis, and Risk Assessment"
-version: "2.1.4"
-date-released: "2026-07-17"
+version: "2.2.0"
+date-released: "2026-09-18"
 license: 0BSD
 repository-code: "https://github.com/USACE-RMC/Numerics"
 url: "https://github.com/USACE-RMC/Numerics"

CLAUDE.md

@@ -0,0 +1,121 @@
+# Numerics Local Development Rules
+
+## Technical Authority and Algorithm Change Control (NON-NEGOTIABLE)
+
+Haden Smith is the final technical and numerical authority for this repository. AI agents,
+including Codex and Claude, must never change an established algorithm, formula,
+probability-combination rule, numerical method, convergence rule, default tolerance,
+random-seed behavior, clipping or normalization policy, or reference-result contract without
+Haden Smith's explicit prior approval. A failing test authorizes diagnosis and a proposed fix
+only; it does not authorize tuning or replacing the algorithm. When an agent's reasoning
+conflicts with Haden Smith's direction or domain judgment, the agent must stop, present the
+evidence, and request a decision. AI confidence is not technical authority.
+
+## Quality Gate
+
+- No compiler errors.
+- No compiler warnings.
+- Do not suppress warnings to make a build pass; fix the code, XML documentation, or invalid reference.
+- Empty catch blocks are not allowed. Preserve exception context when rethrowing or wrapping.
+
+## XML Documentation
+
+- XML documentation is mandatory for all public API additions and changes.
+- Public classes, structs, interfaces, enums, constructors, properties, methods, events, and fields require accurate XML documentation.
+- Private or internal methods with non-obvious algorithms should also be documented.
+- Include `<summary>`, `<param>`, `<returns>`, `<exception>`, and `<remarks>` whenever they apply.
+- Use `<remarks>` for numerical method notes, assumptions, references, and domain-specific constraints.
+- XML documentation warnings `CS1570`, `CS1571`, `CS1572`, `CS1573`, `CS1574`, `CS1584`, `CS1587`, `CS1589`, and `CS1591` are build errors when `EnforceXmlDocumentation=true`.
+
+## Unit Tests
+
+- Every behavior change must include unit tests or an explicit reason no test is useful.
+- Every new public class requires corresponding coverage in `Test_Numerics`.
+- Statistical and numerical methods must cover known values, edge cases, invalid inputs, and regression cases.
+- Use small inline fixtures in tests unless a shared fixture already exists for the exact scenario.
+
+## Required Validation
+
+Run validation before committing:
+
+```powershell
+dotnet build -c Release
+dotnet test -c Release --no-build
+```
+
+Both commands must complete with zero errors, zero warnings, and zero failed tests. If validation fails, fix the issue before committing.
+
+## Git Workflow
+
+- Commit after successful build and test validation for the completed logical change.
+- Stage only files that belong to the validated change.
+- Do not include unrelated tracked changes or untracked local files.
+- Use concise commit messages that describe the change.
+- Do not push unless explicitly asked.
+
+## PR and Release Workflow
+
+Use this workflow for release-preparation pull requests and public package releases.
+
+### Release PR Planning
+
+- Base release PRs on `bug-fixes-and-enhancements` targeting `main` unless the user gives a different branch plan.
+- Identify the last merged PR from the release branch and list every commit since that merge.
+- Merge `origin/main` into the release branch before editing so current README, JOSS, citation, and metadata updates are preserved.
+- Define the release outcome up front, including the exact `RMC.Numerics` version that NuGet.org must show as the latest public package after publishing.
+
+### Version and Metadata Checklist
+
+Update and cross-check every version-bearing file for each release:
+
+- `Numerics/Numerics.csproj`: set `Version`, `AssemblyVersion`, and `PackageReleaseNotes`.
+- `CITATION.cff`: set `version` and `date-released`.
+- `codemeta.json`: set `version` and `dateModified`.
+- `.github/workflows/Snapshot.yml`: advance the snapshot version to the next patch after the release.
+- Keep `PackageReleaseNotes` concise because NuGet.org displays this field on the package page.
+
+### PR Message Checklist
+
+Use a title like `Prepare vX.Y.Z release`.
+
+Include these sections in the PR body:
+
+- `Summary`: package, citation, CodeMeta, and snapshot metadata updates.
+- `Summary`: user-facing fixes, reliability changes, API changes, and test coverage added since the previous release branch merge.
+- `Validation`: required commands and package inspection results.
+
+Use this validation checklist:
+
+```markdown
+- [ ] `dotnet restore`
+- [ ] `dotnet build Numerics/Numerics.csproj -c Release /p:Version=X.Y.Z`
+- [ ] `dotnet test -c Release` with `VSTEST_CONNECTION_TIMEOUT=600`
+- [ ] `dotnet pack Numerics/Numerics.csproj -c Release /p:Version=X.Y.Z --no-build -o ./packages`
+- [ ] Inspect the `.nupkg` metadata and confirm version `X.Y.Z` and release notes are correct.
+```
+
+### Release Message Checklist
+
+Create a GitHub Release titled `Numerics vX.Y.Z`.
+
+Include these sections in the release body:
+
+- `Highlights`: short release overview.
+- `Reliability and Fixes`: behavior fixes and reliability improvements.
+- Domain-specific sections for API, statistics, time-series, numerical methods, or other notable changes.
+- `Install`: package install command.
+
+Use this install command format:
+
+```bash
+dotnet add package RMC.Numerics --version X.Y.Z
+```
+
+### Publish Workflow
+
+- Merge the validated PR to `main`.
+- Tag the merge commit as `vX.Y.Z`.
+- Push the tag so `.github/workflows/Release.yml` publishes to the internal Nexus feed.
+- Create and publish a non-draft, non-prerelease GitHub Release for `vX.Y.Z`.
+- Confirm `.github/workflows/NuGetPublish.yml` publishes `RMC.Numerics.X.Y.Z.nupkg` to NuGet.org.
+- Verify NuGet.org shows `RMC.Numerics X.Y.Z` as the latest public package.

Numerics/Data/Interpolation/Polynomial.cs

@@ -42,7 +42,7 @@ public class Polynomial : Interpolater
         /// <param name="sortOrder">The sort order of the x-values, either ascending or descending. Default = Ascending. </param>
         public Polynomial(int order, IList<double> xValues, IList<double> yValues, SortOrder sortOrder = SortOrder.Ascending) : base(xValues, yValues, sortOrder)
         {
-            if (order >= Count) throw new ArgumentException(nameof(order), "The order must be less than the length of the x value list.");
+            if (order >= Count) throw new ArgumentException("The order must be less than the length of the x value list.", nameof(order));
             Order = order;
 
         }

Numerics/Data/Interpolation/Support/Interpolater.cs

@@ -33,17 +33,20 @@ public Interpolater(IList<double> xValues, IList<double> yValues, SortOrder sort
             Count = xValues.Count;
 
             // Validate 
-            if (yValues.Count != Count) throw new ArgumentException(nameof(xValues), "The x and y lists must be the same length.");
-            if (Count < 2) throw new ArgumentException(nameof(xValues), "The x list is too small. It must have at least 2 values.");
+            if (yValues.Count != Count) throw new ArgumentException("The x and y lists must be the same length.", nameof(xValues));
+            if (Count < 2) throw new ArgumentException("The x list is too small. It must have at least 2 values.", nameof(xValues));
             for (int i = 1; i < xValues.Count; ++i)
             {
-                if (xValues[i] == xValues[i - 1]) throw new ArgumentException(nameof(xValues), "All x values should be unique.");
-                if (sortOrder == SortOrder.Ascending && xValues[i] < xValues[i - 1]) throw new ArgumentException(nameof(xValues), "The x values are not in ascending order.");
-                if (sortOrder == SortOrder.Descending && xValues[i] > xValues[i - 1]) throw new ArgumentException(nameof(xValues), "The x values are not in descending order.");
+                if (xValues[i] == xValues[i - 1]) throw new ArgumentException("All x values should be unique.", nameof(xValues));
+                if (sortOrder == SortOrder.Ascending && xValues[i] < xValues[i - 1]) throw new ArgumentException("The x values are not in ascending order.", nameof(xValues));
+                if (sortOrder == SortOrder.Descending && xValues[i] > xValues[i - 1]) throw new ArgumentException("The x values are not in descending order.", nameof(xValues));
             }
             this.XValues = xValues;
-            this.YValues = yValues;     
-            deltaStart = Math.Min(1, (int)Math.Pow((double)Count, 0.25));
+            this.YValues = yValues;
+            // Scale the correlated-search window with the table size (Numerical Recipes' N^0.25 hunt
+            // heuristic). Math.Max keeps the window at least 1 and lets it grow with the table; a
+            // window pinned to a constant starves the hunt path. See the remarks on deltaStart.
+            deltaStart = Math.Max(1, (int)Math.Pow((double)Count, 0.25));
             SortOrder = sortOrder;
 
         }
@@ -59,8 +62,17 @@ public Interpolater(IList<double> xValues, IList<double> yValues, SortOrder sort
         public int SearchStart { get; set; } = 0;
 
         /// <summary>
-        /// Keeps track of the difference is start locations. 
+        /// The maximum distance between consecutive search results for which those searches are still
+        /// treated as correlated, selecting the hunt search over bisection.
         /// </summary>
+        /// <remarks>
+        /// The constructor assigns <c>Math.Max(1, (int)Math.Pow(Count, 0.25))</c>, the Numerical
+        /// Recipes N^0.25 hunt heuristic, so the window grows with the table size. The value affects
+        /// only which search path runs — hunt and bisection return the same bracket for the same
+        /// input — so it is a performance characteristic rather than a correctness one.
+        /// <see cref="SearchStart"/> and <see cref="UseSmartSearch"/> are public and settable, so a
+        /// consumer that wants different search behaviour can steer the search directly.
+        /// </remarks>
         protected int deltaStart = 0;
 
         /// <summary>