Docs/api documentation update for release-3.1.0

.github/workflows/cd_manual.yml

@@ -24,7 +24,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install ".[docs]"
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -e ".[docs]"
 
       - name: Build API documentation
         run: |
@@ -35,4 +36,4 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: api-docs
-          publish_dir: docs/build/html
+          path: docs/build/html

.gitignore

@@ -89,6 +89,7 @@ instance/
 
 # Sphinx documentation
 docs/build/
+docs/_build/
 docs/source/wf_psf*.rst
 docs/source/_static/file.png
 docs/source/_static/images/logo_colab.png

changelog.d/20260123_160331_jennifer.pollack_159_psf_output_from_trained_model.md

@@ -0,0 +1,45 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Breaking changes
+
+- A bullet item for the Breaking changes category.
+
+-->
+
+### New features
+
+- Added PSF inference capabilities for generating broadband (polychromatic) PSFs from trained models given star positions and SEDs
+- Introduced `PSFInferenceEngine` class to centralize training, simulation, metrics, and inference workflows
+- Added `run_type` attribute to `DataHandler` supporting training, simulation, metrics, and inference modes
+- Implemented `ZernikeInputsFactory` class for building `ZernikeInputs` instances based on run type
+- Added `psf_model_loader.py` module for centralized model weights loading
+
+
+### Bug fixes
+
+- Fix logger formatting for relative RMSE metrics in `metrics.py` (values were not being displayed)
+
+<!--
+### Performance improvements
+
+- A bullet item for the Performance improvements category.
+
+-->
+
+### Internal changes
+
+- Refactored `TFPhysicalPolychromatic` and related modules to separate training vs. inference behavior
+- Enhanced `ZernikeInputs` data class with intelligent assembly based on run type and available data
+- Implemented hybrid loading pattern with eager loading in constructors and lazy-loading via property decorators
+- Centralized PSF data extraction in `data_handler` module
+- Improved code organization with new `tf_utils.py` module in `psf_models` sub-package
+- Updated configuration handling to support inference workflows via `inference_config.yaml`
+- Fixed incorrect argument name in `DataHandler` that prevented proper TensorFlow data type conversion
+- Removed deprecated `get_obs_positions` method
+- Updated documentation to include inference package

changelog.d/20260210_150506_jennifer.pollack_159_psf_output_from_trained_model.md

@@ -0,0 +1,37 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Breaking changes
+
+- A bullet item for the Breaking changes category.
+
+-->
+<!--
+### New features
+
+- A bullet item for the New features category.
+
+-->
+<!--
+### Bug fixes
+
+- A bullet item for the Bug fixes category.
+
+-->
+<!--
+### Performance improvements
+
+- A bullet item for the Performance improvements category.
+
+-->
+
+### Internal changes
+
+- Remove deprecated/optional import tensorflow-addons statement from tf_layers.py
+
+

changelog.d/20260213_141819_jennifer.pollack_api_documentation_update.md

@@ -0,0 +1,40 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Breaking changes
+
+- A bullet item for the Breaking changes category.
+
+-->
+<!--
+### New features
+
+- A bullet item for the New features category.
+
+-->
+<!--
+### Bug fixes
+
+- A bullet item for the Bug fixes category.
+
+-->
+<!--
+### Performance improvements
+
+- A bullet item for the Performance improvements category.
+
+-->
+
+### Internal changes
+
+- Fixed Sphinx autosummary import errors by removing core dependencies (tensorflow) from autodoc_mock_imports in conf.py.
+- Updated pyproject.toml to include all wf_psf packages under src/ and include config/yaml files.
+- Updated example configuration files with clearer inline comments.
+
+
+

changelog.d/20260213_143539_jennifer.pollack_api_documentation_update.md

@@ -0,0 +1,47 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Breaking changes
+
+- A bullet item for the Breaking changes category.
+
+-->
+<!--
+### New features
+
+- A bullet item for the New features category.
+
+-->
+<!--
+### Bug fixes
+
+- A bullet item for the Bug fixes category.
+
+-->
+<!--
+### Performance improvements
+
+- A bullet item for the Performance improvements category.
+
+-->
+
+### Internal changes
+
+- API documentation for new `inference` package in `api.rst`
+- API documentation for new `instrument` package in `api.rst`
+- Inference Configuration section in `configuration.md` documenting `inference_config.yaml`
+- Restructured Configuration documentation:
+  - Split workflows into "CLI Tasks" and "Additional Components" sections
+  - Added configuration file dependency table showing required vs optional files per task
+  - Clarified configuration filename flexibility (filenames customizable, internal structure fixed)
+  - Standardized section titles (Training Configuration, Metrics Configuration, etc.)
+  - Improved markdown formatting and fixed broken anchor links
+- Updated `dependencies.md` to document `tensorflow-addons` as optional dependency with manual installation instructions
+- `tensorflow-addons` from core dependencies documentation (now documented as optional)
+
+

config/data_config.yaml

@@ -5,43 +5,8 @@ data:
     data_dir: data/coherent_euclid_dataset/
     # Provide name of training dataset
     file: train_Euclid_res_200_TrainStars_id_001.npy
-    # if training data set file does not exist, generate a new one by setting values below
-    stars: null
-    positions: null
-    SEDS: null
-    zernike_coef: null
-    C_poly: null
-    params: #
-      d_max: 2
-      max_order: 45
-      x_lims: [0, 1000.0]
-      y_lims: [0, 1000.0]
-      grid_points: [4, 4]
-      n_bins: 20
-      max_wfe_rms: 0.1
-      oversampling_rate: 3.0
-      output_Q: 3.0
-      output_dim: 32
-      LP_filter_length: 2
-      pupil_diameter: 256
-      euclid_obsc: true
-      n_stars: 200
   test:
     # Specify directory path to training dataset
     data_dir: data/coherent_euclid_dataset/
     # Provide name of test dataset
-    file: test_Euclid_res_id_001.npy
-    # If test data set file not provided produce a new one
-    stars: null
-    noisy_stars: null
-    positions: null
-    SEDS: null
-    zernike_coef: null
-    C_poly: null
-    parameters:
-      d_max: 2
-      max_order: 45
-      x_lims: [0, 1000.0]
-      y_lims: [0, 1000.0]
-      grid_points: [4,4]
-      max_wfe_rms: 0.1
+    file: test_Euclid_res_id_001.npy

config/inference_config.yaml

@@ -0,0 +1,37 @@
+
+inference:
+  # Inference batch size
+  batch_size: 16
+  # Cycle to use for inference. Can be: 1, 2, ...
+  cycle: 2
+
+  # Paths to the configuration files and trained model directory
+  configs:
+    # Path to the directory containing the trained model
+    trained_model_path: /path/to/trained/model/
+
+    # Subdirectory name of the trained model, e.g. psf_model
+    model_subdir: model
+
+    # Relative Path to the training configuration file used to train the model
+    trained_model_config_path: config/training_config.yaml
+
+    # Path to the data config file (this could contain prior information)
+    data_config_path:
+
+  # The following parameters will overwrite the `model_params` in the training config file.
+  model_params:
+    # Num of wavelength bins to reconstruct polychromatic objects.
+    n_bins_lda: 8
+
+    # Downsampling rate to match the oversampled model to the specified telescope's sampling.
+    output_Q: 1
+
+    # Dimension of the pixel PSF postage stamp
+    output_dim: 64
+
+    # Flag to perform centroid error correction
+    correct_centroids: False
+
+    # Flag to perform CCD misalignment error correction
+    add_ccd_misalignments: True

config/metrics_config.yaml

@@ -51,9 +51,6 @@ metrics:
       # Top-hat filter to avoid the aliasing effect in the obscuration mask
       LP_filter_length: 2
 
-      # Boolean to define if we use sample weights based on the noise standard deviation estimation
-      use_sample_weights: True
-
       # Flag to use Zernike prior
       use_prior: False
 
@@ -140,7 +137,7 @@ metrics:
   metrics_hparams:
     # Batch size to use for the evaluation.
     batch_size: 16
-  
+
     # Metrics and model evaluation configuration
     optimizer:
       name: 'adam'           # Only standard Adam used for metrics

config/plotting_config.yaml

@@ -1,13 +1,18 @@
 plotting_params:
-  # Specify path to parent folder containing wf-outputs-xxxxxxxxxxx for all runs, ex: $WORK/wf-outputs/
+  # Path to the parent folder containing WaveDiff output directories
   metrics_output_path: <PATH>
-  # List all of the parent output directories (i.e. wf-outputs-xxxxxxxxxxx) that contain metrics results to be included in the plot
+
+  # List of output directories whose metrics should be plotted
+  # Leave commented/empty if plotting immediately after a metrics run
   metrics_dir:
-    #     - wf-outputs-xxxxxxxxxxx1
-    #     - wf-outputs-xxxxxxxxxxx2
-  # List of name of metric config file to add to plot (would like to change such that code goes and finds them in the metrics_dir)
+  #   - wf-outputs-xxxxxxxxxxxxxxxxxxx1
+  #   - wf-outputs-xxxxxxxxxxxxxxxxxxx2
+
+  # List of metrics config filenames corresponding to each directory
+  # Leave commented/empty if plotting immediately after a metrics run
   metrics_config:
-    #     - metrics_config_1.yaml
-    #     - metrics_config_2.yaml
-  # Show Plots Flag
+  #   - metrics_config_1.yaml
+  #   - metrics_config_2.yaml
+
+  # If True, plots are shown interactively during execution
   plot_show: False

config/training_config.yaml

@@ -52,7 +52,7 @@ training:
     ccd_misalignments_input_path: /path/to/ccd_misalignments_file.txt
 
     # Boolean to use sample weights based on the noise standard deviation estimation
-    use_sample_weights: True 
+    use_sample_weights: True
 
     # Sample weight generalised sigmoid function
     sample_weights_sigmoid:
@@ -96,7 +96,7 @@ training:
     # Telescope's focal length in [m]. Default is `24.5`[m] (Euclid-like).
     tel_focal_length: 24.5
 
-    # Wheter to use Euclid-like obscurations.
+    # Use Euclid-like obscurations.
     euclid_obsc: True
 
     # Length of one dimension of the Low-Pass (LP) filter to apply to the
@@ -154,9 +154,9 @@ training:
     loss: 'mask_mse'
 
     # Optimizer to use during training. Options are: 'adam' or 'rectified_adam'.
-    optimizer: 
-      name: 'rectified_adam'                     
-     
+    optimizer:
+      name: 'rectified_adam'
+
     multi_cycle_params:
 
       # Number of training cycles to perform. Each cycle may use different learning rates or number of epochs.

docs/source/api.rst

@@ -8,6 +8,8 @@ This section contains the API reference for the main packages in WaveDiff.
    :recursive:
 
    wf_psf.data
+   wf_psf.inference
+   wf_psf.instrument
    wf_psf.metrics
    wf_psf.plotting
    wf_psf.psf_models