Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions doc/api_python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,10 @@ Reading results
:func:`read_output` returns the most specific table class for the file it reads:
:class:`TimeHistory` for the main output, :class:`LineNodeHistory` and
:class:`LineSegmentHistory` for per-line dynamic outputs, :class:`StaticProfile` for the static
profile, and :class:`OutputTable` for any other numeric table. :class:`TimeHistory` and
:class:`StaticProfile` are subclasses of :class:`OutputTable`; :class:`LineNodeHistory` and
profile, :class:`NaturalModes` for the two tables of a ``.modes.out`` file, and
:class:`OutputTable` for any other numeric table. :class:`TimeHistory`, :class:`StaticProfile`,
:class:`NaturalModes` and :class:`ModeShapes` are subclasses of :class:`OutputTable`;
:class:`LineNodeHistory` and
:class:`LineSegmentHistory` are subclasses of :class:`TimeHistory`, so every table method is
available on them.

Expand All @@ -84,6 +86,12 @@ available on them.
.. autoclass:: cabledyn.StaticProfile
:members:

.. autoclass:: cabledyn.NaturalModes
:members:

.. autoclass:: cabledyn.ModeShapes
:members:

.. autoclass:: cabledyn.ChannelStatistics
:members:

Expand Down
2 changes: 2 additions & 0 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -463,6 +463,8 @@ column, for every line of the file (``0`` on a line without torsion):
mode (``PolarShare`` above 0.5) is scaled to a unit largest ``dTwist`` instead, and its
translations are then in metres per radian of that twist.

:func:`cabledyn.read_output` reads both tables into a :class:`cabledyn.NaturalModes`.

Per-rod files (``RODS`` ``Outputs`` flag)
-----------------------------------------

Expand Down
43 changes: 40 additions & 3 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,9 @@ Pass the executable explicitly for the most reproducible setup:
fairlead_tension = history.column("FairTen1") # N

``result`` retains the executable, absolute deck and output paths, captured ``stdout`` and
``stderr``, return code, the optional static profile and finite-EI element table
(``elements_output``), and all requested per-line and per-rod outputs. A result is returned only
``stderr``, return code, the optional static profile, finite-EI element table
(``elements_output``) and modal table (``modes_output``, read with ``result.read_modes()``), and
all requested per-line and per-rod outputs. A result is returned only
for a fully converged analysis: the driver exits non-zero whenever a nonlinear step fails.
Arrays returned by the parser are read-only so post-processing cannot accidentally mutate the
recorded result.
Expand Down Expand Up @@ -135,7 +136,8 @@ archive the native diagnostic.
Typed result objects
--------------------

:func:`cabledyn.read_output` accepts main histories, static profiles, and per-line tables. It
:func:`cabledyn.read_output` accepts main histories, static profiles, per-line tables, and modal
tables. It
recognises both current main output (title + channel row) and tables with a units row in the
style of OpenFAST (maintained by NLR, the National Laboratory of the Rockies, formerly NREL):

Expand All @@ -161,6 +163,41 @@ and a generic :class:`cabledyn.OutputTable` for static per-line node or segment
strictly increasing; line and node identifiers must be positive integers; and arc length must be
monotonic within each line.

Natural modes
~~~~~~~~~~~~~

A deck that sets ``nModes`` writes ``<root>.modes.out``, which holds two tables (see
:doc:`outputs`). :func:`cabledyn.read_output` reads both into one
:class:`cabledyn.NaturalModes`: the object is the frequency table, and its ``shapes`` attribute is
the mode-shape table, a :class:`cabledyn.ModeShapes`. Each table is an
:class:`cabledyn.OutputTable`, so ``column``, ``unit`` and ``to_dataframe`` work on either; an
export of the object writes the frequency table only.

.. code-block:: python

from cabledyn import read_output

modes = read_output("results/baseline.modes.out") # or result.read_modes()

print(modes.line_ids)
print(modes.periods(1)) # s, by mode
print(modes.frequencies(1)) # Hz, by mode

xyz = modes.shapes.positions(1) # static node positions, (n_nodes, 3), m
shape = modes.shapes.displacements(1, 2) # mode 2, (n_nodes, 3), largest node 1
line_2 = modes.line(2) # both tables of one line

A file with a line restrained in torsion has the columns ``PolarShare`` and ``dTwist`` for every
line, and ``has_twist`` is true. ``modes.polar_shares(1)`` and ``modes.shapes.twist(1, mode)``
return them, and ``modes.torsional_modes(1)`` the modes above a polar share of 0.5, which are
scaled to a unit largest twist instead of a unit largest displacement. On a file without the
columns these return zeros and no modes, as on a line without torsion.

A negative eigenvalue has a negative ``Frequency`` and ``Omega`` and a ``Period`` of 0. A line
without free nodes has no modes and no rows, so it is absent from ``line_ids``. The reader refuses
a file without a mode-shape table, and one whose two tables do not hold the same modes of the same
lines.

Statistics, range graphs, and geometry
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
4 changes: 4 additions & 0 deletions python/cabledyn/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@
ChannelStatistics,
LineNodeHistory,
LineSegmentHistory,
ModeShapes,
NaturalModes,
OutputTable,
SpatialStatistics,
StaticLineSummary,
Expand Down Expand Up @@ -196,7 +198,9 @@
"LinePositions",
"LineSegmentHistory",
"LineSummary",
"ModeShapes",
"MoorDynLineHistory",
"NaturalModes",
"OutputFormatError",
"OutputTable",
"PowerSpectrum",
Expand Down
30 changes: 30 additions & 0 deletions python/cabledyn/driver.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
from cabledyn.results import (
LineNodeHistory,
LineSegmentHistory,
NaturalModes,
OutputTable,
StaticProfile,
TimeHistory,
Expand Down Expand Up @@ -174,6 +175,9 @@ class DriverResult:
Captured standard error of the driver.
returncode : int
Native exit code; always ``0`` for a result.
modes_output : pathlib.Path | None
Natural frequencies and mode shapes ``<root>.modes.out``, or ``None``
if not written.
"""

executable: Path
Expand All @@ -187,6 +191,7 @@ class DriverResult:
stdout: str
stderr: str
returncode: int
modes_output: Path | None = None

def read_main(self) -> TimeHistory:
"""Read the primary channel history again from disk.
Expand Down Expand Up @@ -230,6 +235,29 @@ def read_static(self) -> StaticProfile:
raise OutputFormatError(f"{self.static_output}: static output is not a line profile")
return table

def read_modes(self) -> NaturalModes:
"""Read the natural modes, raising if this run did not write them.

Returns
-------
NaturalModes
The frequency table of each line, with the mode shapes in its
``shapes`` attribute.

Raises
------
FileNotFoundError
If the run did not write a modal output (the deck sets no ``nModes``).
OutputFormatError
If the file is malformed or not a modal output.
"""
if self.modes_output is None:
raise FileNotFoundError("the run did not produce a .modes.out file")
table = read_output(self.modes_output)
if not isinstance(table, NaturalModes):
raise OutputFormatError(f"{self.modes_output}: modal output has no modal tables")
return table

@property
def line_ids(self) -> tuple[int, ...]:
"""Line identifiers for which a per-line output file was produced."""
Expand Down Expand Up @@ -646,6 +674,7 @@ def _execute(
) from exc
static_candidate = Path(f"{root}.static.out")
elements_candidate = Path(f"{root}.elements.out")
modes_candidate = Path(f"{root}.modes.out")
line_outputs = _auxiliary_outputs(root, "Line")
rod_outputs = _auxiliary_outputs(root, "Rod")
return DriverResult(
Expand All @@ -660,4 +689,5 @@ def _execute(
stdout=completed.stdout,
stderr=completed.stderr,
returncode=completed.returncode,
modes_output=modes_candidate if modes_candidate.is_file() else None,
)
Loading
Loading