diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index c0795e4..99b3363 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -14,6 +14,6 @@ jobs: - uses: actions/setup-python@v5 with: python-version: 3.x - - run: pip install mkdocs mkdocs mkdocstrings[python] + - run: pip install mkdocs mkdocstrings[python] mkdocs-material - run: mkdocs gh-deploy --force --clean --verbose diff --git a/docs/api_reference.md b/docs/api_reference.md index 0530634..12aff33 100644 --- a/docs/api_reference.md +++ b/docs/api_reference.md @@ -24,9 +24,8 @@ Additional reference models may be defined in the future and can be added to the ::: echosms.ReferenceModels - -## BenchMarkData -::: echosms.BenchMarkData +## BenchmarkData +::: echosms.BenchmarkData ## Utilities diff --git a/docs/echoSMs_logo.png b/docs/echoSMs_logo.png new file mode 100644 index 0000000..edc0ecd Binary files /dev/null and b/docs/echoSMs_logo.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 2eb0e8c..2f7336e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,19 @@ nav: - Benchmarks: benchmark_data.md - API Reference: api_reference.md -theme: readthedocs +theme: + name: material + logo: echoSMs_logo.png + favicon: echoSMs_logo.png + icon: + repo: fontawesome/brands/github + features: + - navigation.top + - toc.integrate + - content.action.view + +repo_url: https://github.com/ices-tools-dev/echoSMs +edit_uri: edit/main/docs/ plugins: - search @@ -22,5 +34,7 @@ plugins: inherited_members: true show_root_heading: false show_root_toc_entry: false - show_source: false + show_source: true heading_level: 3 + filters: + - "!^_" diff --git a/src/echosms/__init__.py b/src/echosms/__init__.py index bd25701..214fbcf 100644 --- a/src/echosms/__init__.py +++ b/src/echosms/__init__.py @@ -1,11 +1,11 @@ """Setup the public API for echoSMs.""" from .utils import k, eta, h1, df_from_dict, da_from_dict from .scattermodelbase import ScatterModelBase -from .benchmarkdata import BenchMarkData +from .benchmarkdata import BenchmarkData from .referencemodels import ReferenceModels from .mssmodel import MSSModel from .psmsmodel import PSMSModel from .dcmmodel import DCMModel -__all__ = ['ScatterModelBase', 'BenchMarkData', 'ReferenceModels', 'MSSModel', 'PSMSModel', +__all__ = ['ScatterModelBase', 'BenchmarkData', 'ReferenceModels', 'MSSModel', 'PSMSModel', 'DCMModel', 'k', 'eta', 'h1', 'da_from_dict', 'df_from_dict'] diff --git a/src/echosms/benchmarkdata.py b/src/echosms/benchmarkdata.py index d31c1a8..244d5ef 100644 --- a/src/echosms/benchmarkdata.py +++ b/src/echosms/benchmarkdata.py @@ -4,7 +4,7 @@ import pandas as pd -class BenchMarkData: +class BenchmarkData: """Convenient interface to the benchmark dataset. This dataset contains the TS values from Jech et al., 2015. diff --git a/src/echosms/dcmmodel.py b/src/echosms/dcmmodel.py index 9d97673..26cd52b 100644 --- a/src/echosms/dcmmodel.py +++ b/src/echosms/dcmmodel.py @@ -55,7 +55,8 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type, Returns ------- - ts : the target strength (re 1 m²) of the target [dB]. + : float + The target strength (re 1 m²) of the target [dB]. Notes ----- diff --git a/src/echosms/mssmodel.py b/src/echosms/mssmodel.py index 2798a92..dd80efc 100644 --- a/src/echosms/mssmodel.py +++ b/src/echosms/mssmodel.py @@ -12,8 +12,8 @@ class MSSModel(ScatterModelBase): """Modal series solution (MSS) scattering model. - This class contains methods to calculate acoustic scatter from spheres and shells with various - boundary conditions. + This class calculates acoustic scatter from spheres and shells with various + boundary conditions, as listed in the ``model_types`` class attribute. """ def __init__(self): @@ -67,7 +67,7 @@ def calculate_ts_single(self, medium_c, medium_rho, a, theta, f, model_type, Returns ------- - : + : float The target strength (re 1 m²) of the target [dB]. Notes diff --git a/src/echosms/psmsmodel.py b/src/echosms/psmsmodel.py index 8545d21..704b357 100644 --- a/src/echosms/psmsmodel.py +++ b/src/echosms/psmsmodel.py @@ -50,7 +50,8 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type, Returns ------- - ts : the target strength (re 1 m²) of the target [dB]. + : float + The target strength (re 1 m²) of the target [dB]. Notes ----- diff --git a/src/echosms/scattermodelbase.py b/src/echosms/scattermodelbase.py index eb76e7b..c43d925 100644 --- a/src/echosms/scattermodelbase.py +++ b/src/echosms/scattermodelbase.py @@ -11,16 +11,24 @@ class ScatterModelBase(abc.ABC): """Base class for a class that provides a scattering model. All scattering models should inherit from this class, have a name that - ends with 'Model', and provide __init__() and calculate_ts_single() functions. + ends with 'Model', and provide initialisation and calculate_ts_single() functions. Attributes ---------- - long_name : string - short_name : string - analytical_type : string - model_types : - shapes : - max_ka : + long_name : str + The long name of the model. + short_name : str + A short version of the model's long name, typically an ancronym. + analytical_type : str + Whether the model implements an ``exact`` or an ``approximate`` model. + model_types : list of str + The types of boundary conditions that the model provides. + shapes : list of str + The shapes that the model can represent. + max_ka : float + An approximate maximum ka value that will result in accurate target strength results. Note + that ka is often not the only parameter that determines the accuracy of the model (e.g., + aspect ratio and incident angle can also affect the accuracy). """ diff --git a/src/echosms/utils.py b/src/echosms/utils.py index e9916f2..fc6a26d 100644 --- a/src/echosms/utils.py +++ b/src/echosms/utils.py @@ -84,8 +84,8 @@ def k(c: float, f: float) -> float: Returns ------- - k : scalar or array_like - The acoustic wavenumber [m$^{-1}$]. + : + The acoustic wavenumber [m⁻¹]. """ return 2*np.pi*f/c @@ -96,7 +96,7 @@ def h1(n: int, z: float, derivative=False) -> complex: Parameters ---------- n : - Order (n >= 0). + Order (n ≥ 0). z : Argument of the Hankel function. derivative : @@ -107,6 +107,11 @@ def h1(n: int, z: float, derivative=False) -> complex: : Value of the spherical Hankel function + Raises + ------ + ValueError + For negative n values. + Notes ----- The value of the Hankel function is calculated from spherical Bessel functions [1]. diff --git a/src/example_code.py b/src/example_code.py index 2b74a1d..abff6fc 100644 --- a/src/example_code.py +++ b/src/example_code.py @@ -4,7 +4,7 @@ import numpy as np from echosms import MSSModel, PSMSModel, DCMModel -from echosms import BenchMarkData +from echosms import BenchmarkData from echosms import ReferenceModels from echosms import df_from_dict, da_from_dict @@ -15,7 +15,7 @@ print('\t' + n) # Load the benchmark data (from Jech et al., 2015) -bm = BenchMarkData() +bm = BenchmarkData() bmf = bm.dataset_freq() bm_theta = bm.dataset_angle()