cabledyn 0.3.0__py3-none-win_amd64.whl

cabledyn/__init__.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Python interfaces for the CableDyn cable and mooring dynamics solver.
+
+The standalone-driver API works with the statically linked release executable.
+The in-process :class:`CableDyn` class, and the ``abi_version``, ``abi_minor``,
+``library_path``, and ``version_string`` helpers, load the CableDyn shared
+library on first access. They are deliberately left out of ``__all__`` so that
+``from cabledyn import *`` works in installations without the shared library.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cabledyn.animation import Recorder, Seabed, Snapshots, WaterSurface, animate
+from cabledyn.builder import DeckModel, DeckReferenceError, SyropeEA
+from cabledyn.checks import (
+    API_RP_2SK_SAFETY_FACTORS,
+    DNV_OS_E301_PARTIAL_FACTORS,
+    DNV_OS_E301_STRENGTH_FACTOR,
+    BendCheck,
+    BendLimits,
+    TensionCheck,
+    bend_check,
+    mbr_utilisation,
+    tension_check,
+)
+from cabledyn.clearance import (
+    Bathymetry,
+    ClearanceMatrix,
+    LineClearance,
+    SeabedClearance,
+    clearance_matrix,
+    line_clearance,
+    read_bathymetry,
+    seabed_clearance,
+    segment_distance,
+)
+from cabledyn.compare import ChannelComparison, HistoryComparison, compare_histories
+from cabledyn.curves import (
+    FatigueCurve,
+    api_rp_2sk_curve,
+    chain_nominal_area,
+    dnv_os_e301_curve,
+    dnv_rp_c203_curve,
+)
+from cabledyn.damage import (
+    ChannelDamage,
+    DamageProfile,
+    LifetimeFatigue,
+    SeaStateDamage,
+    cable_stress,
+    channel_damage,
+    damage_along_arc,
+    lifetime_fatigue,
+    miner_damage,
+    study_sea_state_damage,
+)
+from cabledyn.deck import DeckWriter
+from cabledyn.deck_file import DeckFile, GeneratedCase, generate_deck_cases
+from cabledyn.driver import (
+    CableDynDriver,
+    DriverError,
+    DriverExecutionError,
+    DriverNotFoundError,
+    DriverResult,
+    read_output,
+)
+from cabledyn.errors import (
+    CableDynError,
+    ConvergenceError,
+    DeckFormatError,
+    OutputFormatError,
+    StudyFormatError,
+    StudyOutputError,
+)
+from cabledyn.extremes import (
+    GumbelFit,
+    WeibullFit,
+    block_maxima,
+    fit_gumbel,
+    fit_weibull,
+    upcrossing_maxima,
+)
+from cabledyn.fatigue import (
+    FatigueResult,
+    RainflowCycle,
+    RainflowHistogram,
+    cycle_histogram,
+    damage_equivalent_range,
+    rainflow_cycles,
+)
+from cabledyn.formats import (
+    CoupledRun,
+    MoorDynLineHistory,
+    read_coupled_run,
+    read_moordyn_line,
+    read_moordyn_output,
+    read_openfast_output,
+    read_table,
+)
+from cabledyn.geometry import LineGeometry, Touchdown, line_geometry
+from cabledyn.processing import fft_filter, moving_average, resample
+from cabledyn.profiles import (
+    ArcProfile,
+    LineField,
+    LinePositions,
+    available_quantities,
+    line_field,
+    line_positions,
+    line_range_graph,
+    profile_at,
+    profiles_at,
+)
+from cabledyn.ranges import (
+    RangeGraph,
+    element_range_graph,
+    node_range_graph,
+    read_range_graph,
+    read_range_graphs,
+    static_range_graph,
+)
+from cabledyn.results import (
+    ChannelStatistics,
+    LineNodeHistory,
+    LineSegmentHistory,
+    OutputTable,
+    SpatialStatistics,
+    StaticLineSummary,
+    StaticProfile,
+    TimeHistory,
+)
+from cabledyn.spectra import (
+    CoherenceResult,
+    PowerSpectrum,
+    SpectralPeak,
+    magnitude_squared_coherence,
+    power_spectrum,
+)
+from cabledyn.study import StudyCaseResult, StudyResult, run_study
+from cabledyn.summary import (
+    ChannelSummary,
+    LineSummary,
+    SummaryTable,
+    channel_summary,
+    line_summary,
+)
+from cabledyn.sweep import parameter_grid
+from cabledyn.touchdown import TouchdownHistory, touchdown_history
+
+if TYPE_CHECKING:
+    from cabledyn._lib import abi_minor as abi_minor
+    from cabledyn._lib import abi_version as abi_version
+    from cabledyn._lib import library_path as library_path
+    from cabledyn._lib import version_string as version_string
+    from cabledyn.model import CableDyn as CableDyn
+
+__all__ = [
+    "API_RP_2SK_SAFETY_FACTORS",
+    "DNV_OS_E301_PARTIAL_FACTORS",
+    "DNV_OS_E301_STRENGTH_FACTOR",
+    "ArcProfile",
+    "Bathymetry",
+    "BendCheck",
+    "BendLimits",
+    "CableDynDriver",
+    "CableDynError",
+    "ChannelComparison",
+    "ChannelDamage",
+    "ChannelStatistics",
+    "ChannelSummary",
+    "ClearanceMatrix",
+    "CoherenceResult",
+    "ConvergenceError",
+    "CoupledRun",
+    "DamageProfile",
+    "DeckFile",
+    "DeckFormatError",
+    "DeckModel",
+    "DeckReferenceError",
+    "DeckWriter",
+    "DriverError",
+    "DriverExecutionError",
+    "DriverNotFoundError",
+    "DriverResult",
+    "FatigueCurve",
+    "FatigueResult",
+    "GeneratedCase",
+    "GumbelFit",
+    "HistoryComparison",
+    "LifetimeFatigue",
+    "LineClearance",
+    "LineField",
+    "LineGeometry",
+    "LineNodeHistory",
+    "LinePositions",
+    "LineSegmentHistory",
+    "LineSummary",
+    "MoorDynLineHistory",
+    "OutputFormatError",
+    "OutputTable",
+    "PowerSpectrum",
+    "RainflowCycle",
+    "RainflowHistogram",
+    "RangeGraph",
+    "Recorder",
+    "SeaStateDamage",
+    "Seabed",
+    "SeabedClearance",
+    "Snapshots",
+    "SpatialStatistics",
+    "SpectralPeak",
+    "StaticLineSummary",
+    "StaticProfile",
+    "StudyCaseResult",
+    "StudyFormatError",
+    "StudyOutputError",
+    "StudyResult",
+    "SummaryTable",
+    "SyropeEA",
+    "TensionCheck",
+    "TimeHistory",
+    "Touchdown",
+    "TouchdownHistory",
+    "WaterSurface",
+    "WeibullFit",
+    "animate",
+    "api_rp_2sk_curve",
+    "available_quantities",
+    "bend_check",
+    "block_maxima",
+    "cable_stress",
+    "chain_nominal_area",
+    "channel_damage",
+    "channel_summary",
+    "clearance_matrix",
+    "compare_histories",
+    "cycle_histogram",
+    "damage_along_arc",
+    "damage_equivalent_range",
+    "dnv_os_e301_curve",
+    "dnv_rp_c203_curve",
+    "element_range_graph",
+    "fft_filter",
+    "fit_gumbel",
+    "fit_weibull",
+    "generate_deck_cases",
+    "lifetime_fatigue",
+    "line_clearance",
+    "line_field",
+    "line_geometry",
+    "line_positions",
+    "line_range_graph",
+    "line_summary",
+    "magnitude_squared_coherence",
+    "mbr_utilisation",
+    "miner_damage",
+    "moving_average",
+    "node_range_graph",
+    "parameter_grid",
+    "power_spectrum",
+    "profile_at",
+    "profiles_at",
+    "rainflow_cycles",
+    "read_bathymetry",
+    "read_coupled_run",
+    "read_moordyn_line",
+    "read_moordyn_output",
+    "read_openfast_output",
+    "read_output",
+    "read_range_graph",
+    "read_range_graphs",
+    "read_table",
+    "resample",
+    "run_study",
+    "seabed_clearance",
+    "segment_distance",
+    "static_range_graph",
+    "study_sea_state_damage",
+    "tension_check",
+    "touchdown_history",
+    "upcrossing_maxima",
+]
+
+__version__ = "0.3.0"
+
+
+def __getattr__(name: str) -> Any:
+    """Load the optional shared-library API only when requested."""
+    if name == "CableDyn":
+        from cabledyn.model import CableDyn
+
+        return CableDyn
+    if name in {"abi_minor", "abi_version", "library_path", "version_string"}:
+        from cabledyn import _lib
+
+        return getattr(_lib, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

cabledyn/_csv.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Atomic CSV writing shared by the design-check and range-graph results."""
+
+from __future__ import annotations
+
+import contextlib
+import csv
+import os
+import tempfile
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+
+def number(value: float) -> str:
+    """Format a float with full round-trip precision."""
+    return f"{float(value):.17g}"
+
+
+def write_csv(
+    path: str | os.PathLike[str],
+    header: Sequence[str],
+    rows: Iterable[Sequence[object]],
+    *,
+    overwrite: bool,
+) -> Path:
+    """Atomically write ``rows`` under ``header``; return the absolute path."""
+    target = Path(path).expanduser().resolve()
+    if target.exists() and not overwrite:
+        raise FileExistsError(f"output already exists: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(
+        prefix=f".{target.name}.", suffix=".tmp", dir=target.parent, text=True
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as stream:
+            writer = csv.writer(stream, lineterminator="\n")
+            writer.writerow(header)
+            writer.writerows(rows)
+        os.replace(temporary, target)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(temporary)
+        raise
+    return target

cabledyn/_discovery.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Locate the CableDyn shared library without loading it.
+
+The search order is:
+
+1. ``CABLEDYN_LIBRARY``: an exact path, used as given.
+2. The package directory, for a wheel or deployment that bundles the library.
+3. The CMake build tree of a source checkout (``<repo>/build``).
+
+In the build tree only linker products are considered: ``build/bin`` and
+``build`` for a single-configuration generator, and ``build/bin/<Config>`` and
+``build/<Config>`` for a multi-configuration generator. The self-contained
+``build/runtime`` bundle is a copy and is never auto-selected, so it cannot
+shadow a newer build. When more than one configuration holds a library,
+``CABLEDYN_BUILD_CONFIG`` must name the intended one; discovery never guesses.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+CMAKE_CONFIGURATIONS = ("Release", "RelWithDebInfo", "MinSizeRel", "Debug")
+_UNCONFIGURED = "single-configuration"
+
+
+def library_basenames(os_name: str | None = None, platform: str | None = None) -> tuple[str, ...]:
+    """Return the shared-library file names loadable by the given (or current) host."""
+    host_os = os.name if os_name is None else os_name
+    host_platform = sys.platform if platform is None else platform
+    if host_os == "nt":
+        # GNU prefixes the DLL name; IFX/MSVC use the unprefixed name.
+        return ("libcabledyn.dll", "cabledyn.dll")
+    if host_platform == "darwin":
+        return ("libcabledyn.dylib",)
+    return ("libcabledyn.so",)
+
+
+def _existing(directory: Path, basenames: tuple[str, ...]) -> list[Path]:
+    """Return the libraries present in one directory, rejecting ambiguous pairs."""
+    found = [directory / name for name in basenames if (directory / name).is_file()]
+    if len(found) > 1:
+        names = ", ".join(path.name for path in found)
+        raise OSError(
+            f"cabledyn: several CableDyn shared libraries exist in {directory} ({names}). "
+            "Remove the stale product or set CABLEDYN_LIBRARY to the exact library path."
+        )
+    return found
+
+
+def build_tree_layouts(build: Path) -> dict[str, tuple[Path, ...]]:
+    """Return the linker-product directories of each CMake layout, in search order."""
+    layouts: dict[str, tuple[Path, ...]] = {_UNCONFIGURED: (build / "bin", build)}
+    for configuration in CMAKE_CONFIGURATIONS:
+        layouts[configuration] = (build / "bin" / configuration, build / configuration)
+    return layouts
+
+
+def selected_configuration(value: str | None = None) -> str | None:
+    """Return the canonical ``CABLEDYN_BUILD_CONFIG`` value, or ``None`` when unset."""
+    requested = (os.environ.get("CABLEDYN_BUILD_CONFIG", "") if value is None else value).strip()
+    if not requested:
+        return None
+    for configuration in CMAKE_CONFIGURATIONS:
+        if configuration.lower() == requested.lower():
+            return configuration
+    choices = ", ".join(CMAKE_CONFIGURATIONS)
+    raise OSError(f"cabledyn: CABLEDYN_BUILD_CONFIG must be one of {choices}; got {requested!r}")
+
+
+def find_in_build_tree(
+    build: Path,
+    basenames: tuple[str, ...],
+    configuration: str | None,
+) -> tuple[Path | None, list[Path]]:
+    """Return ``(library, searched)`` for a CMake build tree.
+
+    ``library`` is ``None`` when nothing was found. Several populated layouts
+    without an explicit ``configuration`` raise :class:`OSError`.
+    """
+    layouts = build_tree_layouts(build)
+    searched = [
+        directory / name for dirs in layouts.values() for directory in dirs for name in basenames
+    ]
+    # An explicit configuration also accepts a single-configuration build whose
+    # CMAKE_BUILD_TYPE is not encoded in the directory layout.
+    chosen = [configuration, _UNCONFIGURED] if configuration is not None else list(layouts)
+    populated: dict[str, Path] = {}
+    for name in chosen:
+        for directory in layouts[name]:
+            found = _existing(directory, basenames)
+            if found:
+                populated[name] = found[0]
+                break
+    if configuration is not None:
+        if configuration in populated:
+            return populated[configuration], searched
+        if _UNCONFIGURED in populated and not any(
+            _existing(directory, basenames)
+            for name in CMAKE_CONFIGURATIONS
+            for directory in layouts[name]
+        ):
+            return populated[_UNCONFIGURED], searched
+        return None, searched
+    if len(populated) > 1:
+        layouts_found = ", ".join(sorted(populated))
+        raise OSError(
+            f"cabledyn: {build} contains CableDyn libraries for several build layouts "
+            f"({layouts_found}). "
+            "Set CABLEDYN_BUILD_CONFIG to the intended configuration or CABLEDYN_LIBRARY to the "
+            "exact library path."
+        )
+    return (next(iter(populated.values())) if populated else None), searched
+
+
+def find_library(package_directory: Path | None = None) -> Path:
+    """Return the CableDyn shared library to load, or raise :class:`OSError`."""
+    exact = os.environ.get("CABLEDYN_LIBRARY", "").strip()
+    if exact:
+        path = Path(exact).expanduser()
+        if not path.is_file():
+            raise OSError(f"cabledyn: CABLEDYN_LIBRARY does not name an existing file: {exact}")
+        return path.resolve()
+
+    package = Path(__file__).resolve().parent if package_directory is None else package_directory
+    basenames = library_basenames()
+    bundled = _existing(package, basenames)
+    if bundled:
+        return bundled[0]
+
+    # Source checkout: <repo>/python/cabledyn -> <repo>/build.
+    build = package.parent.parent / "build"
+    library, searched = find_in_build_tree(build, basenames, selected_configuration())
+    if library is not None:
+        return library.resolve()
+    tried = [package / name for name in basenames] + searched
+    raise OSError(
+        "cabledyn: could not locate the CableDyn shared library. Set CABLEDYN_LIBRARY to its "
+        "full path, or build it with `cmake --build build --target cabledyn_shared`. Tried:\n  "
+        + "\n  ".join(str(path) for path in tried)
+    )
+
+
+def dependency_directories(library: Path) -> list[Path]:
+    """Return directories that may hold the library's toolchain runtime DLLs.
+
+    The library's own directory comes first. For a multi-configuration build
+    tree the GNU/OpenBLAS runtime set is staged once in ``build/bin`` and
+    ``build/runtime`` rather than beside each configuration's product.
+    """
+    directories = [library.parent]
+    for ancestor in library.parents:
+        if ancestor.name == "build":
+            directories.extend(
+                path for path in (ancestor / "bin", ancestor / "runtime") if path.is_dir()
+            )
+            break
+    unique: list[Path] = []
+    for directory in directories:
+        if directory not in unique:
+            unique.append(directory)
+    return unique