Metadata-Version: 2.4
Name: cabledyn
Version: 0.3.0
Summary: Python APIs for the CableDyn standalone driver and native coupling library
Keywords: cable dynamics,dynamic power cable,finite element,floating offshore wind,lazy wave,mooring dynamics,MoorDyn,offshore engineering,OpenFAST
Author-Email: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Fortran
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/SMI-Lab-Inha/CableDyn
Project-URL: Documentation, https://cabledyn.readthedocs.io
Project-URL: Repository, https://github.com/SMI-Lab-Inha/CableDyn
Project-URL: Issues, https://github.com/SMI-Lab-Inha/CableDyn/issues
Project-URL: Changelog, https://github.com/SMI-Lab-Inha/CableDyn/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/SMI-Lab-Inha/CableDyn/releases
Project-URL: Citation, https://doi.org/10.1016/j.oceaneng.2026.128332
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: dataframe
Requires-Dist: pandas>=2.0; extra == "dataframe"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: post
Requires-Dist: pandas>=2.0; extra == "post"
Requires-Dist: matplotlib>=3.7; extra == "post"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: Apache-2.0 -->

# cabledyn: Python tools for CableDyn

`cabledyn` is for engineers who script CableDyn analyses. It runs the standalone
solver, reads and post-processes results, validates and edits input decks, runs
parameter studies, and couples to the solver in-process through the C interface.
The full reference is the
[Python chapter of the CableDyn manual](https://cabledyn.readthedocs.io/en/latest/python.html).

## Install

From PyPI (Python 3.10 or newer; NumPy is the only required dependency):

```powershell
py -m pip install cabledyn
py -m pip install "cabledyn[post]"   # adds pandas and matplotlib
```

The wheels for Windows x64, Linux x86-64 (both for processors with AVX2) and macOS
on Apple silicon carry the solver: the CableDyn shared library for the in-process
`CableDyn` class and the standalone driver that `CableDynDriver` and `cabledyn-run`
run. On another platform pip builds from the source distribution, which needs a
Fortran compiler and LAPACK.

The pure Python wheel attached to each
[GitHub release](https://github.com/SMI-Lab-Inha/CableDyn/releases/latest)
(`cabledyn-0.3.0-py3-none-any.whl`) carries no solver. `CableDynDriver` finds the
driver from an explicit path, then the `CABLEDYN_DRIVER` environment variable,
then the driver inside the package, then `PATH`; the in-process `CableDyn` class
uses the library inside the package, or one named by `CABLEDYN_LIBRARY` or found in
a source checkout's build tree.

## Components

| Component | Purpose |
|---|---|
| `CableDynDriver`, `cabledyn-run` | Run a deck, check completion, and read the output tables |
| `read_output`, `read_openfast_output`, `read_moordyn_output`, `read_moordyn_line`, `read_coupled_run`, `read_table` | Read CableDyn, OpenFAST (text and binary), and MoorDyn results |
| `TimeHistory`, `cabledyn-post` | Statistics, plots, spectra, coherence, rainflow fatigue, and CSV/TSV export |
| `compare_histories`, `resample`, `fft_filter`, `block_maxima`, `fit_gumbel`, `fit_weibull`, `line_geometry` | Run comparison, signal processing, extreme values, and line geometry |
| `DeckFile`, `DeckWriter`, `cabledyn-deck` | Validate, edit, and write decks, preserving comments and formatting |
| `generate_deck_cases`, `parameter_grid`, `run_study`, `cabledyn-study` | Generate and run parameter studies with hashed manifests |
| `CableDyn` | In-process coupling through the C interface |

## Example

```python
from cabledyn import CableDynDriver

driver = CableDynDriver(r"C:\CableDyn\CableDyn_driver.exe")
result = driver.run("model.dat", "results/baseline", timeout=600)

history = result.read_main()
print(history.statistics("FairTen1")[0])

fatigue = history.fatigue("FairTen1", start=600.0, stop=4200.0,
                          wohler_exponent=3.0, reference_frequency=1.0, bins=32)
print(fatigue.damage_equivalent_range)

profile = result.read_static()
profile.plot("Curvature", line_id=1)
```

A returned result is always a converged analysis: a failed solver step, timeout,
missing output, or malformed or non-finite data raises a typed exception. Existing
results are kept unless `overwrite=True`, and then restored if the new run fails.

Run a generated study from the command line:

```powershell
cabledyn-study generated\cases.json --executable C:\CableDyn\CableDyn_driver.exe `
  --output-directory generated\results --jobs 4 --channel FairTen1 --start 600 --stop 4200
```

`cabledyn-study` exits `1` if any case failed, `2` for an invalid manifest or
unsafe destination, and `3` if the cases ran but `study.json` or `summary.csv`
could not be written.

## Documentation

- [Python guide](https://cabledyn.readthedocs.io/en/latest/python.html)
- [Post-processing](https://cabledyn.readthedocs.io/en/latest/python_postprocessing.html)
- [API reference](https://cabledyn.readthedocs.io/en/latest/api_python.html)
- [Command-line tools](https://cabledyn.readthedocs.io/en/latest/cli.html)

Licensed under the Apache License 2.0.
