Source code for pypilecore.common.piles.geometry.components.common

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any, Dict, Literal, Tuple

import numpy as np
from matplotlib import pyplot as plt
from matplotlib.axes import Axes
from numpy.typing import NDArray


def get_component_bounds_nap(
    pile_tip_level_nap: float | int,
    pile_head_level_nap: float | int,
    component_primary_length: float | int | None,
) -> Tuple[float, float]:
    """
    Returns component head and tip level in NAP.

    Parameters
    ----------
    pile_tip_level_nap : float
        pile tip level in [m] w.r.t. NAP.
    pile_head_level_nap : float
        pile head level in [m] w.r.t. NAP.
    component_primary_length : float, optional
        The length of the pile-geometry component.

    Returns
    -------
    tuple
        Tuple with component head and tip level in [m] w.r.t. NAP.
    """
    # Component tip level is always the pile tip level
    component_tip_level_nap = pile_tip_level_nap

    # Component head level is the pile head level if the length is not set
    if component_primary_length is not None:
        component_head_level_nap = pile_tip_level_nap + component_primary_length
    else:
        component_head_level_nap = pile_head_level_nap

    return float(component_head_level_nap), float(component_tip_level_nap)


def get_circum_vs_depth(
    depth_nap: NDArray[np.floating],
    pile_tip_level_nap: float | int,
    pile_head_level_nap: float | int,
    length: float | None,
    circumference: float,
) -> NDArray[np.floating]:
    """
    Returns component circumferences at requested depths.

    Parameters
    ----------
    depth_nap : np.array
        Array with depths in [m] w.r.t. NAP.
    pile_tip_level_nap : float
        pile tip level in [m] w.r.t. NAP.
    pile_head_level_nap : float
        pile head level in [m] w.r.t. NAP.
    length : float, optional
        The length of the pile-geometry component, by default None.
    circumference : float
        The circumference of the pile-geometry component.

    Returns
    -------
    np.array
        Array with component circumferences at the depths in the depth parameter.
    """
    circum_vs_depth = np.zeros_like(depth_nap)

    # Component tip level is always the pile tip level
    component_tip_level_nap = pile_tip_level_nap

    # Component head level is the pile head level if the length is not set
    if length is not None:
        component_head_level_nap = pile_tip_level_nap + length
    else:
        component_head_level_nap = pile_head_level_nap

    # Fill the circumference between component tip and head level
    circum_vs_depth[
        (depth_nap <= component_head_level_nap) & (depth_nap >= component_tip_level_nap)
    ] = circumference

    return circum_vs_depth


def get_area_vs_depth(
    depth_nap: NDArray[np.floating],
    area_full: float | int,
    component_head_level_nap: float | int,
    component_tip_level_nap: float | int,
    inner_area: NDArray[np.floating],
) -> NDArray[np.floating]:
    """
    Returns component areas at requested depths.

    Parameters
    ----------
    depth_nap : np.array
        Array with depths in [m] w.r.t. NAP.
    area_full : float
        The full outer-area [m²] of the pile-geometry component, including any potential inner-components.
    pile_tip_level_nap : float
        pile tip level in [m] w.r.t. NAP.
    pile_head_level_nap : float
        pile head level in [m] w.r.t. NAP.
    component_head_level_nap : float
        Component head level in [m] w.r.t. NAP.
    component_tip_level_nap : float
        Component tip level in [m] w.r.t. NAP.
    inner_area : np.array
        Array with inner areas at the depths in the depth parameter.

    Returns
    -------
    np.array
        Array with component areas at the depths in the depth parameter.
    """
    area_vs_depth = np.zeros_like(depth_nap, dtype=np.floating)

    # Mask the depths between the component tip and head level
    mask_depths = (depth_nap <= component_head_level_nap) & (
        depth_nap >= component_tip_level_nap
    )

    # Fill the area between component tip and head level, subtracting the inner area
    area_vs_depth[mask_depths] = float(area_full) - inner_area[mask_depths]

    return area_vs_depth


def instantiate_axes(
    figsize: Tuple[float, float] = (6.0, 6.0),
    axes: Axes | None = None,
    **kwargs: Any,
) -> Axes:
    """
    Validate axes objects if provided, otherwise create a new axes object.

    Parameters
    ----------
    figsize : tuple, optional
        The figure size (width, height) in inches, by default (6.0, 6.0).
    axes : Axes, optional
        The axes object to plot the cross-section on.
    **kwargs
        Additional keyword arguments to pass to the `plt.subplots()` function.

    Returns
    -------
    Axes
        The axes object to plot the cross-section on.
    """
    # Create axes objects if not provided
    if axes is not None:
        if not isinstance(axes, Axes):
            raise ValueError(
                "'axes' argument must be a `pyplot.axes.Axes` object or None."
            )

    else:
        kwargs_subplot = {
            "figsize": figsize,
            "tight_layout": True,
        }

        kwargs_subplot.update(kwargs)

        _, axes = plt.subplots(
            1,
            1,
            **kwargs_subplot,
        )

        if not isinstance(axes, Axes):
            raise ValueError(
                "Could not create Axes objects. This is probably due to invalid matplotlib keyword arguments. "
            )

    return axes


[docs]class _BasePileGeometryComponent(ABC): """ The _BasePileGeometryComponent class is an abstract base class for pile-geometry components. """
[docs] @classmethod @abstractmethod def from_api_response( cls, component: dict, inner_component: _BasePileGeometryComponent | None = None, ) -> _BasePileGeometryComponent: """ Instantiates a pile-geometry component from a component object in the API response payload. Parameters: ----------- component: dict A dictionary that is retrieved from the API response payload at "/pile_properties/geometry/components/[i]". inner_component: _BasePileGeometryComponent | None, optional The component on the inside of the pile-geometry component, by default None. Returns: -------- _BasePileGeometryComponent A pile-geometry component. """ ...
@property @abstractmethod def inner_component( self, ) -> _BasePileGeometryComponent | None: """The component on the inside of the pile-geometry component""" ... @property @abstractmethod def outer_shape(self) -> str: """The outer shape of the pile-geometry component""" ... @property @abstractmethod def material(self) -> str | None: """The material name of the pile-geometry component""" ... @property @abstractmethod def primary_dimension(self) -> PrimaryPileComponentDimension: """ The primary dimension [m] of the pile-geometry component, which is measured along the primary axis of the pile. """ ... @property @abstractmethod def circumference(self) -> float: """The outer-circumference [m] of the pile-geometry component""" ... @property @abstractmethod def equiv_tip_diameter(self) -> float: """ Equivalent outer-diameter [m] of the component at the tip-level. """ ... @property @abstractmethod def area_full(self) -> float: """The full outer-area [m²] of the pile-geometry component, including any potential inner-components""" ...
[docs] @abstractmethod def serialize_payload(self) -> dict: """ Serialize the pile-geometry component to a dictionary payload for the API. Returns: A dictionary payload containing the geometry properties. """
[docs] @abstractmethod def get_component_bounds_nap( self, pile_tip_level_nap: float | int, pile_head_level_nap: float | int, ) -> Tuple[float, float]: """ Returns component head and tip level in NAP. Parameters ---------- pile_tip_level_nap : float pile tip level in [m] w.r.t. NAP. pile_head_level_nap : float pile head level in [m] w.r.t. NAP. Returns ------- tuple Tuple with component head and tip level in [m] w.r.t. NAP. """ ...
[docs] @abstractmethod def get_circum_vs_depth( self, depth_nap: NDArray[np.floating], pile_tip_level_nap: float | int, pile_head_level_nap: float | int, ) -> NDArray[np.floating]: """ Returns component circumferences at requested depths. Parameters ---------- depth_nap : np.array Array with depths in [m] w.r.t. NAP. pile_tip_level_nap : float pile tip level in [m] w.r.t. NAP. pile_head_level_nap : float pile head level in [m] w.r.t. NAP. Returns ------- np.array Array with component circumferences at the depths in the depth parameter. """ ...
[docs] @abstractmethod def get_inner_area_vs_depth( self, depth_nap: NDArray[np.floating], pile_tip_level_nap: float | int, pile_head_level_nap: float | int, ) -> NDArray[np.floating]: """ Returns inner component areas at requested depths. Parameters ---------- depth_nap : np.array Array with depths in [m] w.r.t. NAP. pile_tip_level_nap : float pile tip level in [m] w.r.t. NAP. pile_head_level_nap : float pile head level in [m] w.r.t. NAP. Returns ------- np.array Array with inner component areas at the depths in the depth parameter. """ ...
[docs] @abstractmethod def get_area_vs_depth( self, depth_nap: NDArray[np.floating], pile_tip_level_nap: float | int, pile_head_level_nap: float | int, ) -> NDArray[np.floating]: """ Returns component areas at requested depths. Parameters ---------- depth_nap : np.array Array with depths in [m] w.r.t. NAP. pile_tip_level_nap : float pile tip level in [m] w.r.t. NAP. pile_head_level_nap : float pile head level in [m] w.r.t. NAP. Returns ------- np.array Array with component areas at the depths in the depth parameter. """ ...
[docs] @abstractmethod def plot_cross_section_exterior( self, figsize: Tuple[float, float] = (6.0, 6.0), facecolor: Tuple[float, float, float] | str | None = None, axes: Axes | None = None, axis_arg: bool | str | Tuple[float, float, float, float] | None = "auto", show: bool = True, **kwargs: Any, ) -> Axes: """ Plot the cross-section of the component at a specified depth. Parameters ---------- figsize : tuple, optional The figure size (width, height) in inches, by default (6.0, 6.0). facecolor : tuple or str, optional The face color of the cross-section, by default None. axes : Axes The axes object to plot the cross-section on. axis_arg : bool or str or tuple, optional The axis argument to pass to the `axes.axis()` function, by default "auto". show : bool, optional Whether to display the plot, by default True. Returns ------- Axes The axes object to plot the cross-section on. """ ...
[docs] @abstractmethod def plot_side_view( self, bottom_boundary_nap: float | Literal["pile_tip"] = "pile_tip", top_boundary_nap: float | Literal["pile_head"] = "pile_head", pile_tip_level_nap: float | int = -10, pile_head_level_nap: float | int = 0, figsize: Tuple[float, float] = (6.0, 6.0), facecolor: Tuple[float, float, float] | str | None = None, axes: Axes | None = None, axis_arg: bool | str | Tuple[float, float, float, float] | None = "scaled", show: bool = True, **kwargs: Any, ) -> Axes: """ Plot the side view of the cross-section at a specified depth. Parameters ---------- figsize : tuple, optional The figure size (width, height) in inches, by default (6.0, 6.0). facecolor : tuple or str, optional The face color of the pile cross-section, by default None. axes : Axes The axes object to plot the cross-section on. axis_arg : bool or str or tuple, optional The axis argument to pass to the `axes.axis()` function, by default "auto". show : bool, optional Whether to display the plot, by default True. **kwargs Additional keyword arguments to pass to the `plt """ ...
[docs]class PrimaryPileComponentDimension: """ The PrimaryPileComponentDimension class represents the primary dimension of a pile-geometry component, which is measured along the primary axis of the pile. It contains the length, top level, and bottom level of the pile-geometry component. """ def __init__( self, length: float | None = None, ): """ Represents the primary dimension of a pile-geometry component, which is measured along the primary axis of the pile. Args: length: The length [m] of the pile-geometry component (along the primary axis). """ self._length = length
[docs] @classmethod def from_api_response(cls, primary_dim: dict) -> PrimaryPileComponentDimension: """ Instantiates a PrimaryPileComponentDimension from a primary dimension object in the API response payload. Args: primary_dim: A dictionary that is retrieved from the API response payload at "/pile_properties/geometry/components/[i]/primary_dimension". """ return cls( length=primary_dim.get("length"), )
@property def length(self) -> float | None: """The length [m] of the pile-geometry component""" return self._length
[docs] def serialize_payload(self) -> Dict[str, float | None] | None: """ Serialize the primary dimension to a dictionary payload for the API. Only contains the length, since this is the only accepted value by the API. Returns None if the length is not set. Returns: A dictionary payload containing the length of the primary dimension. """ if self.length is not None: return {"length": self.length} return None