Merge pull request #197 from CosmoStat/release/v3.0.0

Release/v3.0.0

Author: ChaitanyaChawak

.github/pull_request_template.md

@@ -33,6 +33,7 @@
 - [ ] Hotfix  
 - [ ] Documentation / process change  
 - [ ] Internal / refactor  
+- [ ] Release
 
 > Optionally, note if this PR is part of a larger milestone or set of related PRs.
 
@@ -49,7 +50,7 @@
 
 > Reviewers should confirm the following before approving and merging:
 
-- [ ] The PR targets the `develop` branch
+- [ ] The PR targets the correct base branch (`develop`, or `main` for release PRs)
 - [ ] The PR is assigned to the developer
 - [ ] Appropriate labels are applied
 - [ ] The PR is included in relevant projects and/or milestones

CHANGELOG.md

@@ -1,5 +1,53 @@
-# Changelog
+# WaveDiff / WF-PSF Changelog
 
 All notable changes to WaveDiff are documented in this file.
 
 ## [Unreleased]
+
+- Changes in progress for the next release.
+
+## [3.0.0] – 2026-01-20
+
+Major update with PSF model refactoring, masked training, and CI/doc improvements.
+
+## Breaking changes
+
+- Removed the `--repodir` argument in CLI; scripts using it will now fail.
+
+## New features
+
+- Added physical layer model with improved modularity (`TFPhysicalPolychromatic` refactor) and configurable parameters.
+- Introduced rotation of obscuration mask with configurable parameter.
+- Updated `CentroidEstimator` to support mask-based estimation.
+- Added options for user-configurable flags:
+    - `use_prior` for Zernike prior
+    - `correct_centroids` and `sigma_centroid_window` for centroid error correction
+    - `add_ccd_misalignments` and `ccd_misalignments_input_path` for CCD misalignment correction
+- Added option to randomize the data-driven part seed for reproducibility.
+- Added phase retrieval projection algorithm considering obscurations.
+- Masked training and evaluation: added `masked_mse` loss and `MaskedMeanSquaredErrorMetric` classes.
+- Added configurable parameter for computing shape metrics for test datasets as optional.
+- Added new sigmoid parameters to apply to the sample weights.
+- Added masked datasets and corresponding generation notebooks.
+
+## Bug fixes
+
+- Fixed missing e₂ and R₂ shape metric plots
+- Fixed broken contribution link in documentation
+- Corrected bug in `MonochromaticMetricsPlotHandler` class regarding `eval_mono_metric` configuration.
+
+## Performance improvements
+
+- Improved numerical stability and reproducibility in training routines
+
+## Internal changes
+
+- Replaced Black with Ruff for linting and formatting.
+- Updated TensorFlow to 2.11 (compatibility fixes for NumPy ≥ 1.26.4 and Astropy).
+- Reorganized modules for clarity (e.g., `SimPSFToolkit.py` renamed).
+- Improved PEP8 compliance across the codebase.
+- Introduced Scriv-based changelog infrastructure.
+- Configured `sphinx.ext.autosummary` to auto-generate stubs in `_autosummary/`.
+- Added new documentation and templates: `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `DEV_WORKFLOW.md`.
+
+

DEV_WORKFLOW.md

@@ -11,29 +11,41 @@
 Make a milestone related to a release on possibly a minor release schedule (e.g. monthly schedule). Differentiate between the different types of releases (minor, major, patch).
 
 ## 2.  **Git Workflow Branching Model (Made with** [**mermaid**](https://mermaid.js.org)**)**
-![](assets/branching_model.png)
+![](assets/Git-Branching-Model.png)
 
    *   **main**: Stores official release history with tagged version numbers (see top row in the diagram above).
 
    *   **develop**: This branch is the integration branch for features.
 
-   *   **feature**: Branch off of develop for new feature development.  Features get merged to develop (never to main).
+   *   **feature**: Branch off of `develop` for new feature development.  Features get merged to `develop` (never to main).
 
    *   **bug**: For fixing specific bugs introduced during the production phase.
 
-   *   **hotfix**: Quickly corrects bugs in the latest release version; branched off main.
+   *   **hotfix**: Quickly corrects bugs in the latest release version; branched off `main`.
+
+   *   **release/vX.Y.Z**: Temporary branch created from `develop`; used to:
+         * Collect Scriv changelog fragments here.
+         * Apply final QA or documentation updates.
+         * Merge into `main` when ready and tag the release.
 
 
 ## 3.  **New Branch naming conventions**
 
 
 Branches created for the purpose of a Pull Request should be directly related to an open issue within the project’s issue tracker.  This ensures that all code changes are tied to specific tasks or features, facilitating better organisation and tracking of contributions. Below are the branch naming conventions:
 
-   *   **Feature**: feature/<issue number>/short-description
+   *   **Feature**: `feature/<issue number>/short-description`
 
-   *   **Bug**: bug/<issue number>/short-description
+   *   **Bug**: `bug/<issue number>/short-description`
 
-   *   **Hotfix**: hotfix/<issue number>/short-description
+   *   **Hotfix**: `hotfix/<issue number>/short-description`
+
+   *   **Release**: `release/v<MAJOR>.<MINOR>.<PATCH>` 
+
+**Notes:**
+- Replace `<ISSUE_NUMBER>` with the tracker issue number.
+- Keep short-description concise.
+- Release branches are short-lived and should not include ongoing development.
 
 
 Replace with the corresponding issue number and provide a brief description of the changes in \`short\_description\`.
@@ -43,7 +55,7 @@ Replace with the corresponding issue number and provide a brief description of t
 
 *   Pull the latest changes from the remote repository
 
-*   Checkout develop
+*   Checkout `develop`
 
 *   Create a new feature branch
 
@@ -57,7 +69,7 @@ Replace with the corresponding issue number and provide a brief description of t
 
 *   Run training and metrics validation tests locally to confirm no breaking behaviour or errors were introduced.  Include test reports as per the PR template.
 
-*   Open a Pull Request to start the review process, ensuring to map the branch correctly to the target branch (i.e. feature\_branch -> develop or hotfix\_branch -> main).
+*   Open a Pull Request to start the review process, ensuring to map the branch correctly to the target branch (i.e. `feature` -> `develop` or `hotfix` -> `main`).
 
 *   In the description of the Pull Request, explicitly state whether the PR resolves or closes an open issue by using one of the following formats:
 
@@ -77,7 +89,6 @@ Example: "Solves #12345" or "Closes #8679".
 
 ## 6.  **Merging Pull Requests** 
 
-
 *   Approval and Merging: Once the reviewer approves the PR and all feedback is addressed, merge the feature branch into develop.  Note, it is the reviewer who is responsible for merging the PR when satisfied with the changes.
 
 ## 7.  **Changelog and release notes**
@@ -100,6 +111,9 @@ This approach:
    ```bash
    scriv create
    ```
+**Notes**: 
+- Do not collect fragments in your PR; leave [Unreleased] in CHANGELOG.md.
+- [Unreleased] is always at the top; contributors never write directly into it.
 
 Fragment creation and writing guidelines are documented in [CONTRIBUTING.md](./CONTRIBUTING.md).
 
@@ -114,7 +128,7 @@ This separation keeps release notes accurate and enables clean backports
 
 *   Each milestone targets a release (feature, patch, etc).
 
-*   Open a PR from develop to main upon completing a milestone
+*   Open a PR from `develop` to `release/vX.Y.Z` upon completing a milestone
 
 * Collect changelog fragments and generate release notes using:
 

assets/Git-Branching-Model.png

@@ -1,19 +1,24 @@
+# WaveDiff v3.0.0 release environment
+# Tested on Jean-Zay HPC. NumPy 1.26.x is installed via pip.
+# This file reflects the dependency constraints defined in pyproject.toml
+# and is not a fully pinned development environment.
 name: wavediff-env
 channels:
   - conda-forge
 dependencies:
-  - keras=2.9.0=pyhd8ed1ab_0
-  - scipy=1.11.4=py310h2b794db_0
-  - tensorflow=2.9.1=cpu_py310h6ecea76_0
-  - pip=23.3.1
+  - python>=3.9,<3.12
+  - scipy
+  - tensorflow=2.11.0
+  - pip
   - pip:
-      - astropy>=6.0.0
-      - galsim>=2.5.1
-      - matplotlib>=3.8.2
-      - opencv-python>=4.8.1.78
-      - pandas>=2.1.4
-      - pillow>=10.1.0
-      - seaborn>=0.13.0
-      - tensorflow-addons>=0.23.0
-      - tensorflow-estimator>=2.15.0
-      - zernike>=0.0.32
+      - numpy>=1.26,<2.0
+      - tensorflow-addons
+      - tensorflow-estimator
+      - zernike
+      - opencv-python
+      - pillow
+      - galsim
+      - astropy
+      - matplotlib
+      - seaborn
+