diff --git a/README.md b/README.md index e41ec09a..fa36e90c 100644 --- a/README.md +++ b/README.md @@ -40,19 +40,23 @@ To update the MHKiT documentation you will need Python 3.6+, Git, Sphinx, and a ```pip install -U Sphinx``` - - Sphinx --> Version: 3.1.1 + - Sphinx --> Version: 8.1.3 - - Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, and NB Sphinx) + - Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, NB Sphinx, and google analytics) and additional dependencies - ```pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx``` + ```pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx sphinxcontrib-googleanalytics ipython``` - - nbsphinx --> Version: 0.7.1 + - nbsphinx --> Version: 0.9.5 - - sphinxcontrib-matlabdomain --> Version: 0.11.2 + - sphinxcontrib-matlabdomain --> Version: 0.22.1 - - sphinxcontrib-bibtex --> Version: 1.0.0 + - sphinxcontrib-bibtex --> Version: 2.6.3 - - sphinx-rtd-theme --> Version: 0.5.0 + - sphinx-rtd-theme --> Version: 3.0.2 + + - sphinxcontrib-googleanalytics --> Version: 0.4 + + ```conda install pandoc``` You are now ready to begin modifying and building the MHKiT documentation. @@ -130,3 +134,39 @@ Using your machine's file explorer navigate to MHKiT/docs and use an Internet br - MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo) - MHKiT (Marine and Hydrokinetic Toolkit) +## Modules Template +All modules in MHKiT should be briefly described in the "Module Overview" Section. +Below is a template that can be used for a new MHKiT module (fix title +characters when adding a section): + +NAME Module +
==================== + +Brief description of what the module dose. + +API Documentation +
-------------------- + +- `Python NAME API Documentation `_ +- `MATLAB NAME API Documentation `_ + +Examples +
-------------- + +- Bulleted list of linked examples +- pertaining to this module. +- Tag modules in docs/source/examples.rst as appropriate. + +Submodules +
-------------- + +The NAME module contains the following submodules: + +* ``SUBMODULE_NAME``: one sentence description of the submodule. Calculations are based on `IEC TS XXXXX-XXX:20XX EDX ` +* ``SUBMODULE_NAME``: etc... + +IEC/TS XXXXX-XXX +
--------------------------- + +Recommends proper use of the module per relevant IEC standards. + diff --git a/docs/source/acoustics.rst b/docs/source/acoustics.rst index 6d7715ce..4425b168 100644 --- a/docs/source/acoustics.rst +++ b/docs/source/acoustics.rst @@ -2,7 +2,7 @@ Passive Acoustics Module ======================== -The acoustics module contains a set of functions to injest hydrophone *.wav* files. +The acoustics module contains a set of functions to ingest hydrophone *.wav* files. Only available in MHKiT-Python in v0.9 or later. API Documentation @@ -15,10 +15,11 @@ Examples - `Passive Acoustics Example `_ +Submodules +-------------- The acoustics module contains the following submodules: * ``io``: Contains functions to read and output *.wav* files -* ``analysis``: Contains functions to process, clean and analyze passive acoustics data +* ``analysis``: Contains functions to process, clean and analyze passive acoustics data. + Calculations are based on `IEC TS 62600-40:2019 ED1 `_. * ``graphics``: Contains functions to plot spectral data - -See :ref:`MHKiT-Python ` for more details on the acoustics module. diff --git a/docs/source/conf.py b/docs/source/conf.py index 57c2c5c4..072950f8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,7 +28,8 @@ 'sphinx_rtd_theme', 'nbsphinx', 'sphinxcontrib.bibtex', - 'sphinxcontrib.matlab', + 'sphinxcontrib.matlab', + 'sphinxcontrib.googleanalytics', ] autosectionlabel_prefix_document = True @@ -36,7 +37,7 @@ # # -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another dire ctory, +# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -105,6 +106,11 @@ # can be set to alphabetical, groupwise or bysource autodoc_member_order = 'bysource' +# A list of warning codes to suppress arbitrary warning messages. +suppress_warnings = [ + 'docutils', # duplicate object description, unexpected indentation +] + # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None @@ -148,7 +154,8 @@ # further. For a list of options available for each theme, see the # documentation. # Added Google Analytics to theme based on https://github.com/readthedocs/sphinx_rtd_theme/pull/411 -html_theme_options = {'analytics_id': 'UA-164358105-1'} +googleanalytics_id = 'UA-164358105-1' +googleanalytics_enabled = True # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] diff --git a/docs/source/contact.rst b/docs/source/contact.rst index c524b2ae..2d96447d 100644 --- a/docs/source/contact.rst +++ b/docs/source/contact.rst @@ -26,7 +26,7 @@ To propose changes to the MHKiT software, complete your development on a distinc Submit a `pull request `_ of the modified repository into the appropriate repository's ``develop`` branch. If an update contains a bug fix, create the pull request into the ``develop`` branch. Once reviewed by the MHKiT development team, pull requests will be merged into MHKiT. -Features will later be merged into the master branch and included in future releases of MHKiT. +Features will later be merged into the main branch and included in future releases of MHKiT. Software developers, within the MHKiT development team and external collaborators, are expected to follow standard software quality practices. In any PR, please include documentation and tests for new code. Create an additional PR into the MHKiT documentation repository as needed. diff --git a/docs/source/dolfyn.rst b/docs/source/dolfyn.rst index ef3f9c23..2f913c79 100644 --- a/docs/source/dolfyn.rst +++ b/docs/source/dolfyn.rst @@ -16,6 +16,8 @@ Examples - `ADV Example `_ - `Python Tanana River Resource Characterization `_ +Submodules +-------------- The dolfyn module contains the following submodules: * ``adp``: Contains functions to process, clean and analyze ADCP data @@ -24,5 +26,3 @@ The dolfyn module contains the following submodules: * ``rotate``: Contains tools to rotate a dataset to a new coordinate system. * ``time``: Contains functions to modify the format of the stored time between a variety of time formats. * ``tools``: Contains miscellaneous functions used in mhkit that may prove useful to users - -See :ref:`MHKiT-Python ` for more details on the Dolfyn module. diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 2da8eb9c..770cb74b 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -3,6 +3,9 @@ Examples ======== +Overview +--------- + This page details all the available examples of MHKiT functions and features. Python examples are available as Jupyter notebooks and MATLAB examples as live scripts. Not all MATLAB examples are available yet but are coming soon. @@ -32,7 +35,6 @@ Search for the following tags to identify relevant examples: * - qc - Examples preparing data, doing quality control, etc - .. list-table:: :header-rows: 1 @@ -42,127 +44,143 @@ Search for the following tags to identify relevant examples: - Description - Tags * - Quality Control - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Data quality control workflow example - qc * - River Example - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize river current energy from USGS data - current, resource, iec * - Tidal Example - - `Notebook `_ + - `Notebook `__ - Coming soon - Visualize velocity duration curve from NOAA tidal data - current, resource, iec * - Tidal Power Performance Example - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Tidal power performance testing workflow - current, iec * - ADCP Example - - `Notebook `_ + - `Notebook `__ - Coming soon - Acoustic Doppler Current Profiler (ADCP) analysis workflow - current, resource * - ADV Example - - `Notebook `_ + - `Notebook `__ - Coming soon - Acoustic Doppler Velocimetry (ADV) analysis workflow - current, resource * - Tanana River Resource Characterization - - `Notebook `_ + - `Notebook `__ - Coming soon - Site-specific river resource characterization - current, resource * - Delft3D - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Analyze and visualize output from Delft3D - current, resource * - WEC Power Performance - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize WEC Power vs. Wave Resource - wave, resource, iec * - Directional Waves Analysis - - `Notebook `_ + - `Notebook `__ - Coming soon - Visualize directional wave energy spectra from NDBC data - wave, resource * - Environmental Contours - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize estimates of extreme sea states - wave, resource * - PacWave Resource Characterization - - `Notebook `_ + - `Notebook `__ - Coming soon - Site-specific resource characterization using NDBC data - wave, resource, iec * - CDIP - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Download and visualize CDIP resource data - wave, resource * - WEC-Sim - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize output from WEC-Sim - wave * - SWAN - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize output from Simulating Waves Nearshore (SWAN) - wave * - WPTO Hindcast - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Download and visualize WPTO Hindcast data - wave, resource * - Metocean Analysis - - `Notebook `_ + - `Notebook `__ - Coming soon - Download and visualize NDBC metocean data - wave, resource * - Upcrossing Analysis - - `Notebook `_ + - `Notebook `__ - Coming soon - Analyze the surface elevation of a wave - wave * - Loads Analysis - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Compute structural loads quantities of interest - loads * - Extreme Response MLER - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Extreme conditions model - Most Likely Extreme Response (MLER) - loads, wave * - Extreme Response Contour - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Extreme conditions model - contour approach - loads, wave * - Extreme Response Full Sea State - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Extreme conditions model - full sea state approach - loads, wave * - Short-Term Extremes - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Visualize probability distribution of short-term time series data - loads, wave * - Electrical Power Analysis - - `Notebook `_ - - `Live Script `_ + - `Notebook `__ + - `Live Script `__ - Compute 3-phase power quantities of interest - power, iec * - Mooring - - `Notebook `_ + - `Notebook `__ - Coming soon - Visualize and analyze output from MoorDyn - mooring, wave + * - Acoustics + - `Notebook `__ + - Coming soon + - Ingest, analyze and visualize passive acoustic output + - acoustics, iec + +All Python Notebooks +--------------------- +.. doesn't work for LiveScripts because nbgallery is inherently for notebooks. +.. Automatically makes a table of notebook names/icons and adds them to the toctree +.. nbgallery:: + :name: example_gallery_python + :glob: + + *_example + directional_waves diff --git a/docs/source/loads.rst b/docs/source/loads.rst index 3c9a8ec4..7ddc3b29 100644 --- a/docs/source/loads.rst +++ b/docs/source/loads.rst @@ -18,11 +18,10 @@ Examples Calculations are based on `IEC TS 62600-3:2020 ED1 `_ . +Submodules +-------------- The loads module contains the following submodules: * ``general``: Computes loads metrics such as damage equivalent loads. * ``graphics``: Generates graphics of loads statistics. * ``extreme``: Contains functions to calculate peak distribution. - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the loads module. - diff --git a/docs/source/matlab_installation.rst b/docs/source/matlab_installation.rst index c8ec7b43..03782390 100644 --- a/docs/source/matlab_installation.rst +++ b/docs/source/matlab_installation.rst @@ -6,7 +6,7 @@ MHKiT-MATLAB Installation The following section includes instructions for installing `MHKiT-MATLAB `_ . * New users should follow the :ref:`Installation Steps `. -* Experienced users can follow the :ref:`Advanced Installation Steps `. +* Experienced users can follow the :ref:`Advanced Installation Steps `. Installation Overview diff --git a/docs/source/mhkit-matlab/api.dolfyn.rst b/docs/source/mhkit-matlab/api.dolfyn.rst index d5b3d28b..569db6ed 100644 --- a/docs/source/mhkit-matlab/api.dolfyn.rst +++ b/docs/source/mhkit-matlab/api.dolfyn.rst @@ -10,7 +10,6 @@ processed and returned as MATLAB structures. .. Note:: DOLfYN support within MHKiT-MATLAB is a work in progress. Please submit any issues or improvements to the `MHKiT-MATLAB GitHub Repository `_ - .. Note:: The names of the functions below are of the convention ``path.path.function``. Only the function name is used when calling the function in MATLAB. For example, to call on ``mhkit.dolfyn.io.read_nortek`` simply use ``read_nortek``. @@ -22,7 +21,7 @@ binary Nortek (e.g., .VEC, .wpr, .ad2cp, etc.) or TRDI (.000, .PD0, .ENX, etc.) data files. .. mat:automodule:: mhkit.dolfyn.io - :members + :members: :undoc-members: :show-inheritance: diff --git a/docs/source/mhkit-matlab/api.loads.rst b/docs/source/mhkit-matlab/api.loads.rst index c60b6db4..a50f335c 100644 --- a/docs/source/mhkit-matlab/api.loads.rst +++ b/docs/source/mhkit-matlab/api.loads.rst @@ -19,13 +19,42 @@ Functions Description ``blade_moments`` Transfer function for deriving blade flap and edge moments using blade matrix. =========================================== ========================= - .. mat:automodule:: mhkit.loads.general :members: :no-undoc-members: :show-inheritance: +Extreme +"""""""""""" +The extreme submodule contains tools and functions for extreme value analysis +and wave data statistics. It includes methods for calculating peaks over threshold, estimating +short-term extreme distributions,and performing wave amplitude +normalization for most likely extreme response analysis. +=========================================== ========================= +Functions Description +=========================================== ========================= +``block_maxima`` Find the block maxima of a time-series. +``full_seastate_long_term_extreme`` Return the long-term extreme distribution of a response of interest using the full sea state approach. +``global_peaks`` Find the global peaks of a zero-centered response time-series. +``mler_coefficients`` Calculate MLER (most likely extreme response) coefficients from a sea state spectrum and a response RAO. +``mler_export_time_series`` Generate the wave amplitude time series at X0 from the calculated MLER coefficients +``mler_simulation`` Define the simulation parameters that are used in various MLER functionalities. +``mler_wave_amp_normalize`` Renormalizes the incoming amplitude of the MLER wave to the desired peak height (peak to MSL). +``number_of_short_term_peaks`` Estimate the number of peaks in a specified period. +``peaks_distribution_peaks_over_threshold`` Estimate the peaks distribution by fitting a generalized Pareto distribution. +``peaks_distribution_weibull`` Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response. +``peaks_distribution_weibull_tail_fit`` Estimate the peaks distribution by using the Weibull tail fit method. +``short_term_extreme`` Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response. +``ste_block_maxima_gev`` Approximate the short-term extreme distribution using the block maxima method and the Generalized Extreme Value distribution. +``ste_block_maxima_gumbel`` Approximate the short-term extreme distribution using the block maxima method and the Gumbel (right) distribution. +``ste_peaks`` Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response. +=========================================== ========================= + +.. mat:automodule:: mhkit.loads.extreme + :members: + :no-undoc-members: + :show-inheritance: Graphics """""""""""" @@ -42,4 +71,4 @@ Functions Description .. mat:automodule:: mhkit.loads.graphics :members: :no-undoc-members: - :show-inheritance: \ No newline at end of file + :show-inheritance: diff --git a/docs/source/mhkit-matlab/api.power.rst b/docs/source/mhkit-matlab/api.power.rst index bc9e851b..7be2d717 100644 --- a/docs/source/mhkit-matlab/api.power.rst +++ b/docs/source/mhkit-matlab/api.power.rst @@ -31,13 +31,20 @@ The quality submodule functions assess power quality, including harmonics, inter =========================================== ========================= Functions Description =========================================== ========================= -``harmonics`` Calculates the harmonics from time series of voltage or current based on IEC 61000-4-7. -``harmonic_subgroups`` Calculates the harmonic subgroups based on IEC 61000-4-7 -``total_harmonic_current_distortion`` Calculates the total harmonic current distortion (THC) based on IEC/TS 62600-30 -``interharmonics`` Calculates the interharmonics from the harmonics of current +``harmonics`` Calculates the harmonics from time series of voltage or current based on IEC 61000-4-7. +``harmonic_subgroups`` Calculates the harmonic subgroups based on IEC 61000-4-7 +``total_harmonic_current_distortion`` Calculates the total harmonic current distortion (THC) based on IEC/TS 62600-30 +``interharmonics`` Calculates the interharmonics from the harmonics of current +``calc_electrical_angle`` Calculates the electrical angle alpha_m(t) of the fundamental of the measured voltage (u_m(t)) according to IECTS 62600-30(ed1.0) Eq (3). +``calc_flicker_coefficient`` Calculates the flicker coefficient c(Phi_k) for each set of the 10 min measured voltage and current time-series, using the calculated flicker emission values using IECTS-62600-30 Eq (6). +``calc_fundamental_freq`` Calculates the fundamental frequency of the measured voltage u_m(t) using Zero-Crossing-Detection (ZCD) or Short-Time Fourier Transform (STFT). +``calc_ideal_voltage`` Calculates the ideal phase-to-neutral voltage source (V) u0(t) according to IECTS 62600-30(ed1.0) Eq (2). +``calc_Rfic_Lfic`` Calculates resistance (Rfic, Ohm) and inductance (Lfic, H) of the fictitious grid according to IECTS-62600-30 Eq (4-5). +``calc_shortterm_flicker_severity`` Calculates short-term flicker severity P_st according to the IEC 61000-4-15(ed2.0) section 5.7.2 Short-term flicker evaluation. +``calc_simulated_voltage`` Calculates the simulated voltage at a fictitious grid according to IEC standard 62600-30(ed1.0) Eq (1). +``flicker_ufic_workflow`` Conduct flicker assessment according to IECTS62600-30 and IECTS61400-21-1. =========================================== ========================= - .. mat:automodule:: mhkit.power.quality :members: :undoc-members: diff --git a/docs/source/mhkit-matlab/api.qc.rst b/docs/source/mhkit-matlab/api.qc.rst index d9eafa0e..1f51e87c 100644 --- a/docs/source/mhkit-matlab/api.qc.rst +++ b/docs/source/mhkit-matlab/api.qc.rst @@ -20,18 +20,7 @@ Functions Description .. Note:: The names of the functions below are of the convention ``path.path.function``. Only the function name is used when calling the function in MATLAB. For example, to call on ``mhkit.qc.check_timestamp`` simply use ``check_timestamp``. - .. mat:automodule:: mhkit.qc :members: :no-undoc-members: :show-inheritance: - - - - - - - - - - diff --git a/docs/source/mhkit-matlab/api.river.rst b/docs/source/mhkit-matlab/api.river.rst index 1d66621c..75dd36e6 100644 --- a/docs/source/mhkit-matlab/api.river.rst +++ b/docs/source/mhkit-matlab/api.river.rst @@ -11,18 +11,35 @@ IO """""""""""" The io submodule contains the following functions to load USGS Discharge data into structures. -=========================================== ========================= -Functions Description -=========================================== ========================= -``read_usgs_file`` Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis) into a structure -``request_usgs_file`` Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request into a structure -=========================================== ========================= +============================================== ========================= +Functions Description +============================================== ========================= +``read_usgs_file`` Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis) into a structure +``request_usgs_file`` Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request into a structure +``delft_3d_calculate_turbulent_intensity`` Returns the turbulent intensity percentage for a given data set for the specified points +``delft_3d_calculate_unorm`` Calculates the root mean squared value given three arrays. +``delft_3d_calculate_variable_interpolation`` Interpolates multiple variables from the Delft3D onto the same points. +``delft_3d_cleanup_turbulent_kinetic_energy`` Cleans up the turbulent kinetic energy values based on a threshold. +``delft_3d_convert_time`` Converts timestamps into a usable format. +``delft_3d_create_points`` Turns three coordinate inputs into a single output struct of points +``delft_3d_get_all_data_points`` Returns all data points for a specific variable at a given time index from a Delft 3D netCDF object. +``delft_3d_get_all_time`` Returns all time values from a Delft 3D netCDF object. +``delft_3d_get_keys`` Returns a struct of the key/values of a Delft 3D netCDF object. +``delft_3d_get_layer_data`` Returns layer data from a Delft 3D netCDF object. +``delft_3d_index_to_seconds`` Returns the time in seconds corresponding to the given index in the Delft3D dataset. +``delft_3d_interpolate_to_centerline`` Interpolates data to points along a centerline. +``delft_3d_open_netcdf`` Opens a Delft 3D netCDF file as a python netCDF4 object +``delft_3d_seconds_to_index`` Returns the index corresponding to the given number of seconds elapsed in the Delft3D dataset. +============================================== ========================= .. mat:automodule:: mhkit.river.IO :members: :undoc-members: - - + +.. mat:automodule:: mhkit.river.IO.delft_3d + :members: + :undoc-members: + Resource """""""""""" The resource submodule uses discharge data to compute exeedance probability, velocity, and power. The module also contains functions to compute the Froude number and to fit a polynomial to a series of points. The polynomial is used to estimate the relationship between discharge and velocity or velocity and power at an individual turbine. @@ -41,7 +58,6 @@ Functions Description .. mat:automodule:: mhkit.river.resource :members: :undoc-members: - Performance """""""""""" @@ -64,8 +80,7 @@ Functions Description .. mat:automodule:: mhkit.river.performance :members: :undoc-members: - - + Graphics """""""""""" The graphics submodule contains functions to plot river data and related metrics. The functions are designed to work in parallel with the :class:`~mhkit.river.resource` submodule. @@ -84,8 +99,3 @@ Functions Description .. mat:automodule:: mhkit.river.graphics :members: :undoc-members: - - - - - diff --git a/docs/source/mhkit-matlab/api.tidal.rst b/docs/source/mhkit-matlab/api.tidal.rst index aa387a9b..e75fba26 100644 --- a/docs/source/mhkit-matlab/api.tidal.rst +++ b/docs/source/mhkit-matlab/api.tidal.rst @@ -25,8 +25,6 @@ Functions Description :undoc-members: :show-inheritance: - - Resource """""""""""" The resource submodule uses discharge data to compute @@ -38,8 +36,8 @@ or velocity and power at an individual turbine. =========================================== ========================= Functions Description =========================================== ========================= -``principal_flow_direction`` Calculates the principal flow directions of current data -``Froude_number`` Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). +``principal_flow_direction`` Calculates the principal flow directions of current data +``Froude_number`` Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). ``exceedance_probability`` Calculates the exceedance probability =========================================== ========================= @@ -48,7 +46,6 @@ Functions Description :undoc-members: :show-inheritance: - Performance """""""""""" The performance submodule contains functions to compute equivalent diameter @@ -66,8 +63,8 @@ Functions Description ``ducted`` Calculates the equivalent diameter and projected capture area of a ducted turbine ``multiple_circular`` Calculates the equivalent diameter and projected capture area of a multiple circular turbine ``rectangular`` Calculates the equivalent diameter and projected capture area of a retangular turbine -``tip_speed_ratio`` Calculates the tip speed ratio (TSR) of a MEC device with rotor -``power_coefficient`` Calculates the calculates the power coefficient of MEC device +``tip_speed_ratio`` Calculates the tip speed ratio (TSR) of a MEC device with rotor +``power_coefficient`` Calculates the calculates the power coefficient of MEC device =========================================== ========================= .. mat:automodule:: mhkit.river.performance @@ -78,8 +75,6 @@ Functions Description .. Note:: Tidal device functions are the same as the River device functions - - Graphics """""""""""" The graphics submodule contains functions to plot river data and related metrics. @@ -96,11 +91,7 @@ Functions Description ``plot_tidal_phase_probability`` Discretizes the tidal series speed by bin size and returns a plot of the probability for each bin in the flood or ebb tidal phase. =========================================== ========================= - .. mat:automodule:: mhkit.tidal.graphics :members: :undoc-members: :show-inheritance: - - - \ No newline at end of file diff --git a/docs/source/mhkit-matlab/api.utils.rst b/docs/source/mhkit-matlab/api.utils.rst index 00a2260d..3418c197 100644 --- a/docs/source/mhkit-matlab/api.utils.rst +++ b/docs/source/mhkit-matlab/api.utils.rst @@ -2,7 +2,9 @@ Utils Module ^^^^^^^^^^^^^^^^^^^^ -The utils module includes helper functions. The module currently contains a single function to help users convert numeric indexes to datetime indexes. Additional helper functions could be added at a later date. +The utils module contains the essential utility functions for data +conversion, statistical analysis, caching, and event detection for the +MHKiT library. .. Note:: The names of the functions below are of the convention ``path.path.function``. Only the function name is used when calling the function in MATLAB. For example, to call on ``mhkit.wave.io.read_NDBC_file`` simply use ``read_NDBC_file``. @@ -13,9 +15,21 @@ Functions Description ``get_statistics`` Calculate mean, max, min and stdev statistics of continuous data for a given statistical window. ``excel_to_datetime`` Convert Excel datenum format to Python datetime. ``magnitude_phase`` Calculates magnitude and phase in two or three dimensions of the supplied vector. +``bplot`` This function will create a nice boxplot from a set of data. +``cached_webread`` Perform webread with caching to avoid redundant downloads. +``check_name`` Check if a given string is a valid field name for MATLAB struct. +``convert_numeric_dataframe_to_struct`` Converts a numeric pandas DataFrame to a MATLAB struct. +``convert_numeric_struct_to_dataframe`` Converts a MATLAB struct to a numeric pandas DataFrame. +``nc_file_precheck`` Check NetCDF filename before working on it +``nc_get_var_info`` Append NetCDF variable data and info to an existing structure (res). +``read_nc_file`` Read NetCDF data into a MATLAB struct(). +``read_nc_file_group`` Read NetCDF data into a MATLAB struct(). +``read_nc_file_var`` Read NetCDF data structure. +``reloadPy`` Reloads Python for use after Python code change. +``toggleToolbox`` Utility to enable/disable MATLAB toolboxes. +``uninstall_all_toolboxes`` Uninstall all currently installed toolboxes =========================================== ========================= - .. mat:automodule:: mhkit.utils :members: :no-undoc-members: diff --git a/docs/source/mhkit-matlab/api.wave.rst b/docs/source/mhkit-matlab/api.wave.rst index c4209d5f..12a0b6d6 100644 --- a/docs/source/mhkit-matlab/api.wave.rst +++ b/docs/source/mhkit-matlab/api.wave.rst @@ -29,14 +29,17 @@ Functions Description :members: :undoc-members: :show-inheritance: + .. mat:automodule:: mhkit.wave.IO.hindcast :members: :undoc-members: :show-inheritance: + .. mat:automodule:: mhkit.wave.IO.NDBC :members: :undoc-members: - :show-inheritance: + :show-inheritance: + .. mat:automodule:: mhkit.wave.IO.SWAN :members: :undoc-members: @@ -55,7 +58,6 @@ Functions Description ``pierson_moskowitz_spectrum`` Calculates Pierson Moskowitz spectrum from wave data. ``elevation_spectrum`` Calculates wave spectra from wave probe timeseries. =========================================== ========================= - The following metrics can be computed from the spectra: @@ -71,6 +73,8 @@ Functions Description ``environmental_contour`` Calculates environmental contours of extreme sea states ``frequency_moment`` Calculates the Nth frequency moment of the spectrum ``peak_period`` Calculates wave energy period from spectra +``samples_contour`` Get Hs points along a specified environmental contour using user-defined T values. +``samples_full_seastate`` Sample a sea state between contours of specified return periods. ``significant_wave_height`` Calculates wave height from spectra ``spectral_bandwidth`` Calculates bandwidth from spectra ``spectral_width`` Calculates wave spectral width from spectra @@ -85,9 +89,6 @@ Functions Description :undoc-members: :show-inheritance: - - - Performance """""""""""""""""" The performance submodule contains functions to compute capture length, statistics, performance matrices, and mean annual energy production. diff --git a/docs/source/mhkit-python/api.acoustics.rst b/docs/source/mhkit-python/api.acoustics.rst index 080ab1ce..4c51fa2c 100644 --- a/docs/source/mhkit-python/api.acoustics.rst +++ b/docs/source/mhkit-python/api.acoustics.rst @@ -2,67 +2,53 @@ Passive Acoustics Module ^^^^^^^^^^^^^^^^^^^^^^^^ -The passive acoustics module contains a set of functions -for analyzing and visualizing passive acoustic monitoring -data deployed in water bodies. This package reads in raw -*.wav* files and conducts basic acoustics analysis and -visualization. -To start using the module, import it directly from MHKiT: -``from mhkit import acoustics``. The analysis functions -are available directly from the main import, while the -I/O and graphics submodules are available from -``acoustics.io`` and ``acoustics.graphics``, respectively. - -I/O submodule -""""""""""""" -There is one primary function of the I/O submodule that -can be used to read in *.wav* files output by hydrophones, -``acoustics.io.read_hydrophone``. There are a couple -manufacturer specific wrappers around this function, as -well as one to export audio back into a *.wav* file. - -.. autosummary:: - :nosignatures: - - ~mhkit.acoustics.io.read_hydrophone - ~mhkit.acoustics.io.read_soundtrap - ~mhkit.acoustics.io.read_iclisten - ~mhkit.acoustics.io.export_audio - - -Analysis submodule -"""""""""""""""""" -Analysis functions are stored in the analysis submodule, -accessed directly from ``mhkit.acoustics``. These functions -are intended to be used on top of the I/O submodule, and -include functionality to calibrate data, create spectral -densities, sound pressure levels, and time or band -aggregate spectral data. - -.. autosummary:: - :nosignatures: - - ~mhkit.acoustics.minimum_frequency - ~mhkit.acoustics.sound_pressure_spectral_density - ~mhkit.acoustics.apply_calibration - ~mhkit.acoustics.sound_pressure_spectral_density_level - ~mhkit.acoustics.band_aggregate - ~mhkit.acoustics.time_aggregate - ~mhkit.acoustics.sound_pressure_level - ~mhkit.acoustics.third_octave_sound_pressure_level - ~mhkit.acoustics.decidecade_sound_pressure_level - - -Graphics submodule -"""""""""""""""""" -The graphics submodule provides functions for plotting -spectograms (frequency vs time) and spectra (psd vs frequency). -These functions are fully configurable via matplotlib -and can be pulled into existing plotting frameworks. - -.. autosummary:: - :nosignatures: - - ~mhkit.acoustics.graphics.plot_spectogram - ~mhkit.acoustics.graphics.plot_spectra +.. automodule:: mhkit.acoustics + :members: + :no-undoc-members: + :show-inheritance: + + .. automodule:: mhkit.acoustics.analysis + + .. autosummary:: + :nosignatures: + + ~minimum_frequency + ~sound_pressure_spectral_density + ~apply_calibration + ~sound_pressure_spectral_density_level + ~band_aggregate + ~time_aggregate + ~sound_pressure_level + ~third_octave_sound_pressure_level + ~decidecade_sound_pressure_level + +IO +"""" + +.. automodule:: mhkit.acoustics.io + :members: + :no-undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~read_hydrophone + ~read_soundtrap + ~read_iclisten + ~export_audio + +Graphics +"""""""" + +.. automodule:: mhkit.acoustics.graphics + :members: + :no-undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~plot_spectrogram + ~plot_spectra diff --git a/docs/source/mhkit-python/api.dolfyn.rst b/docs/source/mhkit-python/api.dolfyn.rst index e7efc361..519da993 100644 --- a/docs/source/mhkit-python/api.dolfyn.rst +++ b/docs/source/mhkit-python/api.dolfyn.rst @@ -12,23 +12,28 @@ first way is to import the entire module using Many functions are directly available from the main dolfyn import: -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.io.api.read - ~mhkit.dolfyn.io.api.read_example - ~mhkit.dolfyn.io.api.save - ~mhkit.dolfyn.io.api.load - ~mhkit.dolfyn.io.api.save_mat - ~mhkit.dolfyn.io.api.load_mat - ~mhkit.dolfyn.rotate.api.rotate2 - ~mhkit.dolfyn.rotate.api.calc_principal_heading - ~mhkit.dolfyn.rotate.api.set_declination - ~mhkit.dolfyn.rotate.api.set_inst2head_rotmat - ~mhkit.dolfyn.rotate.base.euler2orient - ~mhkit.dolfyn.rotate.base.orient2euler - ~mhkit.dolfyn.rotate.base.quaternion2orient - ~mhkit.dolfyn.velocity.VelBinner +.. automodule:: mhkit.dolfyn + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~io.api.read + ~io.api.read_example + ~io.api.save + ~io.api.load + ~io.api.save_mat + ~io.api.load_mat + ~rotate.api.rotate2 + ~rotate.api.calc_principal_heading + ~rotate.api.set_declination + ~rotate.api.set_inst2head_rotmat + ~rotate.base.euler2orient + ~rotate.base.orient2euler + ~rotate.base.quaternion2orient + ~velocity.VelBinner ADP Submodule """"""""""""" @@ -38,16 +43,22 @@ The ADP module contains routines for reading and working with ADP/ADCP data and is imported using `from mhkit.dolfyn.adp import api`. It contains: -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.io.api.read - ~mhkit.dolfyn.io.api.load - ~mhkit.dolfyn.rotate.api.rotate2 - ~mhkit.dolfyn.rotate.api.calc_principal_heading - ~mhkit.dolfyn.adp.clean - ~mhkit.dolfyn.velocity.VelBinner - ~mhkit.dolfyn.adp.turbulence.ADPBinner +.. automodule:: mhkit.dolfyn.adp + :members: + :imported-members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~api.read + ~api.load + ~api.rotate2 + ~api.calc_principal_heading + ~api.clean + ~api.VelBinner + ~api.ADPBinner ADV Submodule """"""""""""" @@ -55,19 +66,25 @@ The ADV module contains routines for reading and working with ADV data and is imported using `from mhkit.dolfyn.adv import api`. It contains: -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.io.api.read - ~mhkit.dolfyn.io.api.load - ~mhkit.dolfyn.rotate.api.rotate2 - ~mhkit.dolfyn.rotate.api.calc_principal_heading - ~mhkit.dolfyn.rotate.api.set_inst2head_rotmat - ~mhkit.dolfyn.adv.clean - ~mhkit.dolfyn.adv.motion.correct_motion - ~mhkit.dolfyn.velocity.VelBinner - ~mhkit.dolfyn.adv.turbulence.ADVBinner - ~mhkit.dolfyn.adv.turbulence.turbulence_statistics +.. automodule:: mhkit.dolfyn.adv + :members: + :imported-members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~api.read + ~api.load + ~api.rotate2 + ~api.calc_principal_heading + ~api.set_inst2head_rotmat + ~api.clean + ~api.correct_motion + ~api.VelBinner + ~api.ADVBinner + ~api.turbulence_statistics IO Submodule """""""""""" @@ -75,15 +92,20 @@ The io submodule contains the following functions to read binary Nortek (e.g., .VEC, .wpr, .ad2cp, etc.) or TRDI (.000, .PD0, .ENX, etc.) data file. -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.io.api.read - ~mhkit.dolfyn.io.api.read_example - ~mhkit.dolfyn.io.api.save - ~mhkit.dolfyn.io.api.load - ~mhkit.dolfyn.io.api.save_mat - ~mhkit.dolfyn.io.api.load_mat +.. automodule:: mhkit.dolfyn.io + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~api.read + ~api.read_example + ~api.save + ~api.load + ~api.save_mat + ~api.load_mat .. automodule:: mhkit.dolfyn.io.api :members: @@ -125,17 +147,22 @@ rotating into the "earth" frame, defined as East-North-Up (ENU). The earth frame can then be rotated to the principal axes, defined as streamwise-cross_stream-vertical. -.. autosummary:: - :nosignatures: +.. automodule:: mhkit.dolfyn.rotate + :members: + :undoc-members: + :show-inheritance: - ~mhkit.dolfyn.rotate.api.rotate2 - ~mhkit.dolfyn.rotate.api.calc_principal_heading - ~mhkit.dolfyn.rotate.api.set_declination - ~mhkit.dolfyn.rotate.api.set_inst2head_rotmat - ~mhkit.dolfyn.rotate.base.euler2orient - ~mhkit.dolfyn.rotate.base.orient2euler - ~mhkit.dolfyn.rotate.base.quaternion2orient - ~mhkit.dolfyn.rotate.base.calc_tilt + .. autosummary:: + :nosignatures: + + ~api.rotate2 + ~api.calc_principal_heading + ~api.set_declination + ~api.set_inst2head_rotmat + ~base.euler2orient + ~base.orient2euler + ~base.quaternion2orient + ~base.calc_tilt .. automodule:: mhkit.dolfyn.rotate.api :members: @@ -147,48 +174,48 @@ axes, defined as streamwise-cross_stream-vertical. :undoc-members: :show-inheritance: - Cleaning Data """"""""""""" The clean submodule contains basic quality control tools specific to ADCP and ADVs. -ADP-specific functions: - -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.adp.clean.set_range_offset - ~mhkit.dolfyn.adp.clean.water_depth_from_amplitude - ~mhkit.dolfyn.adp.clean.water_depth_from_pressure - ~mhkit.dolfyn.adp.clean.remove_surface_interference - ~mhkit.dolfyn.adp.clean.correlation_filter - ~mhkit.dolfyn.adp.clean.medfilt_orient - ~mhkit.dolfyn.adp.clean.val_exceeds_thresh - ~mhkit.dolfyn.adp.clean.fillgaps_time - ~mhkit.dolfyn.adp.clean.fillgaps_depth - -ADV-specific functions: - -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.adv.clean.clean_fill - ~mhkit.dolfyn.adv.clean.fill_nan_ensemble_mean - ~mhkit.dolfyn.adv.clean.spike_thresh - ~mhkit.dolfyn.adv.clean.range_limit - ~mhkit.dolfyn.adv.clean.GN2002 +ADP Cleaning ++++++++++++++ .. automodule:: mhkit.dolfyn.adp.clean :members: :undoc-members: :show-inheritance: - + + .. autosummary:: + :nosignatures: + + ~set_range_offset + ~water_depth_from_amplitude + ~water_depth_from_pressure + ~remove_surface_interference + ~correlation_filter + ~medfilt_orient + ~val_exceeds_thresh + ~fillgaps_time + ~fillgaps_depth + +ADV Cleaning ++++++++++++++ + .. automodule:: mhkit.dolfyn.adv.clean :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~clean_fill + ~fill_nan_ensemble_mean + ~spike_thresh + ~range_limit + ~GN2002 Motion Correction """"""""""""""""" @@ -197,16 +224,15 @@ Nortek Vector ADV-IMU data using the onboard IMU, if equipped. Requires `proper setup `_ prior to collecting data. -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.adv.motion.correct_motion - .. automodule:: mhkit.dolfyn.adv.motion :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~correct_motion Velocity Analysis """"""""""""""""" @@ -218,25 +244,25 @@ be called from `VelBinner`. :nosignatures: ~mhkit.dolfyn.velocity.VelBinner - ~mhkit.dolfyn.binned.TimeBinner.reshape - ~mhkit.dolfyn.binned.TimeBinner.detrend - ~mhkit.dolfyn.binned.TimeBinner.demean - ~mhkit.dolfyn.binned.TimeBinner.mean - ~mhkit.dolfyn.binned.TimeBinner.variance - ~mhkit.dolfyn.binned.TimeBinner.standard_deviation ~mhkit.dolfyn.velocity.VelBinner.bin_average ~mhkit.dolfyn.velocity.VelBinner.bin_variance ~mhkit.dolfyn.velocity.VelBinner.autocovariance ~mhkit.dolfyn.velocity.VelBinner.turbulence_intensity ~mhkit.dolfyn.velocity.VelBinner.turbulent_kinetic_energy ~mhkit.dolfyn.velocity.VelBinner.power_spectral_density + ~mhkit.dolfyn.binned.TimeBinner.reshape + ~mhkit.dolfyn.binned.TimeBinner.detrend + ~mhkit.dolfyn.binned.TimeBinner.demean + ~mhkit.dolfyn.binned.TimeBinner.mean + ~mhkit.dolfyn.binned.TimeBinner.variance + ~mhkit.dolfyn.binned.TimeBinner.standard_deviation -.. automodule:: mhkit.dolfyn.binned +.. automodule:: mhkit.dolfyn.velocity :members: :undoc-members: :show-inheritance: -.. automodule:: mhkit.dolfyn.velocity +.. automodule:: mhkit.dolfyn.binned :members: :undoc-members: :show-inheritance: @@ -247,52 +273,50 @@ ADV Turbulence Analysis Functions for analyzing ADV data via the `ADVBinner` class, beyond those described in `VelBinner`. -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.adv.turbulence.ADVBinner - ~mhkit.dolfyn.adv.turbulence.turbulence_statistics - ~mhkit.dolfyn.adv.turbulence.ADVBinner.reynolds_stress - ~mhkit.dolfyn.adv.turbulence.ADVBinner.cross_spectral_density - ~mhkit.dolfyn.adv.turbulence.ADVBinner.doppler_noise_level - ~mhkit.dolfyn.adv.turbulence.ADVBinner.check_turbulence_cascade_slope - ~mhkit.dolfyn.adv.turbulence.ADVBinner.dissipation_rate_LT83 - ~mhkit.dolfyn.adv.turbulence.ADVBinner.dissipation_rate_SF - ~mhkit.dolfyn.adv.turbulence.ADVBinner.dissipation_rate_TE01 - ~mhkit.dolfyn.adv.turbulence.ADVBinner.integral_length_scales - .. automodule:: mhkit.dolfyn.adv.turbulence :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~ADVBinner + ~turbulence_statistics + ~ADVBinner.reynolds_stress + ~ADVBinner.cross_spectral_density + ~ADVBinner.doppler_noise_level + ~ADVBinner.check_turbulence_cascade_slope + ~ADVBinner.dissipation_rate_LT83 + ~ADVBinner.dissipation_rate_SF + ~ADVBinner.dissipation_rate_TE01 + ~ADVBinner.integral_length_scales AD2CP Turbulence Analysis """"""""""""""""""""""""" Functions for analyzing turbulence from AD2CP measurements via the `ADPBinner` class. -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.adv.turbulence.ADPBinner - ~mhkit.dolfyn.adv.turbulence.ADPBinner.dudz - ~mhkit.dolfyn.adv.turbulence.ADPBinner.dvdz - ~mhkit.dolfyn.adv.turbulence.ADPBinner.dwdz - ~mhkit.dolfyn.adv.turbulence.ADPBinner.shear_squared - ~mhkit.dolfyn.adv.turbulence.ADPBinner.doppler_noise_level - ~mhkit.dolfyn.adv.turbulence.ADPBinner.reynolds_stress_4beam - ~mhkit.dolfyn.adv.turbulence.ADPBinner.stress_tensor_5beam - ~mhkit.dolfyn.adv.turbulence.ADPBinner.check_turbulence_cascade_slope - ~mhkit.dolfyn.adv.turbulence.ADPBinner.dissipation_rate_LT83 - ~mhkit.dolfyn.adv.turbulence.ADPBinner.dissipation_rate_SF - ~mhkit.dolfyn.adv.turbulence.ADPBinner.friction_velocity - .. automodule:: mhkit.dolfyn.adp.turbulence :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~ADPBinner + ~ADPBinner.dudz + ~ADPBinner.dvdz + ~ADPBinner.dwdz + ~ADPBinner.shear_squared + ~ADPBinner.doppler_noise_level + ~ADPBinner.reynolds_stress_4beam + ~ADPBinner.stress_tensor_5beam + ~ADPBinner.check_turbulence_cascade_slope + ~ADPBinner.dissipation_rate_LT83 + ~ADPBinner.dissipation_rate_SF + ~ADPBinner.friction_velocity Tools """"" @@ -300,59 +324,60 @@ Spectral analysis and miscellaneous DOLfYN functions are stored here. These functions are used throughout DOLfYN's core code and may also be helpful to users in general. -FFT-based Functions: - -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.tools.fft.fft_frequency - ~mhkit.dolfyn.tools.fft.psd_1D - ~mhkit.dolfyn.tools.fft.cpsd_1D - ~mhkit.dolfyn.tools.fft.cpsd_quasisync_1D - -Other Functions: - -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.tools.misc.detrend_array - ~mhkit.dolfyn.tools.misc.group - ~mhkit.dolfyn.tools.misc.slice1d_along_axis - ~mhkit.dolfyn.tools.misc.convert_degrees - ~mhkit.dolfyn.tools.misc.fillgaps - ~mhkit.dolfyn.tools.misc.interpgaps - ~mhkit.dolfyn.tools.misc.medfiltnan +FFT-based Functions ++++++++++++++++++++ .. automodule:: mhkit.dolfyn.tools.fft :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~fft_frequency + ~psd_1D + ~cpsd_1D + ~cpsd_quasisync_1D + +Other Functions ++++++++++++++++ + .. automodule:: mhkit.dolfyn.tools.misc :members: :undoc-members: :show-inheritance: + .. autosummary:: + :nosignatures: + + ~detrend_array + ~group + ~slice1d_along_axis + ~convert_degrees + ~fillgaps + ~interpgaps + ~medfiltnan Time """" The time submodule contains functions to modify the format of the stored time between a variety of time formats. -.. autosummary:: - :nosignatures: - - ~mhkit.dolfyn.time.epoch2dt64 - ~mhkit.dolfyn.time.dt642epoch - ~mhkit.dolfyn.time.date2dt64 - ~mhkit.dolfyn.time.dt642date - ~mhkit.dolfyn.time.epoch2date - ~mhkit.dolfyn.time.date2str - ~mhkit.dolfyn.time.date2epoch - ~mhkit.dolfyn.time.date2matlab - ~mhkit.dolfyn.time.matlab2date - .. automodule:: mhkit.dolfyn.time :members: :undoc-members: :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~epoch2dt64 + ~dt642epoch + ~date2dt64 + ~dt642date + ~epoch2date + ~date2str + ~date2epoch + ~date2matlab + ~matlab2date diff --git a/docs/source/mhkit-python/api.loads.rst b/docs/source/mhkit-python/api.loads.rst index 83c33264..1e7c00f3 100644 --- a/docs/source/mhkit-python/api.loads.rst +++ b/docs/source/mhkit-python/api.loads.rst @@ -2,66 +2,68 @@ Loads Module ^^^^^^^^^^^^^^^^^^^^ -The loads module contains a set of functions to calculate quantities of interest for mechanical loads assessments. + +.. automodule:: mhkit.loads + :members: + :no-undoc-members: + :show-inheritance: General """""""""""" -The loads general submodule contains general loads calculations that can be applied to most MRE devices. - -.. autosummary:: - :nosignatures: - - ~mhkit.loads.general.bin_statistics - ~mhkit.loads.general.blade_moments - ~mhkit.loads.general.damage_equivalent_load - .. automodule:: mhkit.loads.general - :members: - :no-undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + .. autosummary:: + :nosignatures: + + ~bin_statistics + ~blade_moments + ~damage_equivalent_load Graphics """""""""""" -The graphics submodule contains functions to plot loads metrics. - -.. autosummary:: - :nosignatures: - ~mhkit.loads.graphics.plot_statistics - ~mhkit.loads.graphics.plot_bin_statistics - .. automodule:: mhkit.loads.graphics - :members: - :no-undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + .. autosummary:: + :nosignatures: + + ~plot_statistics + ~plot_bin_statistics Extreme """""""""""" -The extreme submodule contains functions to calculate peak distribution. - -.. autosummary:: - :nosignatures: - ~mhkit.loads.extreme.global_peaks - ~mhkit.loads.extreme.number_of_short_term_peaks - ~mhkit.loads.extreme.peaks_distribution_weibull - ~mhkit.loads.extreme.peaks_distribution_weibull_tail_fit - ~mhkit.loads.extreme.peaks_distribution_peaks_over_threshold - ~mhkit.loads.extreme.ste_peaks - ~mhkit.loads.extreme.block_maxima - ~mhkit.loads.extreme.ste_block_maxima_gev - ~mhkit.loads.extreme.ste_block_maxima_gumbel - ~mhkit.loads.extreme.short_term_extreme - ~mhkit.loads.extreme.full_seastate_long_term_extreme - ~mhkit.loads.extreme.mler_coefficients - ~mhkit.loads.extreme.mler_simulation - ~mhkit.loads.extreme.mler_wave_amp_normalize - ~mhkit.loads.extreme.mler_export_time_series - .. automodule:: mhkit.loads.extreme - :members: - :no-undoc-members: - :show-inheritance: \ No newline at end of file + :members: + :undoc-members: + :imported-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~ste_peaks + ~block_maxima + ~ste_block_maxima_gev + ~ste_block_maxima_gumbel + ~ste + ~short_term_extreme + ~full_seastate_long_term_extreme + ~mler_coefficients + ~mler_simulation + ~mler_wave_amp_normalize + ~mler_export_time_series + ~global_peaks + ~number_of_short_term_peaks + ~peaks_distribution_weibull + ~peaks_distribution_weibull_tail_fit + ~automatic_hs_threshold + ~peaks_distribution_peaks_over_threshold + ~return_year_value diff --git a/docs/source/mhkit-python/api.mooring.rst b/docs/source/mhkit-python/api.mooring.rst index d17f87eb..42949fe4 100644 --- a/docs/source/mhkit-python/api.mooring.rst +++ b/docs/source/mhkit-python/api.mooring.rst @@ -5,37 +5,32 @@ Mooring Module The mooring module contains a set of functions to read MoorDyn output files and calculate lay length of a mooring line. .. automodule:: mhkit.mooring - :members: - :no-undoc-members: - :show-inheritance: - + :members: + :no-undoc-members: + :show-inheritance: + IO """""""""""" -The io submodule contains a function to -load MoorDyn data and convert it to xarray: - -.. autosummary:: - :nosignatures: - - ~mhkit.mooring.io.read_moordyn .. automodule:: mhkit.mooring.io - :members: - :undoc-members: - :show-inheritance: - - + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~read_moordyn + Graphics """""""""""" -The graphics submodule contains functions to visualize -mooring lines. -.. autosummary:: - :nosignatures: - - ~mhkit.mooring.graphics.animate - .. automodule:: mhkit.mooring.graphics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~animate diff --git a/docs/source/mhkit-python/api.power.rst b/docs/source/mhkit-python/api.power.rst index 170b2819..5100ad76 100644 --- a/docs/source/mhkit-python/api.power.rst +++ b/docs/source/mhkit-python/api.power.rst @@ -4,35 +4,37 @@ Power Module ^^^^^^^^^^^^^^^^^^^^ The power module contains a set of functions to calculate quantities of interest for power production and power quality. +.. automodule:: mhkit.power + :members: + :no-undoc-members: + :show-inheritance: + Characteristics """""""""""""""""" -The characteristics submodule calculates power quantities of interest from voltage and current timseries. - -.. autosummary:: - :nosignatures: - ~mhkit.power.characteristics.instantaneous_frequency - ~mhkit.power.characteristics.dc_power - ~mhkit.power.characteristics.ac_power_three_phase - .. automodule:: mhkit.power.characteristics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~instantaneous_frequency + ~dc_power + ~ac_power_three_phase Quality """"""""" -The quality submodule functions assess power quality, including harmonics, interharmonics, and distortion. Calculations are based on `IEC TS 62600-30:2018 ED1 `_ and `IEC TS 61000-4-7:2008 ED2 `_. +.. automodule:: mhkit.power.quality + :members: + :undoc-members: + :show-inheritance: -.. autosummary:: - :nosignatures: + .. autosummary:: + :nosignatures: - ~mhkit.power.quality.harmonics - ~mhkit.power.quality.harmonic_subgroups - ~mhkit.power.quality.total_harmonic_current_distortion - ~mhkit.power.quality.interharmonics - -.. automodule:: mhkit.power.quality - :members: - :undoc-members: - :show-inheritance: \ No newline at end of file + ~harmonics + ~harmonic_subgroups + ~total_harmonic_current_distortion + ~interharmonics diff --git a/docs/source/mhkit-python/api.qc.rst b/docs/source/mhkit-python/api.qc.rst index d88420b0..504f4e0e 100644 --- a/docs/source/mhkit-python/api.qc.rst +++ b/docs/source/mhkit-python/api.qc.rst @@ -3,25 +3,19 @@ QC Module ^^^^^^^^^^^^^^^^^^^^ The QC module includes quality control functions from Pecos, see https://pecos.readthedocs.io for more details. - -.. autosummary:: - :nosignatures: - - ~mhkit.qc.check_timestamp - ~mhkit.qc.check_missing - ~mhkit.qc.check_corrupt - ~mhkit.qc.check_range - ~mhkit.qc.check_delta - ~mhkit.qc.check_outlier .. automodule:: mhkit.qc - :members: - :no-undoc-members: - :show-inheritance: - -.. autofunction:: mhkit.qc.check_timestamp -.. autofunction:: mhkit.qc.check_missing -.. autofunction:: mhkit.qc.check_corrupt -.. autofunction:: mhkit.qc.check_range -.. autofunction:: mhkit.qc.check_delta -.. autofunction:: mhkit.qc.check_outlier \ No newline at end of file + :members: + :imported-members: + :no-undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~check_timestamp + ~check_missing + ~check_corrupt + ~check_range + ~check_delta + ~check_outlier diff --git a/docs/source/mhkit-python/api.river.rst b/docs/source/mhkit-python/api.river.rst index 9bd25ea1..87483849 100644 --- a/docs/source/mhkit-python/api.river.rst +++ b/docs/source/mhkit-python/api.river.rst @@ -3,41 +3,55 @@ River Module ^^^^^^^^^^^^^^^^^^^^^^^^^^ The river module contains a set of functions to calculate quantities of interest for river energy converters (REC). - -**Discharge time series data** is stored as a pandas DataFrame indexed by time. - Time can be specified in datetime or in seconds. The column names describe the type of data in each column. -.. This doesn't generate anything .. automodule:: mhkit.river - :members: - :no-undoc-members: - :show-inheritance: + :members: + :no-undoc-members: + :show-inheritance: IO """""" The io submodule contains the following functions to load USGS discharge and Delft3D data. -.. autosummary:: - :nosignatures: - - ~mhkit.river.io.usgs.read_usgs_file - ~mhkit.river.io.usgs.request_usgs_data - ~mhkit.river.io.d3d.get_layer_data - ~mhkit.river.io.d3d.create_points - ~mhkit.river.io.d3d.variable_interpolation - ~mhkit.river.io.d3d.get_all_data_points - ~mhkit.river.io.d3d.turbulent_intensity - -.. automodule:: mhkit.river.io.d3d - :members: - :undoc-members: - :show-inheritance: - +.. automodule:: mhkit.river.io + :members: + :no-undoc-members: + :show-inheritance: + +USGS +++++ + .. automodule:: mhkit.river.io.usgs - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~read_usgs_file + ~request_usgs_data + +D3D ++++ + +.. automodule:: mhkit.river.io.d3d + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~get_all_time + ~index_to_seconds + ~seconds_to_index + ~get_layer_data + ~create_points + ~variable_interpolation + ~get_all_data_points + ~turbulent_intensity Resource """""""""""" @@ -47,20 +61,20 @@ to compute the Froude number and to fit a polynomial to a series of points. The polynomial is used to estimate the relationship between discharge and velocity or velocity and power at an individual turbine. -.. autosummary:: - :nosignatures: - - ~mhkit.river.resource.Froude_number - ~mhkit.river.resource.exceedance_probability - ~mhkit.river.resource.polynomial_fit - ~mhkit.river.resource.discharge_to_velocity - ~mhkit.river.resource.velocity_to_power - ~mhkit.river.resource.energy_produced - .. automodule:: mhkit.river.resource - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~Froude_number + ~exceedance_probability + ~polynomial_fit + ~discharge_to_velocity + ~velocity_to_power + ~energy_produced Performance """""""""""" @@ -72,36 +86,36 @@ is an enclosed VAWT. A multiple-circular devices is a device with multiple VAWTs per device. The performance module also includes functions for calculating a turbine coeffcient of power and tip speed ratio. -.. autosummary:: - :nosignatures: - - ~mhkit.river.performance.circular - ~mhkit.river.performance.ducted - ~mhkit.river.performance.rectangular - ~mhkit.river.performance.multiple_circular - ~mhkit.river.performance.tip_speed_ratio - ~mhkit.river.performance.power_coefficient - .. automodule:: mhkit.river.performance - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~circular + ~ducted + ~rectangular + ~multiple_circular + ~tip_speed_ratio + ~power_coefficient + Graphics """""""""""" The graphics submodule contains functions to plot river resource data and related metrics. -.. autosummary:: - :nosignatures: - - ~mhkit.river.graphics.plot_flow_duration_curve - ~mhkit.river.graphics.plot_velocity_duration_curve - ~mhkit.river.graphics.plot_power_duration_curve - ~mhkit.river.graphics.plot_discharge_timeseries - ~mhkit.river.graphics.plot_discharge_vs_velocity - ~mhkit.river.graphics.plot_velocity_vs_power - .. automodule:: mhkit.river.graphics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~plot_flow_duration_curve + ~plot_velocity_duration_curve + ~plot_power_duration_curve + ~plot_discharge_timeseries + ~plot_discharge_vs_velocity + ~plot_velocity_vs_power diff --git a/docs/source/mhkit-python/api.tidal.rst b/docs/source/mhkit-python/api.tidal.rst index 554b46af..fd0a365b 100644 --- a/docs/source/mhkit-python/api.tidal.rst +++ b/docs/source/mhkit-python/api.tidal.rst @@ -1,58 +1,49 @@ .. _tidal_api: Tidal Module -^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^ The tidal module contains a set of functions to calculate quantities of interest for tidal energy converters (TEC). The tidal module uses timeseries data of velocity and direction. - -* **Velocity/ direction time series data** is stored as a pandas DataFrame indexed by time. - Time can be specified in datetime or in seconds. The column names describe the type of data in each column. - -.. This doesn't generate anything .. automodule:: mhkit.tidal - :members: - :no-undoc-members: - :show-inheritance: + :members: + :no-undoc-members: + :show-inheritance: IO """""""""""" The io submodule contains the following functions to -load NOAA velocity/ direction data - -.. autosummary:: - :nosignatures: - - ~mhkit.tidal.io.noaa.request_noaa_data - ~mhkit.tidal.io.noaa.read_noaa_json - +load NOAA velocity/ direction data. .. automodule:: mhkit.tidal.io - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~noaa.request_noaa_data + ~noaa.read_noaa_json Resource """""""""""" The resource module allows the user to calculate the ebb and flood directions of the tidal resource given a timeseries of directional data. -.. autosummary:: - :nosignatures: - - ~mhkit.tidal.resource.principal_flow_directions - ~mhkit.tidal.resource.Froude_number - ~mhkit.tidal.resource.exceedance_probability - .. automodule:: mhkit.tidal.resource - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: -.. autofunction:: mhkit.tidal.resource.Froude_number -.. autofunction:: mhkit.tidal.resource.exceedance_probability + ~principal_flow_directions + ~Froude_number + ~exceedance_probability Performance """""""""""" @@ -64,56 +55,40 @@ is an enclosed VAWT. A multiple-circular devices is a device with multiple VAWTs per device. This submodule also contains functions for computing the tip speed ratio and power coefficient from a blade/rotor type device. - -.. autosummary:: - :nosignatures: - - ~mhkit.tidal.performance.circular - ~mhkit.tidal.performance.ducted - ~mhkit.tidal.performance.rectangular - ~mhkit.tidal.performance.multiple_circular - ~mhkit.tidal.performance.tip_speed_ratio - ~mhkit.tidal.performance.power_coefficient - ~mhkit.tidal.performance.power_curve - ~mhkit.tidal.performance.device_efficiency - ~mhkit.tidal.performance.velocity_profiles - - .. automodule:: mhkit.tidal.performance - :members: - :undoc-members: - :show-inheritance: - -.. autofunction:: mhkit.tidal.performance.circular -.. autofunction:: mhkit.tidal.performance.ducted -.. autofunction:: mhkit.tidal.performance.rectangular -.. autofunction:: mhkit.tidal.performance.multiple_circular -.. autofunction:: mhkit.tidal.performance.tip_speed_ratio -.. autofunction:: mhkit.tidal.performance.power_coefficient - + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~circular + ~ducted + ~rectangular + ~multiple_circular + ~tip_speed_ratio + ~power_coefficient + ~power_curve + ~velocity_profiles + ~device_efficiency Graphics """""""""""" The graphics submodule contains functions to plot tidal resource data and related metrics. -.. autosummary:: - :nosignatures: - - ~mhkit.tidal.graphics.plot_rose - ~mhkit.tidal.graphics.plot_joint_probability_distribution - ~mhkit.tidal.graphics.plot_current_timeseries - ~mhkit.tidal.graphics.plot_velocity_duration_curve - ~mhkit.tidal.graphics.tidal_phase_probability - ~mhkit.tidal.graphics.tidal_phase_exceedance - .. automodule:: mhkit.tidal.graphics - :members: - :undoc-members: - :show-inheritance: - -.. autofunction:: mhkit.tidal.graphics.plot_velocity_duration_curve - :noindex: - - - + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~plot_rose + ~plot_joint_probability_distribution + ~plot_current_timeseries + ~plot_velocity_duration_curve + ~tidal_phase_probability + ~tidal_phase_exceedance diff --git a/docs/source/mhkit-python/api.utils.rst b/docs/source/mhkit-python/api.utils.rst index 2fbcc63c..4b80f64a 100644 --- a/docs/source/mhkit-python/api.utils.rst +++ b/docs/source/mhkit-python/api.utils.rst @@ -3,35 +3,32 @@ Utils Module ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The utils module includes helper functions. The module currently contains a single function to help users -convert numeric indexes to datetime indexes. Additional helper functions could be added at a later date. - - -.. autosummary:: - :nosignatures: - - ~mhkit.utils.matlab_to_datetime - ~mhkit.utils.excel_to_datetime - ~mhkit.utils.get_statistics - ~mhkit.utils.vector_statistics - ~mhkit.utils.unwrap_vector - ~mhkit.utils.magnitude_phase - ~mhkit.utils.unorm - ~mhkit.utils.handle_caching - ~mhkit.utils.clear_cache - ~mhkit.utils.upcrossing - ~mhkit.utils.peaks - ~mhkit.utils.troughs - ~mhkit.utils.heights - ~mhkit.utils.periods - ~mhkit.utils.custom - ~mhkit.utils.to_numeric_array - ~mhkit.utils.convert_to_dataset - ~mhkit.utils.convert_to_dataarray - ~mhkit.utils.convert_nested_dict_and_pandas - .. automodule:: mhkit.utils - :members: - :no-undoc-members: - :show-inheritance: + :members: + :imported-members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + ~matlab_to_datetime + ~excel_to_datetime + ~index_to_datetime + ~get_statistics + ~vector_statistics + ~unwrap_vector + ~magnitude_phase + ~unorm + ~handle_caching + ~clear_cache + ~upcrossing + ~peaks + ~troughs + ~heights + ~periods + ~custom + ~to_numeric_array + ~convert_to_dataset + ~convert_to_dataarray + ~convert_nested_dict_and_pandas diff --git a/docs/source/mhkit-python/api.wave.rst b/docs/source/mhkit-python/api.wave.rst index b4d5d400..44d595a4 100644 --- a/docs/source/mhkit-python/api.wave.rst +++ b/docs/source/mhkit-python/api.wave.rst @@ -7,256 +7,222 @@ calculate quantities of interest for wave energy converters (WEC). The wave module uses wave elevation time series data and spectra data. -* **Wave elevation time series data** is stored as a pandas DataFrame - indexed by time. Time can be specified in datetime or in seconds. - The column names describe the type of data in each column (for - example, data from multiple sensors). - -* **Spectra data** is stored as a pandas DataFrame and may be indexed - by frequency in Hz or datetime. The resource and graphic modules - expects spectra indexed by frequency. Timeseries spectra may be - passed to these functions using after ausing the pandas method - ``transpose``. - -.. This doesn't generate anything .. automodule:: mhkit.wave :members: :no-undoc-members: :show-inheritance: - + IO --- The io submodule contains the following functions to request, load, -and manipulate `National Data Buoy Center (NDBC) `_ data, `WPTO Hindcast `_ data, and -`CDiP `_ data. The io module also has functions to load and manipulate +and manipulate `CDiP `_ data, `National Data Buoy Center (NDBC) `_ data, +`WPTO Hindcast `_ data, and `WIND Toolkit data `_ data. +The io module also has functions to load and manipulate `WEC-Sim `_ and `SWAN `_ model data. - -Wave IO (Input/Output) Function Summary -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: mhkit.wave.io + :members: + :no-undoc-members: + :show-inheritance: CDiP -"""" +^^^^ + +.. automodule:: mhkit.wave.io.cdip + :members: + :undoc-members: + :show-inheritance: -.. autosummary:: - :nosignatures: + .. autosummary:: + :nosignatures: - ~mhkit.wave.io.cdip.request_netCDF - ~mhkit.wave.io.cdip.request_parse_workflow - ~mhkit.wave.io.cdip.get_netcdf_variables + ~request_netCDF + ~request_parse_workflow + ~get_netcdf_variables NDBC -"""" - -.. autosummary:: - :nosignatures: - - ~mhkit.wave.io.ndbc.read_file - ~mhkit.wave.io.ndbc.available_data - ~mhkit.wave.io.ndbc.request_data - ~mhkit.wave.io.ndbc.to_datetime_index - ~mhkit.wave.io.ndbc.dates_to_datetime - ~mhkit.wave.io.ndbc.parameter_units - ~mhkit.wave.io.ndbc.get_buoy_metadata - ~mhkit.wave.io.ndbc.request_directional_data - ~mhkit.wave.io.ndbc.create_spread_function - ~mhkit.wave.io.ndbc.create_directional_spectrum +^^^^ + +.. automodule:: mhkit.wave.io.ndbc + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~read_file + ~available_data + ~request_data + ~to_datetime_index + ~dates_to_datetime + ~parameter_units + ~request_directional_data + ~create_spread_function + ~create_directional_spectrum + ~get_buoy_metadata SWAN -"""" +^^^^ -.. autosummary:: - :nosignatures: +.. automodule:: mhkit.wave.io.swan + :members: + :undoc-members: + :show-inheritance: - ~mhkit.wave.io.swan.read_table - ~mhkit.wave.io.swan.read_block - ~mhkit.wave.io.swan.dictionary_of_block_to_table - ~mhkit.wave.io.swan.block_to_table + .. autosummary:: + :nosignatures: + ~read_table + ~read_block + ~dictionary_of_block_to_table + ~block_to_table WEC-Sim -""""""" - -.. autosummary:: - :nosignatures: - - ~mhkit.wave.io.wecsim.read_output - -WPTO Hindcast -""""""""""""" +^^^^^^^ +.. automodule:: mhkit.wave.io.wecsim + :members: + :undoc-members: + :show-inheritance: -.. autosummary:: - :nosignatures: + .. autosummary:: + :nosignatures: - ~mhkit.wave.io.hindcast.hindcast.region_selection - ~mhkit.wave.io.hindcast.hindcast.request_wpto_point_data - ~mhkit.wave.io.hindcast.hindcast.request_wpto_directional_spectrum + ~read_output WIND Toolkit Hindcast -""""""""""""""""""""" - -.. autosummary:: - :nosignatures: - - ~mhkit.wave.io.hindcast.wind_toolkit.region_selection - ~mhkit.wave.io.hindcast.wind_toolkit.get_region_data - ~mhkit.wave.io.hindcast.wind_toolkit.plot_region - ~mhkit.wave.io.hindcast.wind_toolkit.elevation_to_string - ~mhkit.wave.io.hindcast.wind_toolkit.request_wtk_point_data - - - - -CDiP Data -++++++++++++ - -.. automodule:: mhkit.wave.io.cdip - :members: - :undoc-members: - :show-inheritance: - +^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: mhkit.wave.io.hindcast.wind_toolkit + :members: + :undoc-members: + :show-inheritance: -NDBC Data -+++++++++ + .. autosummary:: + :nosignatures: -.. automodule:: mhkit.wave.io.ndbc - :members: - :undoc-members: - :show-inheritance: + ~region_selection + ~get_region_data + ~plot_region + ~elevation_to_string + ~request_wtk_point_data -SWAN Data -+++++++++ +WPTO Hindcast +^^^^^^^^^^^^^ -.. automodule:: mhkit.wave.io.swan - :members: - :undoc-members: - :show-inheritance: +.. automodule:: mhkit.wave.io.hindcast.hindcast + :members: + :undoc-members: + :show-inheritance: -WEC-Sim Data -++++++++++++ - -.. automodule:: mhkit.wave.io.wecsim - :members: - :undoc-members: - :show-inheritance: + .. autosummary:: + :nosignatures: -WPTO Hindcast Data -++++++++++++++++++ - -.. automodule:: mhkit.wave.io.hindcast.hindcast - :members: - :undoc-members: - :show-inheritance: - -WIND Toolkit Data -+++++++++++++++++ - -.. automodule:: mhkit.wave.io.hindcast.wind_toolkit - :members: - :undoc-members: - :show-inheritance: + ~region_selection + ~request_wpto_point_data + ~request_wpto_directional_spectrum Resource -"""""""" +-------- The resource submodule contains functions compute wave energy spectra and metrics. -The following functions can be used to compute wave energy spectra: - -.. autosummary:: - :nosignatures: - - ~mhkit.wave.resource.elevation_spectrum - ~mhkit.wave.resource.pierson_moskowitz_spectrum - ~mhkit.wave.resource.jonswap_spectrum - -The following functions can be used to compute wave metrics from spectra: - -.. autosummary:: - :nosignatures: - - ~mhkit.wave.resource.surface_elevation - ~mhkit.wave.resource.frequency_moment - ~mhkit.wave.resource.significant_wave_height - ~mhkit.wave.resource.average_zero_crossing_period - ~mhkit.wave.resource.average_crest_period - ~mhkit.wave.resource.average_wave_period - ~mhkit.wave.resource.peak_period - ~mhkit.wave.resource.energy_period - ~mhkit.wave.resource.spectral_bandwidth - ~mhkit.wave.resource.spectral_width - ~mhkit.wave.resource.energy_flux - ~mhkit.wave.resource.energy_period_to_peak_period - ~mhkit.wave.resource.wave_celerity - ~mhkit.wave.resource.wave_number - ~mhkit.wave.resource.depth_regime - ~mhkit.wave.resource.wave_length - - .. automodule:: mhkit.wave.resource - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + The following functions can be used to compute wave energy spectra: + + .. autosummary:: + :nosignatures: + + ~elevation_spectrum + ~pierson_moskowitz_spectrum + ~jonswap_spectrum + + The following functions can be used to compute wave metrics from spectra: + + .. autosummary:: + :nosignatures: + + ~surface_elevation + ~frequency_moment + ~significant_wave_height + ~average_zero_crossing_period + ~average_crest_period + ~average_wave_period + ~peak_period + ~energy_period + ~spectral_bandwidth + ~spectral_width + ~energy_flux + ~energy_period_to_peak_period + ~wave_celerity + ~wave_length + ~wave_number + ~depth_regime Performance -""""""""""" +----------- The performance submodule contains functions to compute capture length, statistics, performance matrices, and mean annual energy production. -.. autosummary:: - :nosignatures: - - ~mhkit.wave.performance.capture_length - ~mhkit.wave.performance.statistics - ~mhkit.wave.performance.capture_length_matrix - ~mhkit.wave.performance.wave_energy_flux_matrix - ~mhkit.wave.performance.power_matrix - ~mhkit.wave.performance.mean_annual_energy_production_timeseries - ~mhkit.wave.performance.mean_annual_energy_production_matrix - .. automodule:: mhkit.wave.performance - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~capture_length + ~statistics + ~capture_length_matrix + ~wave_energy_flux_matrix + ~power_matrix + ~mean_annual_energy_production_timeseries + ~mean_annual_energy_production_matrix + ~power_performance_workflow .. TODO Add Response amplitude operator .. TODO Add Watch circle Graphics -"""""""" +-------- The graphics submodule contains functions to plot wave data and related metrics. -.. autosummary:: - :nosignatures: - - ~mhkit.wave.graphics.plot_spectrum - ~mhkit.wave.graphics.plot_elevation_timeseries - ~mhkit.wave.graphics.plot_matrix - ~mhkit.wave.graphics.plot_chakrabarti - ~mhkit.wave.graphics.plot_environmental_contour - ~mhkit.wave.graphics.plot_compendium - ~mhkit.wave.graphics.plot_boxplot - ~mhkit.wave.graphics.plot_avg_annual_energy_matrix - ~mhkit.wave.graphics.monthly_cumulative_distribution - .. automodule:: mhkit.wave.graphics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + + .. autosummary:: + :nosignatures: + + ~plot_spectrum + ~plot_elevation_timeseries + ~plot_matrix + ~plot_chakrabarti + ~plot_environmental_contour + ~plot_avg_annual_energy_matrix + ~monthly_cumulative_distribution + ~plot_compendium + ~plot_boxplot + ~plot_directional_spectrum Contours -"""""""" +-------- Contains functions for calculating environmental contours of extreme seastates -.. autosummary:: - :nosignatures: +.. automodule:: mhkit.wave.contours + :members: + :undoc-members: + :show-inheritance: - ~mhkit.wave.contours.environmental_contours - ~mhkit.wave.contours.PCA_contour - ~mhkit.wave.contours.samples_full_seastate - ~mhkit.wave.contours.samples_contour + .. autosummary:: + :nosignatures: -.. automodule:: mhkit.wave.contours - :members: - :undoc-members: - :show-inheritance: + ~environmental_contours + ~PCA_contour + ~samples_full_seastate + ~samples_contour diff --git a/docs/source/mooring.rst b/docs/source/mooring.rst index 52690693..8f39ff85 100644 --- a/docs/source/mooring.rst +++ b/docs/source/mooring.rst @@ -14,10 +14,10 @@ Examples - `Python Mooring Example Notebook `_ +Submodules +-------------- The mooring module contains the following submodules: * ``io``: Loads mooring data from MoorDyn. * ``main``: Computes the lay length of a mooring line over time. * ``graphics``: Generates graphics, mooring line node positions over time. - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the mooring module. diff --git a/docs/source/overview.rst b/docs/source/overview.rst index cecd12e8..5bad4f50 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -80,6 +80,7 @@ The MHKiT-MATLAB repository is located at: https://github.com/MHKiT-Software/MHK .. _tests: + Software Tests -------------------------- @@ -88,16 +89,16 @@ Tests are run each time changes are made to the repository. New tests are developed each time new functionality is added to MHKiT. Tests are run on GitHub Actions and reported on the respective README pages. -GitHub Actions: `Python `_, `MATLAB `_ -README pages: `Python `_, `MATLAB `_ +GitHub Actions: `Python `__, `MATLAB `__ +README pages: `Python `__, `MATLAB `__ Developers should run software tests locally before submitting a pull request, using the following commands. A summary pdf will be created after running the tests summarizing the test results. -MHKiT-Python tests using the Python package nose:: +MHKiT-Python tests using the Python package pytest:: - nosetests -v --with-coverage --cover-package=mhkit mhkit + pytest MHKiT-MATLAB tests using the MATLAB API:: diff --git a/docs/source/power.rst b/docs/source/power.rst index 6ff21c45..d92a7eec 100644 --- a/docs/source/power.rst +++ b/docs/source/power.rst @@ -15,6 +15,8 @@ Examples - `Python Power Example Notebook `_ - `MATLAB Power Example LiveScript `_ +Submodules +-------------- The power module contains the following submodules: * ``characteristics``: Calculates power quantities of interest from voltage and current timseries. @@ -22,8 +24,6 @@ The power module contains the following submodules: Calculations are based on `IEC TS 62600-30:2018 ED1 `_ and `IEC TS 61000-4-7:2008 ED2 `_. -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the power module. - IEC/TS 62600-30 --------------------------- Timeseries of voltage and current are the primary inputs for the power module. diff --git a/docs/source/qc.rst b/docs/source/qc.rst index f83299f3..4303a0d0 100644 --- a/docs/source/qc.rst +++ b/docs/source/qc.rst @@ -21,6 +21,9 @@ Examples - `Python Quality Control Example `_ - `MATLAB Quality Control Example `_ +Submodules +-------------- +The QC module does not contain submodules. It imports several convenient functions from pecos.monitoring. The QC module contains a set of functions for basic quality control analysis. These functions are imported from `Pecos `_, an open-source Python package designed for quality control analysis of time-series data. Pecos was originally developed to monitor solar photovoltaic systems but is designed to be used for a wide range of applications. @@ -59,5 +62,3 @@ See Pandas documentation for more details. Note, that the quality control functions require that the data have a datatime index. Other functionality in MHKiT can use data that has datatime or numeric indexes. The :ref:`utils` can be used to convert numeric indexes to datetime indexes. - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the QC module. diff --git a/docs/source/river.rst b/docs/source/river.rst index c9b09321..2da72bc3 100644 --- a/docs/source/river.rst +++ b/docs/source/river.rst @@ -16,6 +16,8 @@ Examples - `Python Tanana River Resource Characterization `_ - `MATLAB River Example `_ +Submodules +-------------- The river module contains the following submodules: * ``io``: Loads discharge data from standard formats. @@ -25,8 +27,6 @@ The river module contains the following submodules: Calculations are based on `IEC TS 62600-300:2019 ED1 `_. * ``graphics``: Generates graphics, including flow duration curves and velocity duration curves. -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the river module. - IEC/TS 62600-100 --------------------------- Flow discharge at a site is the primary input for the river module. diff --git a/docs/source/tidal.rst b/docs/source/tidal.rst index 3a2b3747..b69a0e4c 100644 --- a/docs/source/tidal.rst +++ b/docs/source/tidal.rst @@ -17,6 +17,8 @@ Examples - `MATLAB Tidal Example LiveScript `_ +Submodules +-------------- The tidal module contains the following submodules: * ``io``: Loads tidal velocity and direction data from National Oceanic and Atmospheric Administration (NOAA) currents. @@ -25,6 +27,3 @@ The tidal module contains the following submodules: * ``performance``: Computes device metrics such as equivalent diameter, tip speed ratio, and capture area. Calculations are based on `IEC TS 62600-200:2013 ED1 `_. * ``graphics``: Generates graphics, including rose plots and joint probability distributions. - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the tidal module. - diff --git a/docs/source/utils.rst b/docs/source/utils.rst index 158f9e8d..e5e83a36 100644 --- a/docs/source/utils.rst +++ b/docs/source/utils.rst @@ -2,18 +2,12 @@ Utils Module ==================== -The utils module contains helper functions. +The MHKiT-Python utils Module contains a single function to help users +convert numeric indexes to datetime indexes. Additional helper functions could be added at a later date. + +The mhkit_python_utils module is used by MHKiT-MATLAB to convert MATLAB data types into Pandas DataFrames. API Documentation -------------------- - `Python Utils API Documentation `_ - `MATLAB Utils API Documentation `_ - - -The MHKiT-Python utils module contains a single function to help users -convert numeric indexes to datetime indexes. Additional helper functions could be added at a later date. - -The mhkit_python_utils module is used by MHKiT-MATLAB to convert MATLAB data types into Pandas DataFrames. - - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the utils module. diff --git a/docs/source/wave.rst b/docs/source/wave.rst index 0045334a..b01c667c 100644 --- a/docs/source/wave.rst +++ b/docs/source/wave.rst @@ -15,6 +15,8 @@ Examples - `Wave Examples List `_ +Submodules +-------------- The wave module contains the following submodules: * ``io``: Loads wave elevation and spectra data from standard formats including WEC-Sim, SWAN, WPTO hindcast, CDiP, and NDBC data. @@ -24,5 +26,3 @@ The wave module contains the following submodules: Calculations are based on `IEC TS 62600-100:2012 ED1 `_. * ``graphics``: Generates graphics, including elevation time-series, spectra, and scatter diagrams. * ``contours``: Calculates envoronmental contours of extreme seastates. - -See :ref:`MHKiT-Python ` or :ref:`MHKiT-MATLAB ` for more details on the wave module. diff --git a/docs/source/webinars.rst b/docs/source/webinars.rst index 18ec9b3f..ba0827ca 100644 --- a/docs/source/webinars.rst +++ b/docs/source/webinars.rst @@ -16,8 +16,6 @@ The MHKiT-Python webinar held on 10 February 2021 covered MHKiT-Python v0.3.1 an
-| -| The MHKiT-Python webinar held on 31 March 2022 covered MHKiT-Python v0.5.0 and featured demonstrations of the DOLfYN and WDRT modules. @@ -28,9 +26,6 @@ The MHKiT-Python webinar held on 31 March 2022 covered MHKiT-Python v0.5.0 and f -| -| - MHKiT-MATLAB ------------- @@ -43,4 +38,3 @@ The MHKiT-Matlab webinar held on February 18th covered MHKiT-Matlab v0.3.1 and f -