MHKiT 0.9.0

[ssolson]

MHKiT v0.9.0 Release Notes

This release includes significant new features, enhancements, bug fixes, and updates to improve the functionality, performance, and compatibility of MHKiT.

New Features

Acoustics Module (#349, #359)

• Introduced a new Acoustics module to MHKiT, providing comprehensive tools for processing and analyzing passive acoustic data from hydrophone recordings.
• Designed to facilitate compliance with the IEC-TS 62600-40 standard
• Supports hydrophone models such as SoundTrap and icListen, with functionality to read, calibrate, and process hydrophone data into acoustic metrics.
• Includes functionalities for:
  • Reading hydrophone data.
  • Performing spectral analyses.
    • spectral density (SPSD)
    • spectral density levels (SPSDL)
    • Fractional octave bands (e.g., third-octave, decidecade)
    • Sound Pressure Level (SPL)
  • Applying calibrations.
  • Calculating sound pressure levels.
  • Visualizing results.
  • Audio export
• To support users, an example notebook demonstrates the application of this module with workflows.

Strain Processing Example (#358)

The Strain Processing example introduces a workflow for analyzing strain gauge data, particularly from tidal turbine blade testing. While the functions are not included as a formal MHKiT module due to the variability of test setups, this example notebook provides a detailed and practical framework for processing such data.

• Illustrates the calibration and processing of strain gauge data, showcasing a real-world application in tidal turbine testing.
• Designed to accommodate the variability in strain gauge testing setups, enabling users to adapt the workflow to their specific needs.
• Includes figures and explanations to contextualize the analysis and support data interpretation.
• Reference:
  • Gunawan, B., Haulenbeek, K., Abdellatef, M., Streit, R., Lynn, E., Willis, M., Pendley, D., Gallegos-Patterson, D., Neary, V., Wosnik, M. (2024). Calibration Of Fiber Optic Rosette Sensors For Measuring Bending Moment On Tidal Turbine Blades. International Conference on Ocean Energy, Melbourne, Australia, September 17–19, 2024.

Enhancements and Improvements

Wave Resource Module Performance (#352)

Optimizes the wave.resource module to improve performance and resolve issue #331 by transitioning from xarray.Dataset to xarray.DataArray for core functions. Handling edge cases robustly in pure numpy proved challenging, so the adoption of DataArray strikes a balance between performance and usability.

• Transitioning to DataArray provides a significant speed-up—up to 1000x faster for very large datasets compared to the previous Dataset implementation.
• While pure numpy would offer an additional 5-10x speed-up, DataArray ensures better usability and flexibility for both developers and users.
• Restores the speed of MHKiT’s wave resource functions to their previous state, making the module more efficient for users working with large datasets.
• Simplified input handling for elevation_spectrum and surface_elevation functions.

Surface Elevation Method Selection (#340, #336)

• Enhanced surface_elevation function to handle spectra without a zero frequency index.
• Introduced an auto method for surface elevation calculations that selects the most suitable computation method based on the input spectrum:
  • Automatically switches to sum_of_sines method when Inverse Fast Fourier Transform (IFFT) is not computable.
• Added warnings to inform users of method changes.
• Added an optional frequency_dimension parameter across all necessary wave.resource functions for better flexibility.

DOLfYN Cleaning Functions Update (#354)

• Renamed and enhanced water depth calculation and surface interference removal functions for improved robustness.
• Added an optional frequency_dimension parameter to relevant wave.resource functions, including significant_wave_height and others, to improve compatibility with xarray formats and enhance input flexibility.
• Fixed issues identified in Issue wave.resource.surface_elevation does not gracefully handle input wave spectra where the zero frequency is not defined #308 .

Reynolds Stress ADCP Estimation Notebook Improvements (#326)

• Removed the total_tke function due to limitations of ADCP measurements in accurately estimating smaller turbulent scales and components of TKE.
• Clarified the assumptions required for ADCP measurements:
  • Assumption of Homogeneity: Minimal vertical motion between beam measurements.
  • Spatial Resolution: Turbulent scales smaller than the beam distance cannot be resolved.
• Expanded explanations of TKE shear production, emphasizing the limitations of ADCP-derived Reynolds stress and TKE estimations compared to point measurements from ADV and shear probes.
• Corrected heading rotation logic to prevent rotation beyond 360 degrees.
• Expanded the ADV notebook to cover all relevant functions, emphasizing the accuracy and reliability of ADV measurements for TKE components and Reynolds stress.

Type Handling Improvements (#348)

• Fixed a bug in wave performance Mean Annual Energy Production (MAEP) matrix calculation (Issue Wave performance mean_annual_energy_production_matrix has no test & is incompatible with example #339).
• Improved type handling between Datasets and DataArrays, enhancing function robustness.

NOAA Request Function Update (#332)

• Fixed imprecise error handling in mhkit.tidal.io.noaa.request_noaa_data to ensure meaningful and actionable error messages.
• Enhanced functionality to support additional NOAA data request parameters (e.g., datum) for variables such as water level, water temperature, and salinity.
• Fixed Issue NOAA data request #223.

Bug Fixes

Numpy 2.0 Compatibility (#333)

• Made MHKiT compatible with Numpy 2.0.

Flow Duration Curve Plot Bug Fix (#365)

• Fixed a bug in the flow duration curve plotting function related to matplotlib >= 3.8.
• Corrected the sortby assignment to use the correct value.

Matplotlib Version Compatibility (#345, #365)

• Removed the matplotlib version check previously required for versions < 3.8.0.
• Ensured compatibility with matplotlib >= 3.8.

Python 3.12 Support (#351)

• Added support for Python 3.12.

Documentation Build Warnings Fix (#360)

• Fixed minor spacing and formatting issues in the documentation that were causing warnings during the build process.

Testing and Continuous Integration Updates

GitHub Actions Enhancements (#330, #350, #357)

• Notebook Testing: Added a GitHub Action to test example notebooks as part of the Continuous Deployment (CD) pipeline.
• Implemented a timeout feature to fail notebooks that exceed a specified execution time.
• PyLint Enforcement: Made the utils module PyLint compatible and enforced this compatibility via GitHub Actions.
• Testing Environment Consistency: Updated the GitHub Actions testing environment to use the conda environment.yml file for consistency.
• Pylint Settings Update: Updated Pylint settings and disabled specific warnings as necessary.

Wind Toolkit Tests Optimization (#338)

• Optimized the Wind Toolkit tests, reducing test runtime from over 3.5 hours to approximately 2 hours by modifying the test data and aligning it with cached data used in the notebooks.
• Replaced test data with smaller, representative datasets, improving efficiency without sacrificing robustness.
• Ensured consistent use of cached data between hindcast tests and notebooks to minimize redundant API requests and reduce reliance on live NREL server calls.

MacOS Tests Fix (#362)

• Adjusted test tolerances to fix failing tests on MacOS systems.

Documentation and Examples

Updated Examples and Notebooks (#352, #359, #358)

• Updated Jupyter notebooks for the new Acoustics module.
• Fixed typos and updated examples in notebooks, including the Pacwave and CDIP examples.
• Enhanced strain processing example with additional figures and context.

Other Changes

MHKiT Version Update (#346, #363)

• Bumped MHKiT version to 0.9.0.
• Updated the README to include conda-forge in the conda install command for easier installation.

Folium Map Updates (#350)

• Updated folium map calls in the Pacwave example to align with the latest folium API changes.

Use main as the MHKiT default branch (#367 )

• Many modern projects use main as the default branch, aligning with the GitHub recommendation and broader conventions.
• There is some non-linear history in the previous rebase causing issues between develop & master
• main was created from the current develop branch creating a 1-to-1 liner history between develop and the new main branch

[akeeste]

Thanks @ssolson these release notes look good to me