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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Added

- A finite-EI line may end on a `Free` point: the line's free End B, its position free in the
static equilibrium and the dynamics, with the point's Mass/Vol/CdA/Ca acting on the end node as
an attachment (a free-hanging cable or riser with a clump). The static solve holds the end on
the stretched chord first and then releases it; `Point<P>p…` channels read the end node.
Standalone decks of finite-EI lines without bodies, rods or Connect points, every Free point
such an end (pinned in bending at both ends, net heavy, from a Coupled/Vessel End A; a torsion
restraint at one end is noted and not solved); any other deck,
and host-driven decks, keep their behaviour. The Python deck reader takes the same rule.
- Bending damping of finite-EI cables: the LINE TYPES EI column takes `EI|Bb`, a Kelvin-Voigt
damping moment `Bb` [N m^2 s] times the curvature rate (in the frame carried with the tangent),
or `EI|-zeta|f`, the damping ratio of a pure bending mode of frequency `f` (Bb = zeta EI/(pi f)).
Expand Down
3 changes: 3 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1362,6 +1362,9 @@ set_tests_properties(viv_amplitude_deck PROPERTIES LABELS "fortran;integration;d
add_executable(test_viv_diameter_deck tests/test_viv_diameter_deck.f90)
target_link_libraries(test_viv_diameter_deck PRIVATE cabledyn_core)
add_test(NAME viv_diameter_deck COMMAND test_viv_diameter_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
add_executable(test_free_end_deck tests/test_free_end_deck.f90)
target_link_libraries(test_free_end_deck PRIVATE cabledyn_core)
add_test(NAME free_end_deck COMMAND test_free_end_deck WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
set_tests_properties(viv_diameter_deck PROPERTIES LABELS "fortran;integration;dynamic;viv" TIMEOUT 1200)

add_executable(test_hermite_viv tests/test_hermite_viv.f90)
Expand Down
6 changes: 6 additions & 0 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,12 @@ Line and constitutive capability
- Supported
- lumped at nodes of a finite-EI cable, standalone and coupled, also on a line restrained in
torsion (they add no polar inertia to its twist)
* - Free end of a finite-EI cable (a ``Free`` End B)
- Supported with limits
- a free-hanging cable or riser with a clump or a bare end, its static rest position solved
before the march, on a standalone deck of finite-EI lines without bodies, rods or
Connect points, from a Coupled/Vessel End A; host-driven decks refuse it
(:ref:`theory-free-cable-end`)
* - Bend stiffeners (``STIFFENERS``)
- Supported with limits
- tapered linear-elastic sleeve over a finite-EI line end, adding bending stiffness, mass,
Expand Down
28 changes: 27 additions & 1 deletion doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -727,7 +727,7 @@ A POINTS row has 9 columns, `ID Type X Y Z Mass Vol CdA Ca`, or the short 5-colu
| `Body<N>` | line end on body N; (X,Y,Z) is the attachment offset in the body frame | X,Y,Z offset; the body supplies Mass/Vol/CdA/Ca |
| `Rod<N>A` / `Rod<N>B` | line end on rod N End A / End B; coordinates come from the `RODS` row | X,Y,Z placeholders; zero Mass/Vol/CdA/Ca |
| `Connect` | free internal point where ≥ 2 lines meet; its static position is solved from force balance (lines, weight/buoyancy, current drag) starting at the deck seed, and the march starts there | X,Y,Z seed; Mass, Vol, CdA, Ca ≥ 0 |
| `Free` | free line end (clump or float terminal); a one-line `Connect`, solved the same way | X,Y,Z seed; Mass, Vol, CdA, Ca ≥ 0 |
| `Free` | free line end (clump or float terminal); a one-line `Connect`, solved the same way; as the End B of a finite-EI line, that line's free end ([below](#free-cable-end)) | X,Y,Z seed; Mass, Vol, CdA, Ca ≥ 0 |
| `Turbine<J>` / `T<J>` | FAST.Farm coupled point on turbine J (turbine-local coordinates) | X,Y,Z; zero Mass/Vol/CdA/Ca |

For dynamic `Connect`/`Free` points, `Mass` is inertial mass and `(rhoW·Vol − Mass)·g` is a
Expand All @@ -742,6 +742,30 @@ of its BODY `Mass`/`Vol` (see the theory manual, Seabed contact).
standalone driver. Non-zero `Mass`/`Vol`/`CdA`/`Ca` on `Fixed`, `Coupled`, `Vessel`, `Body<N>`,
`Rod<N>A/B`, or `Turbine<J>` points is rejected.

(free-cable-end)=
**A free finite-EI cable end.** A `Free` point that ends exactly one finite-EI line, as its End B
with a `Coupled` or `Vessel` End A (a still hang-off is a `Coupled` point without motion), is that
line's free end on a standalone deck whose lines are all finite-EI and that has no BODIES,
RODS or other `Connect`/`Free` point (a free-hanging cable or riser with a clump or a bare end).
The point's `Mass`, `Vol`, `CdA` and `Ca` act on the line's End B node as an
[ATTACHMENTS](#attachments-optional-finite-ei-lines) row at the line's full arc length (weight
and buoyancy, added mass, and drag against current and waves), with the point's isotropic drag
`½ rhoW CdA ‖w‖ w` on the whole relative velocity rather than the attachment's normal/axial split. The static equilibrium is solved
with the end first held on the chord from End A towards the deck position, at the line's length
stretched by its hanging weight, then released, so the run starts at the end's rest position
(the theory manual, Free cable ends); the dynamics leave the end's position free. `Point<P>p…`
channels read the line's End B node, and the End B force (`AnchTen`, `Point<P>F…`) is the line load
the point balances, without the point's own loads (a clump at rest reads its submerged weight). The line must be pinned in bending at both ends (no
non-pinned `END CONNECTIONS` row), with at most one end restrained in torsion, which is then not
solved (a free end carries no moment or torque; the initialisation note says why), and the point
and the line must be net heavy (the end hangs). A deck in which any `Free` point is not such an end
(a clamped or buoyant end, a second `Free` point, a `Connect` point), and a host-driven deck
(OpenFAST, the C API) or a `bathymetryFile` deck, is left as it was: the routes that take `Free`
points run it or refuse a finite-EI cable on a `Free` point by name. On a flat seabed a seed below
the seabed is placed on it at the same stretched length; an end that comes to rest on the seabed
with a net-heavy point is refused by name (the point has no seabed contact of its own on a
finite-EI line), while a bare end rests on the line's own contact.

`Turbine<J>` points (J ≥ 1) need the turbine reference positions from one of two sources: the
OpenFAST/FAST.Farm aggregate route, where the host supplies them, or a
[TURBINES](#turbines-standalone-farm-decks) section, with which the standalone driver runs the
Expand Down Expand Up @@ -789,6 +813,8 @@ rod end, and `Free`/`Connect`-to-`Coupled` lines are left as written.
fails with `LINE End A fairlead (NodeA) must not be below End B anchor (NodeB)`. The exceptions
are a FAST.Farm shared line with both ends on `Turbine<J>` points and a finite-EI line whose End
B is also a `Coupled`/`Vessel` point (a line between two moving points, driven at both ends).
- A finite-EI line may end on a `Free` point as its End B on a standalone deck of finite-EI lines
(its [free end](#free-cable-end)); that point does not count as a dynamic point.
- In a deck with dynamic points, line ends may be `Fixed`, `Coupled`, `Vessel`, `Connect`, `Free`,
`Body<N>`, or `Rod<N>A/B`.

Expand Down
36 changes: 36 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,42 @@ as closely. The local value is floored at 0.1 % of the root curvature, as the cu
sign near the tip. On the same hang-off, the curvature along the stiffener follows OrcaFlex
11.6d with its stiffener given as a line attachment within 0.5 % of the root curvature.

.. _theory-free-cable-end:

Free cable ends
~~~~~~~~~~~~~~~

A finite-EI line whose End B is a ``Free`` point (:doc:`driver_format`) has that end's position
free: the dynamic march holds only End A's three positions, and the point's mass, volume, drag
area and added-mass coefficient act on the End B node as a discrete attachment (the weight
:math:`(M - \rho V)g`, the added mass :math:`C_a \rho V`, the fluid inertia), with the point's
isotropic drag :math:`\tfrac12 \rho\, C_dA\, |\mathbf w|\,\mathbf w` on the whole relative velocity,
as a ``Free`` point carries it, rather than the attachment's normal/axial split. The point's loads
stay out of the End B force (``AnchTen``, ``Point<P>F``): it is the force the line exerts on the
point, the line load the point balances, as on the ``EI = 0`` route. The end carries no moment (it is pinned, a natural boundary condition of the
cubic-Hermite element) and no torque: the line is pinned in bending at both ends, and a torsion
restraint at its other end is not solved (it is noted, as for a line with two moving ends).

The static equilibrium starts from a held seed: the end is placed on the chord from End A towards
the point's deck position, at the line's length stretched by its hanging weight,
:math:`L\,(1 + (W_B + \sum w_i L_i)/EA_{\min})`, so that the seed is the taut straight line (a
vertical span of exactly the line's length has no catenary seed). The line's static solve (with
its attachments' homotopy) runs with that end held; the end is then released and the full-load
equilibrium is solved again with its position free, by the attachment polish's warm-started
Newton solve with its fallbacks, repeated to the drag and surface fixed point. The run starts at
that rest position. The line and the point must be net heavy, so that the end hangs. On a flat
seabed a seed that would lie below the seabed (a line longer than the depth below End A) is placed
on the seabed at the same stretched length, out along the deck chord's horizontal direction; an end
whose point is net heavy and that comes to rest on the seabed is refused, since an attachment has no
seabed contact of its own on a finite-EI line (a bare end rests on the line's contact).

On a 7 m cable (2.8 kg/m, EA 1e8 N) with a 200 kg clump the top tension is the submerged weight
of both to 1e-6 relative and the end hangs one stretched length below the top to 1e-7 m; in a
0.5 m/s current the end rests where the ``EI = 0`` route puts the same deck's ``Free`` point
(within 2e-5 m at EI 3 N m², and converging to it as EI falls); and a 0.05 m sway of the top at
0.05 Hz moves the end in phase with an amplitude ratio within 1 % of the Rayleigh estimate of the
hanging string with its end mass (``tests/test_free_end_deck.f90``).

.. _theory-output-recovery:

Node tension, curvature and bend moment
Expand Down
107 changes: 107 additions & 0 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -3720,6 +3720,102 @@ def validate(self) -> None:
raise DeckFormatError(f"{exc}{_STATIC_CHECK_HINT}") from None
raise

def _free_cable_ends(
self,
point_types: dict[str, str],
line_type_meta: dict[str, tuple[float, float, float, float]],
effective: Callable[[str, float], float],
) -> set[str]:
"""The Free points native promote_free_cable_ends makes free finite-EI cable ends."""
if (
self.caller_driven
or self._rows("BODIES")
or any(segments != 0 for _, segments in self._rod_rows_by_id().values())
or any(_option_key(option.keyword) == "bathymetry" for option in self.options)
):
return set()
sections: dict[str, list[tuple[str, float]]] = {}
ends: dict[str, tuple[str, str]] = {}
try:
for section in self._rows("SECTIONS"):
sections.setdefault(str(_native_int(section.tokens[0])), []).append(
(section.tokens[1].lower(), _native_float(section.tokens[2]))
)
for row in self.lines:
line_key = str(_native_int(row.tokens[0]))
a_tok, b_tok = (
(row.tokens[2], row.tokens[3]) if len(row.tokens) == 7 else row.tokens[1:3]
)
ends[line_key] = (str(_native_int(a_tok)), str(_native_int(b_tok)))
if len(row.tokens) == 7:
sections[line_key] = [(row.tokens[1].lower(), _native_float(row.tokens[4]))]
except (ValueError, IndexError):
return set()
if not ends or not all(
any(
line_type_meta.get(name, (0.0, 0.0, 0.0, 0.0))[3] > 0.0
for name, _ in sections.get(k, [])
)
for k in ends
):
return set()

# pinned in bending at both ends, at most one end restrained in torsion; a numeric zero
# stiffness is pinned / free, as native append_end_connection reads it
def zero_or(token: str, keywords: frozenset[str]) -> bool:
word = _strip_quotes(token).lower()
if word in keywords:
return True
try:
return _native_float(word) == 0.0
except ValueError:
return False

clamped: set[str] = set()
twisted: dict[str, int] = {}
for row in self.end_connections:
with contextlib.suppress(ValueError, IndexError):
line_key = str(_native_int(row.tokens[0]))
if not zero_or(row.tokens[2], _PINNED_END_CONNECTIONS):
clamped.add(line_key)
if len(row.tokens) >= 10 and not zero_or(row.tokens[6], _FREE_TORSION_KEYWORDS):
twisted[line_key] = twisted.get(line_key, 0) + 1
clamped |= {line_key for line_key, count in twisted.items() if count > 1}
rho_w, grav = effective("water_density", 1025.0), effective("gravity", 9.80665)
rows = {str(_native_int(row.tokens[0])): row for row in self.points}
promoted: set[str] = set()
for point_id, point_type in point_types.items():
if point_type == "connect":
return set()
if point_type != "free":
continue
refs = [k for k, pair in ends.items() if point_id in pair]
if len(refs) != 1 or ends[refs[0]][1] != point_id:
return set()
line_key = refs[0]
if (
point_types.get(ends[line_key][0], "") not in {"coupled", "vessel"}
or line_key in clamped
):
return set()
if any(name not in line_type_meta for name, _ in sections.get(line_key, [])):
return set()
values = [_native_float(tok) for tok in rows[point_id].tokens[2:]]
mass, vol = (values[3], values[4]) if len(values) == 7 else (0.0, 0.0)
w_line = sum(
(line_type_meta[name][1] - rho_w * 0.25 * math.pi * line_type_meta[name][0] ** 2)
* grav
* length
for name, length in sections.get(line_key, [])
)
w_point = (mass - rho_w * vol) * grav
if not (w_line + w_point > 0.0 and w_point >= 0.0):
return set()
if not any(line_type_meta[name][2] > 0.0 for name, _ in sections.get(line_key, [])):
return set()
promoted.add(point_id)
return promoted

def _validate(self) -> None:
required = {"LINE TYPES", "POINTS", "LINES"}
if not self._rows("LINES") and (self._rows("RODS") or self._rows("BODIES")):
Expand Down Expand Up @@ -4383,6 +4479,15 @@ def end_key(token: str) -> str:
f"z = -WtrDpth = {z_floor:.10g} m by more than the {tolerance:.2e} m "
"seabed tolerance; place the anchor on (or above) the seabed"
)
# Native promote_free_cable_ends: a Free point that ends exactly one finite-EI line as its
# End B (from a Coupled/Vessel End A, pinned and free in torsion, net heavy), on a
# standalone deck of finite-EI lines with no BODIES, RODS or Connect point, is the line's
# free End B (its loads an end attachment) and reads Fixed from here on, when every Free
# point of the deck is such an end; otherwise the deck is left as it is.
free_cable_ends = self._free_cable_ends(point_types, line_type_meta, effective)
self._free_cable_end_points = free_cable_ends
for point_id in free_cable_ends:
point_types[point_id] = "fixed"
has_dynamic_points = any(
point_type in {"connect", "free"} or point_type.startswith(("body", "rod"))
for point_type in point_types.values()
Expand Down Expand Up @@ -6379,6 +6484,8 @@ def _check_torsion_lines(
"its LINE TYPES rows give no GJ (the 14-column row; torsion has no "
"EI/1.3 default)"
)
elif end_b in getattr(self, "_free_cable_end_points", set()):
note = "its End B is a free end (a Free point)"
elif point_types[end_b] != "fixed":
note = "it has two moving ends (torsion needs a Fixed End B)"
elif dynamic and not force_blend:
Expand Down
Loading
Loading