femethods 0.1.7a2__py3-none-any.whl → 0.1.8__py3-none-any.whl

femethods/__init__.py

@@ -1,5 +1,8 @@
-__name__ = "femethods"
-__version__ = "0.1.7a2"
-__author__ = "Joseph Contreras Jr."
-__license__ = "MIT"
-__copyright__ = "Copyright 2020 Joseph Contreras Jr."
+# pylint: disable=missing-module-docstring
+# pylint: disable=F
+# flake8: noqa
+
+
+from .mesh import Mesh
+
+__version__ = "0.1.8"

femethods/core/__init__.py

@@ -0,0 +1,4 @@
+# pylint: disable=F
+# flake8: noqa
+
+from .force import Force

femethods/mesh.py

@@ -1,101 +1,245 @@
-"""
-Mesh module that will define the mesh.
-"""
-
-from typing import List, Sequence, TYPE_CHECKING
-
-if TYPE_CHECKING:  # pragma: no cover
-    from femethods.reactions import Reaction  # noqa: F401 (unused import)
-    from femethods.loads import Load  # noqa: F401 (unused import)
-
-
-class Mesh(object):
-    """define a mesh that will handle degrees-of-freedom (dof), element lengths
-    etc.
-
-    the input degree-of-freedom (dof) parameter is the degrees-of-freedom for
-    a single element
-    """
-
-    def __init__(
-        self,
-        length: float,
-        loads: List["Load"],
-        reactions: List["Reaction"],
-        dof: int,
-    ):
-        self._nodes = self.__get_nodes(length, loads, reactions)
-        self._lengths = self.__get_lengths()
-        self._num_elements = len(self.lengths)
-        self._dof = dof * self.num_elements + dof
-
-    @property
-    def nodes(self) -> Sequence[float]:
-        return self._nodes
-
-    @property
-    def dof(self) -> int:
-        """
-        Degrees of freedom of the entire beam
-
-        Returns:
-            :obj:`int`: Read-only. Number of degrees of freedom of the beam
-        """
-        return self._dof
-
-    @property
-    def lengths(self) -> List[float]:
-        """
-        List of lengths of mesh elements
-
-        Returns:
-            :obj:`list`: Read-only. List of lengths of local mesh elements
-        """
-        return self._lengths
-
-    @property
-    def num_elements(self) -> int:
-        """
-        Number of mesh elements
-
-        Returns:
-            :obj:`int`: Read-only. Number of elements in mesh
-
-        """
-
-        return self._num_elements
-
-    def __get_lengths(self) -> List[float]:
-        # Calculate the lengths of each element
-        lengths: List[float] = []
-        for k in range(len(self.nodes) - 1):
-            lengths.append(self.nodes[k + 1] - self.nodes[k])
-        return lengths
-
-    @staticmethod
-    def __get_nodes(
-        length: float, loads: List["Load"], reactions: List["Reaction"]
-    ) -> Sequence[float]:
-        nodes: List[float] = [0]  # ensure first node is always at zero (0)
-
-        # Ignore the type checking for the for loop adding lists of loads and
-        # lists of reactions. There is no + operator defined for these, but it
-        # will combine the lists using the built in list addition. Which is the
-        # desired behavior
-        # noinspection PyTypeChecker,Mypy
-        for item in loads + reactions:  # type: ignore
-            nodes.append(item.location)
-        nodes.append(length)  # ensure last node is at the end of the beam
-        nodes = list(set(nodes))  # remove duplicates
-        nodes.sort()
-        return nodes
-
-    def __str__(self) -> str:
-        s = (
-            "MESH PARAMETERS\n"
-            f"Number of elements: {self.num_elements}\n"
-            f"Node locations: {self.nodes}\n"
-            f"Element Lengths: {self.lengths}\n"
-            f"Total degrees of freedom: {self.dof}\n"
-        )
-        return s
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+
+from . import validation
+
+
+class Mesh:
+    """
+    Mesh to handle degrees-of-freedom (dof) and element lengths
+
+    Parameters
+    ----------
+        length : float
+            overall length of structure
+        locations : sequence
+            locations of nodes (loads and reactions)
+        node_dof : int
+            degrees-of-freedom for a single node
+        max_element_length : float | None
+            maximum allowed length of mesh element
+        min_element_count : int | None
+            minimum required number of elements
+
+    .. versionchanged:: 0.1.8a1 renamed :obj:`dof` parameter to :obj:`node_dof`
+    """
+
+    def __init__(
+        self,
+        length: float,
+        locations: npt.NDArray[np.float64],
+        node_dof: int,
+        *,
+        max_element_length: Optional[float] = None,
+        min_element_count: Optional[int] = None,
+    ) -> None:
+        self.length = length
+        self.locations = locations
+        self.node_dof = node_dof
+
+        self.__lengths: npt.NDArray[np.float64] | None = (
+            None  # this will be lazy calculated on-demand
+        )
+
+        self.max_element_length = max_element_length
+        self.min_element_count = min_element_count
+
+    @property
+    def node_dof(self) -> int:
+        """
+        degrees of freedom for a single node
+
+        Raises
+        ------
+            TypeError: when not a number
+            ValueError: when not a positive integer
+        """
+        return self.__node_dof
+
+    @node_dof.setter
+    @validation.is_numeric
+    @validation.positive
+    def node_dof(self, value: int, /) -> None:
+        if value != int(value):
+            raise ValueError(f"node_dof must be an integer, not {value}")
+        self.__node_dof = value
+
+    @property
+    def max_element_length(self) -> Optional[float]:
+        """
+        maximum allowed length of mesh element
+
+        Returns
+        -------
+        float: maximum allowed length of mesh element
+        """
+        return self.__max_element_length
+
+    @max_element_length.setter
+    def max_element_length(self, value: Optional[float]) -> None:
+        if value is None:
+            self.__max_element_length = None
+            return
+
+        if not isinstance(value, (int, float)):
+            raise TypeError(f"max_element_length must be a number, not {value}")
+        if value <= 0:
+            raise ValueError(
+                f"max_element_length must be a positive number, not {value}"
+            )
+        self.__max_element_length = value
+
+    @property
+    def min_element_count(self) -> Optional[int]:
+        """
+        Minimum required number of elements.
+
+        Returns
+        -------
+        int | None
+            minimum required number of elements
+        """
+        return self.__min_element_count
+
+    @min_element_count.setter
+    def min_element_count(self, value: Optional[int]) -> None:
+        if value is None:
+            self.__min_element_count = None
+            return
+
+        if not isinstance(value, int):
+            raise TypeError(f"min_element_count must be a number, not {value}")
+        if value <= 0:
+            raise ValueError(
+                f"min_element_count must be a positive number, not {value}"
+            )
+        self.__min_element_count = value
+
+    def __max_length_nodes(
+        self, required_nodes: npt.NDArray[np.float64]
+    ) -> npt.NDArray[np.float64]:
+        """
+        get node locations when the max length of an element is specified
+        """
+
+        if self.__max_element_length is None:  # pragma: no cover
+            return required_nodes
+
+        # there is a requirements on the max length of elements. Create a copy of the
+        # nodes to be manipulated
+        nodes = np.copy(required_nodes)
+
+        # continually iterate over nodes until all elements have a length that is
+        # less than the max allowed
+        lengths = np.diff(nodes)
+        while self.__max_element_length < np.max(lengths):
+            # there is a node that is longer than allowed
+            for node, length in zip(nodes[:-1], lengths):
+                if not self.__max_element_length < length:
+                    # current element is not longer than the allowed, no changes
+                    # required
+                    continue
+                # current element is too long, split it in half
+                nodes = np.append(nodes, node + length / 2)
+
+            # all nodes that were longer than allowed, have been split in half.
+            # recalculate node locations
+            nodes = np.unique(nodes)
+            nodes = np.sort(nodes)
+
+            # update lengths variable, this is required for the exit condition of
+            # the while loop that guarantees all elements end up shorter than the
+            # maximum allowed length
+            lengths = np.diff(nodes)
+        return nodes
+
+    def __min_count_nodes(
+        self, required_nodes: npt.NDArray[np.float64]
+    ) -> npt.NDArray[np.float64]:
+        """get node locations when min number of elements are specified"""
+
+        if self.__min_element_count is None:  # pragma: no cover
+            return required_nodes
+
+        # there is a requirements on the number of elements. Create a copy of the
+        # nodes to be manipulated
+        nodes = np.copy(required_nodes)
+
+        # there is a limit on the minimum number of elements that must be used
+        while self.__min_element_count > np.size(nodes) - 1:
+            # there are not enough elements. Split the largest element in half
+            lengths = np.diff(nodes)
+            max_length = np.max(lengths)
+            for node, length in zip(nodes[:-1], lengths):  # pragma: no branch
+                if length == max_length:
+                    nodes = np.append(nodes, node + length / 2)
+                    nodes = np.unique(nodes)
+                    nodes = np.sort(nodes)
+
+                    # this condition focuses on the NUMBER of elements, not the
+                    # length. Therefore, only break the first element that equals
+                    # the longest. Even if multiple elements have the max length,
+                    # only the first one is split
+                    break
+        return nodes
+
+    @property
+    def nodes(self) -> npt.NDArray[np.float64]:
+        """location of nodes"""
+        # create set of locations of each load and reaction, and the ends of the beam.
+        # ensure first node is always at zero (0) (start of beam)
+        nodes__ = np.array([0, self.length])
+        nodes__ = np.append(nodes__, self.locations, axis=0)
+        nodes__ = np.unique(nodes__)
+        nodes__ = np.sort(nodes__)
+
+        if self.__max_element_length is not None:
+            # there is a maximum limit on the length of the elements.
+            nodes__ = self.__max_length_nodes(required_nodes=nodes__)
+        if self.__min_element_count is not None:
+            # there is a limit on the minimum number of elements that must be used
+            nodes__ = self.__min_count_nodes(required_nodes=nodes__)
+
+        return nodes__
+
+    @property
+    def dof(self) -> int:
+        """
+        Degrees of freedom of the entire beam
+
+        Returns
+        -------
+        int
+            Read-only. Number of degrees of freedom of the beam
+        """
+        return self.node_dof * len(self.nodes)
+
+    @property
+    def lengths(self) -> npt.NDArray[np.float64]:
+        """
+        List of lengths of mesh elements
+
+        Returns
+        -------
+        array_like
+            Read-only. List of lengths of local mesh elements
+        """
+        if self.__lengths is not None:  # pragma: no cover
+            return self.__lengths
+
+        # the lengths have not been calculated yet. Calculate the lengths of each
+        # element
+        self.__lengths = np.diff(self.nodes)
+        return self.__lengths
+
+    def __str__(self) -> str:
+        mesh_string = (
+            "MESH PARAMETERS\n"
+            f"Number of elements: {len(self.lengths)}\n"
+            f"Node locations: {self.nodes}\n"
+            f"Element Lengths: {self.lengths}\n"
+            f"Total degrees of freedom: {self.dof}\n"
+        )
+        return mesh_string

femethods/validation.py

@@ -0,0 +1,104 @@
+"""
+Misc validation decorators that are used for validation of class properties
+"""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable, Concatenate, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# value type: allow int-only OR float-only (and preserve it)
+N = TypeVar("N", int, float)
+
+# Assumes decorated function is called like: func(self, value, *args, **kwargs)
+ValidatedFunc = Callable[Concatenate[Any, N, P], R]
+
+
+def is_numeric(func: ValidatedFunc[N, P, R]) -> ValidatedFunc[N, P, R]:
+    """
+    Validate property is numeric
+
+    Raises:
+        TypeError: when input value is non-numeric
+    """
+
+    @wraps(func)
+    def wrapper(self: Any, value: N, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        if not isinstance(value, (int, float)):
+            raise TypeError(f"{func.__name__} must be a number, not {value}")
+        return func(self, value, *args, **kwargs)
+
+    return wrapper
+
+
+def positive(func: ValidatedFunc[N, P, R]) -> ValidatedFunc[N, P, R]:
+    """
+    Validate property is positive (excluding ``0``)
+
+    Raises:
+        ValueError: when input value is negative or ``0``
+    """
+
+    @wraps(func)
+    def wrapper(self: Any, value: N, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        if value <= 0:
+            raise ValueError(f"{func.__name__} must be a positive number, not {value}")
+        return func(self, value, *args, **kwargs)
+
+    return wrapper
+
+
+def non_positive(func: ValidatedFunc[N, P, R]) -> ValidatedFunc[N, P, R]:
+    """
+    Validate property is non_positive (negative or ``0``)
+
+    Raises:
+        ValueError: when value is positive
+    """
+
+    @wraps(func)
+    def wrapper(self: Any, value: N, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        if value > 0:
+            raise ValueError(f"{func.__name__} must be a negative or 0, not {value}")
+        return func(self, value, *args, **kwargs)
+
+    return wrapper
+
+
+def negative(func: ValidatedFunc[N, P, R]) -> ValidatedFunc[N, P, R]:
+    """
+    Validate property is negative (excluding ``0``)
+
+    Raises:
+        ValueError: when value is ``0`` or positive
+    """
+
+    @wraps(func)
+    def wrapper(self: Any, value: N, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        if value >= 0:
+            raise ValueError(f"{func.__name__} must be a negative number, not {value}")
+        return func(self, value, *args, **kwargs)
+
+    return wrapper
+
+
+def non_negative(func: ValidatedFunc[N, P, R]) -> ValidatedFunc[N, P, R]:
+    """
+    Validate property is non_negative (must be ``0`` or positive)
+
+    Raises:
+        ValueError: when value is negative
+    """
+
+    @wraps(func)
+    def wrapper(self: Any, value: N, /, *args: P.args, **kwargs: P.kwargs) -> R:
+        if value < 0:
+            raise ValueError(
+                f"{func.__name__} must be a positive or 0 number, not {value}"
+            )
+        return func(self, value, *args, **kwargs)
+
+    return wrapper