USACE-RMC · HadenSmith · Sep 17, 2025 · Sep 17, 2025 · Sep 17, 2025 · Sep 17, 2025
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,10 @@
+changelog:
+  categories:
+    - title: New Features
+      labels: [enhancement, feature]
+    - title: Bug Fixes
+      labels: [bug, fix]
+    - title: Documentation
+      labels: [documentation]
+    - title: Other Changes
+      labels: ["*"]
diff --git a/.github/workflows/NuGetPublish.yml b/.github/workflows/NuGetPublish.yml
@@ -0,0 +1,37 @@
+name: Publish to NuGet.org
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+            9.0.x
+            10.0.x
+
+      - name: Extract version from tag
+        id: version
+        shell: bash
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Build
+        run: dotnet build Numerics/Numerics.csproj -c Release -p:Version=${{ steps.version.outputs.VERSION }}
+
+      - name: Test (all frameworks)
+        run: dotnet test -c Release --no-build
+
+      - name: Pack
+        run: dotnet pack Numerics/Numerics.csproj -c Release --no-build -p:Version=${{ steps.version.outputs.VERSION }}
+
+      - name: Push to NuGet.org
+        run: dotnet nuget push "Numerics/bin/Release/RMC.Numerics.${{ steps.version.outputs.VERSION }}.nupkg" --api-key ${{ secrets.NUGET_ORG_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
diff --git a/.gitignore b/.gitignore
@@ -370,3 +370,4 @@ MigrationBackup/
 
 #Numerics Specific
 /TestResults
+/.claude/settings.local.json
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,45 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "Numerics"
+version: "2.0.0"
+date-released: "2026-03-08"
+license: BSD-3-Clause
+repository-code: "https://github.com/USACE-RMC/Numerics"
+url: "https://github.com/USACE-RMC/Numerics"
+abstract: >-
+  Numerics is a free and open-source .NET library providing numerical methods,
+  probability distributions, statistical analysis, and Bayesian inference tools
+  for quantitative risk assessment in water resources engineering.
+keywords:
+  - statistics
+  - probability distributions
+  - MCMC
+  - hydrology
+  - flood frequency analysis
+  - copulas
+  - L-moments
+  - optimization
+  - .NET
+  - C#
+authors:
+  - family-names: "Smith"
+    given-names: "C. Haden"
+    email: "cole.h.smith@usace.army.mil"
+    affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
+    orcid: "https://orcid.org/0000-0002-4651-9890"
+  - family-names: "Fields"
+    given-names: "Woodrow L."
+    affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
+  - family-names: "Gonzalez"
+    given-names: "Julian"
+    affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
+  - family-names: "Niblett"
+    given-names: "Sadie"
+    affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
+  - family-names: "Beam"
+    given-names: "Brennan"
+    affiliation: "U.S. Army Corps of Engineers, Hydrologic Engineering Center"
+  - family-names: "Skahill"
+    given-names: "Brian"
+    affiliation: "Fariborz Maseeh Department of Mathematics and Statistics, Portland State University"
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,13 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Please read the full text at the link above. In summary, we are committed to providing a welcoming and inclusive environment for everyone. Be respectful, constructive, and professional in all interactions.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please contact the project maintainers at cole.h.smith@usace.army.mil.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,63 @@
+# Contributing to Numerics
+
+Thank you for your interest in contributing to Numerics! We welcome bug reports, feature requests, validation results, and other feedback from the community.
+
+## Review Capacity
+
+Numerics is maintained by a small team within the U.S. Army Corps of Engineers Risk Management Center (USACE-RMC). **Our capacity to review external pull requests is very limited.** We prioritize issues and bug reports, which are always welcome and will be reviewed as resources permit.
+
+If you plan to submit a pull request, please open an issue first to discuss your proposed change. This helps avoid duplicated effort and ensures your contribution aligns with the project's direction.
+
+## How to Contribute
+
+### Report a Bug
+
+If you find a bug, please [open an issue](../../issues/new) and include:
+
+- Steps to reproduce the problem
+- Input data and configuration (if applicable)
+- Expected behavior vs. actual behavior
+- Software version and operating system
+- Any relevant error messages or screenshots
+
+### Request a Feature
+
+Feature requests are welcome. Please [open an issue](../../issues/new) describing:
+
+- The use case or problem you are trying to solve
+- How you envision the feature working
+- Any references to statistical methods or published literature
+
+### Report Validation Results
+
+Given the life-safety applications of this software, independent validation is especially valuable. If you have compared Numerics results against other software (e.g., R packages, published tables, or analytical solutions), we would appreciate hearing about it through an issue.
+
+### Submit a Pull Request
+
+Pull requests may take several weeks or longer to review. Before submitting code:
+
+1. **Open an issue first** to discuss the proposed change
+2. **Follow the coding standards**, including XML documentation on all public types and members
+3. **Include unit tests** that validate against known results (R, SciPy, Mathematica, or published tables)
+4. **Use MSTest** (`[TestClass]`, `[TestMethod]`) as the testing framework
+5. **Ensure a clean build** with zero errors and zero warnings
+
+## Developer Certificate of Origin
+
+By submitting a pull request, you certify under the [Developer Certificate of Origin (DCO) Version 1.1](https://developercertificate.org/) that you have the right to submit the work under the license associated with this project and that you agree to the DCO.
+
+All contributions will be released under the same license as the project (see [LICENSE](LICENSE)).
+
+## Federal Government Contributors
+
+U.S. Federal law prevents the government from accepting gratuitous services unless certain conditions are met. By submitting a pull request, you acknowledge that your services are offered without expectation of payment and that you expressly waive any future pay claims against the U.S. Federal government related to your contribution.
+
+If you are a U.S. Federal government employee and use a `*.mil` or `*.gov` email address, your contribution is understood to have been created in whole or in part as part of your official duties and is not subject to domestic copyright protection under 17 USC 105.
+
+## Security
+
+If you discover a security vulnerability, please do **not** open a public issue. Instead, contact the RMC team directly through official USACE-RMC channels.
+
+## License
+
+See [LICENSE](LICENSE) for details. This software is provided by USACE-RMC under a BSD-style license with a no-endorsement clause.
diff --git a/JOSS_TODO.md b/JOSS_TODO.md
@@ -0,0 +1,219 @@
+# JOSS Submission Checklist
+
+Pre-submission checklist for the Journal of Open Source Software (JOSS).
+JOSS review criteria: https://joss.readthedocs.io/en/latest/review_criteria.html
+JOSS paper format: https://joss.readthedocs.io/en/latest/paper.html (750-1,750 words)
+
+---
+
+## Section A: JOSS Requirements Compliance
+
+### Software Requirements
+
+| # | Requirement | Status | Evidence |
+|---|-------------|--------|----------|
+| 1 | Open source license (OSI-approved) | MET | BSD-3-Clause in `LICENSE`; declared in `CITATION.cff` |
+| 2 | Version control (public repository) | MET | https://github.com/USACE-RMC/Numerics |
+| 3 | README with project description | MET | `README.md` with description, install, docs, badges |
+| 4 | Installation instructions | MET | NuGet install in `README.md` and `docs/getting-started.md` |
+| 5 | Usage examples | MET | `docs/getting-started.md`, `docs/index.md` Quick Start, paper Example section |
+| 6 | API documentation | MET | 25+ Markdown files in `docs/`; XML documentation generated from source |
+| 7 | Community guidelines (CONTRIBUTING) | MET | `CONTRIBUTING.md` with bug reports, PRs, DCO, security policy |
+| 8 | Code of Conduct | MET | `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1) |
+| 9 | Automated tests | MET | 1,006 MSTest methods across 150 test classes in `Test_Numerics/` |
+| 10 | Continuous integration | MET | 3 GitHub Actions workflows (`Integration.yml`, `Snapshot.yml`, `Release.yml`) |
+| 11 | Substantial scholarly effort | MET | 60,000+ LOC library, 34,000+ LOC tests, 248 source files |
+| 12 | Sustained development history | MET | 2.5 years (Sep 2023 - Mar 2026), 270+ commits, 7+ contributors |
+| 13 | Statement of need | MET | Paper includes Statement of Need section |
+| 14 | State of the field / related work | MET | Paper includes State of the Field section |
+| 15 | Zero or documented dependencies | MET | Zero runtime dependencies for .NET 8+; polyfills only for .NET Framework 4.8.1 |
+| 16 | Functionality matches claims | MET | All claims verified: 43 distributions, 8 MCMC samplers (RWMH, ARWMH, DEMCz, DEMCzs, HMC, NUTS, Gibbs, SNIS), 5+ optimizers, copulas, ML, bootstrap |
+| 17 | Software installable | REMAINING | Publish `RMC.Numerics` to nuget.org (see Step 4 below) |
+
+### Paper Requirements
+
+| # | Requirement | Status | Evidence |
+|---|-------------|--------|----------|
+| 18 | Paper in `paper/paper.md` | MET | `paper/paper.md` with YAML frontmatter |
+| 19 | Bibliography in `paper/paper.bib` | MET | `paper/paper.bib` with 29 references |
+| 20 | Summary section | MET | Lines 39-41 |
+| 21 | Statement of Need section | MET | Lines 43-54 |
+| 22 | State of the Field section | MET | Lines 56-62 |
+| 23 | Research impact / ongoing projects | MET | Lines 64-75 (6 production applications) |
+| 24 | Acknowledgements | MET | Lines 119-121 |
+| 25 | AI Usage Disclosure | MET | Lines 115-117 |
+| 26 | Word count 750-1,750 | MET | ~1,215 words (within range) |
+| 27 | Submitting author ORCID | MET | `0000-0002-4651-9890` for C. Haden Smith |
+| 28 | Author affiliations | MET | 3 affiliations listed |
+| 29 | All references have DOIs where available | MET | 21 DOIs + 7 URLs for web-only resources |
+| 30 | Code example in paper | MET | Lines 85-113 (bootstrap uncertainty analysis) |
+
+### Repository Metadata
+
+| # | Requirement | Status | Evidence |
+|---|-------------|--------|----------|
+| 31 | CITATION.cff | MET | `CITATION.cff` (CFF v1.2.0, BSD-3-Clause) |
+| 32 | codemeta.json | MET | `codemeta.json` created |
+| 33 | Version tag matching submission | REMAINING | Need to create `v2.0.0` tag after merge to `main` |
+| 34 | Archived release with DOI | REMAINING | Need Zenodo archive |
+
+---
+
+## Section B: BES Paper Review Comments (Addressed)
+
+| # | Comment | Status | Action |
+|---|---------|--------|--------|
+| 1 | Co-author ORCIDs (Fields, Gonzalez, Niblett, Beam) | DONE | All ORCIDs added to paper.md |
+| 2 | "Differential Evolution MCMC" → "Adaptive Differential Evolution MCMC" (line 53) | DONE | Clarifies DE-MCz vs DE-MC |
+| 3 | "needed for reliable calibration" → "commonly applied for Bayesian inference" (line 61) | DONE | More accurate characterization |
+| 4 | Gonzalez: Software Design choppy language | DONE | Rewrote section with accurate base class descriptions, removed First/Second/Third structure |
+| 5 | Gonzalez: Redundant "zero dependencies" in Summary | DONE | Removed from Summary, kept in Software Design where it is explained |
+| 6 | Gonzalez: Why is CI important? | DONE | Added "preventing regressions in numerical accuracy" to CI sentence |
+| 7 | Gonzalez: References not in markdown | N/A | JOSS uses Pandoc + paper.bib to render citations at build time |
+| 8 | MCMC sampler count (was "six", should be "eight") | DONE | Updated Summary and Statement of Need to include DEMCzs and SNIS |
+
+---
+
+## Section C: Pre-Release Verification
+
+- [ ] Run full test suite across all target frameworks:
+  ```
+  dotnet test --framework net8.0
+  dotnet test --framework net9.0
+  dotnet test --framework net10.0
+  dotnet test --framework net481
+  ```
+- [ ] Confirm all 1,006+ tests pass on every target
+- [ ] Build the NuGet package locally:
+  ```
+  dotnet pack Numerics/Numerics.csproj -c Release
+  ```
+- [ ] Verify the .nupkg contains assemblies for all 4 TFMs
+
+---
+
+## Section D: Release Roadmap (Step-by-Step)
+
+### Step 1: Create Pull Request to `main`
+- [ ] Push latest `bugfixes-and-enhancements` to origin
+- [ ] Create PR:
+  ```
+  gh pr create --base main --head bugfixes-and-enhancements \
+    --title "v2.0.0: Major update" --body-file RELEASE_NOTES.md
+  ```
+- [ ] Wait for CI (Integration.yml) to pass
+- [ ] Review and merge PR
+
+### Step 2: Tag and GitHub Release
+- [ ] After merge:
+  ```
+  git checkout main && git pull
+  git tag v2.0.0
+  git push origin v2.0.0
+  ```
+- [ ] Create GitHub Release:
+  ```
+  gh release create v2.0.0 --title "v2.0.0 — Major Update" --notes-file RELEASE_NOTES.md
+  ```
+- [ ] `Release.yml` auto-triggers → pushes to internal USACE Nexus
+- [ ] `NuGetPublish.yml` auto-triggers → pushes to nuget.org
+
+### Step 3: One-Time NuGet.org Setup (before first release)
+- [ ] Create/verify nuget.org account at https://www.nuget.org/
+- [ ] Generate API key at https://www.nuget.org/account/apikeys:
+  - Name: `GitHub Actions - Numerics`
+  - Expiration: 365 days
+  - Glob pattern: `RMC.Numerics`
+  - Scopes: "Push new packages and package versions"
+- [ ] Add secret to GitHub repo at https://github.com/USACE-RMC/Numerics/settings/secrets/actions:
+  - Name: `NUGET_ORG_API_KEY`
+  - Value: the API key from above
+
+### Step 4: Verify NuGet Package
+- [ ] Check https://www.nuget.org/packages/RMC.Numerics/ (may take 10-15 min to index)
+- [ ] Test installation:
+  ```
+  dotnet new console -o TestInstall && cd TestInstall
+  dotnet add package RMC.Numerics --version 2.0.0
+  dotnet build
+  ```
+
+### Step 5: Zenodo Archival
+- [ ] Go to https://zenodo.org and log in with GitHub
+- [ ] Enable the `USACE-RMC/Numerics` repository in Zenodo's GitHub integration
+- [ ] Zenodo will automatically archive the GitHub Release and mint a DOI
+- [ ] Copy the Zenodo DOI badge and add it to `README.md`
+- [ ] Update `CITATION.cff` with the Zenodo DOI if desired
+
+### Step 6: Submit to JOSS
+- [ ] Go to https://joss.theoj.org/papers/new
+- [ ] Enter the repository URL: `https://github.com/USACE-RMC/Numerics`
+- [ ] Enter the Zenodo archive DOI
+- [ ] Confirm software version matches the tagged release
+- [ ] Submit the paper
+
+### Step 7: Post-Submission
+- [ ] Add the JOSS status badge to `README.md` once the review issue is created:
+  ```markdown
+  [![status](https://joss.theoj.org/papers/<DOI>/status.svg)](https://joss.theoj.org/papers/<DOI>)
+  ```
+- [ ] Monitor the review issue for editor/reviewer feedback
+- [ ] Address any review comments promptly (JOSS reviews typically take 4-8 weeks)
+
+---
+
+## Section E: v2.0.0 Release Notes
+
+### v2.0.0 — Major Update
+
+This is a major update to Numerics with 274 files changed, 24,476 insertions, and 4,400 deletions since v1.0.0. Highlights include new distributions, improved MCMC inference, enhanced numerical methods, and comprehensive documentation.
+
+#### New Distributions
+- Dirichlet distribution (multivariate)
+- Multinomial distribution (multivariate)
+- Multivariate Student-t distribution
+- Student-t copula
+
+#### Bayesian Inference & MCMC
+- Improved Gelman-Rubin convergence diagnostics
+- Refactored Noncentral-T to use Brent.Solve
+- Enhanced MCMC sampler reliability and convergence
+
+#### Numerical Methods
+- Linear algebra enhancements
+- Root-finding improvements
+- ODE solver improvements
+- Improved adaptive integration
+
+#### Data & Statistics
+- Time series download improvements
+- Hypothesis test enhancements
+- Enhanced parameter estimation methods
+- Autocorrelation and convergence diagnostics improvements
+
+#### Optimization
+- Comprehensive correctness improvements across all optimizers
+
+#### Machine Learning
+- Documentation consolidation
+- Code quality improvements
+
+#### Infrastructure & Documentation
+- Added .NET 10.0 target framework (now targets net8.0, net9.0, net10.0, net481)
+- Zero runtime dependencies maintained
+- 1,006+ unit tests validated against published references
+- JOSS paper and metadata (CITATION.cff, codemeta.json)
+- CONTRIBUTING.md and CODE_OF_CONDUCT.md
+- 25+ documentation files covering all library capabilities
+- NuGet publishing workflow for nuget.org
+
+---
+
+## Notes
+
+- **Word limit**: JOSS papers should be 750-1,750 words (https://joss.readthedocs.io/en/latest/paper.html). Current paper is ~1,215 words.
+- **"Jery R. Stedinger"**: This spelling in `paper.bib` is correct (confirmed on USGS publications). Be prepared to explain if a reviewer questions it.
+- **England 2019 vs 2018**: Bulletin 17C was originally published March 2018; the `2019` date refers to the v1.1 revision. Both are acceptable in the literature.
+- **ter Braak citation**: The 2008 paper describes DE-MCzs (with snooker updater). The library has both `DEMCz` and `DEMCzs` classes. The citation is appropriate since the 2008 paper supersedes the 2006 original.
+- **NuGet API key expiration**: The nuget.org API key expires after 365 days max. Set a calendar reminder to regenerate it.
+- **Versioning**: Version is derived from git tags (e.g., `v2.1.0` → package version `2.1.0`). The `.csproj` version is a fallback for local builds only.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -370,3 +370,4 @@ MigrationBackup/

		#Numerics Specific
		/TestResults
		/.claude/settings.local.json