From cf28a1cd119e677b074bfc8ef70a6daed0f1b0e5 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 15:50:43 +0900 Subject: [PATCH 1/7] feat(openfast): linearise lines restrained in torsion With Linearize = True a finite-EI line restrained in torsion no longer fails closed. Its nodal twist joins the line states: the twist angle of every node its end frames do not hold (all but a torsionally rigid end) after the cables' positions and tangents, and the angle rates after their velocities ("Cable 1 node 2 twist, rad" / "twist rate, rad/s"). lin_eval loads them into the mirror with the rest of the state, and the angles' accelerations come from the same acceleration solve as the cable's, with the lumped polar inertia Irn. CD_HFMF_Twist_Lin_Count/_Slots give the slots in the cable's torsion tail. The input mesh already carried the coupled point's orientation and angular rates, and the output mesh the moment. The orientation turns the parent-attached End A frame (SetCoupledKinematics), so the condensed torque (Phi - Theta)/C and a nodal twist's end element see the turned frame, and the fairlead moment carries the torque. New CD_HFMF_Set_Twist_Frame_Rates gives that frame the point's angular velocity and acceleration, which the march takes from the frame's turn over a step: the torsional damping of the end element and the polar inertia of the held end section now have their B and D columns. Under linearisation the rotation is stepped by 1e-4 rad instead of 0.1 rad (a rotation moves no node, so no contact or slack bounds it, and the turn of an end frame or connection direction is nonlinear). This moves the rotation columns of a deck with a hang-off spring by up to 0.17 %; on a straight line with a 2e5 N m/rad hang-off spring the force per unit rotation now matches static solutions to 4e-8 (6.8e-6 before). The time-domain input Jacobian keeps 0.1 rad. A Rigid bending end connection still fails closed. Gates: - openfast_lin_torsion.py (full OpenFAST linearisation, the case of openfast_lin_ab.py). A straight taut 100 m line, GJ 5e4 N m^2, Irn 2 kg m, 50 elements, rigid in torsion at both ends: the first three torsional modes from the eigenvalues of A are the lumped chain's 2 sqrt(GJ/Irn)/h sin(n pi/2N) to 5e-14 and lie -1.6e-4, -6.6e-4, -1.5e-3 below the continuum's n pi/L sqrt(GJ/Irn). The roll stiffness D - C A^-1 B is GJ/L = 500 N m/rad to 1.5e-14; D alone is the end element's GJ/l_e = 25000. The mixed deck's lazy-wave cable alone, twisted 90 deg (3470 states), matches the deck's static solutions to 4.9e-4: the moment about the End A director per unit rotation about it (Pretwist(A) +-0.5 deg) is 82.4268 / 82.4263 N m/rad, then the forces and that moment per unit fairlead translation, and the forces per unit rotation against the reciprocal moment row. - test_lin_torsion (ctest): the shell's lin_eval sequence on the aggregate. Twist modes against the lumped chain to 1e-14, twist block decoupled from the line states (exactly). Roll stiffness GJ/L for the nodal twist and the condensed torsion, 1/(L/GJ + 1/kt) with an elastic end. Bt/L per unit angular velocity (0 without the frame rates), and Irn l_e/2 per unit angular acceleration. - The #66 gates are unchanged: the UMaine fairlead stiffness against MoorDyn-F to 0.10 % (H/X 0.29 %), the line modes to 0.30 %, the mixed deck's coupled points against their static solutions to 3.3e-4. An executable without twist states refuses both decks at initialisation. The full suite passes, and all 53 example decks are bit-identical to dev. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 15 +- CMakeLists.txt | 8 + VALIDATION.md | 23 +- doc/capabilities.rst | 15 +- doc/driver_format.md | 11 +- doc/openfast.rst | 45 +- doc/outputs.rst | 8 +- doc/troubleshooting.rst | 3 - src/CableDyn_OpenFAST_HermiteFMF.f90 | 72 +++ src/openfast/CableDyn_OF.f90 | 147 +++++- tests/test_lin_torsion.f90 | 586 +++++++++++++++++++++ validation/scripts/openfast_lin_torsion.py | 415 +++++++++++++++ 12 files changed, 1278 insertions(+), 70 deletions(-) create mode 100644 tests/test_lin_torsion.f90 create mode 100644 validation/scripts/openfast_lin_torsion.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e1061aa3..6cc37ca8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,17 @@ All notable changes to CableDyn are recorded in this file. The format follows load-dependent) and 4e-9 at rest; after a length step it is MoorDyn's at the carried stretch to 4e-16 (carrying the strain instead would be off by 0.4 to 4.6 %); a restart in the ramp continues bit for bit. +- OpenFAST linearisation of finite-EI lines restrained in torsion: the twist angles of the nodes + the end frames do not hold, and their rates, are continuous states (`Cable 1 node 2 twist, + rad`); the coupled point's orientation turns the line's End A frame, its angular velocity and + acceleration reach the torsional damping and the held end section's inertia, and the fairlead + moment carries the torque. A straight line's torsional modes from the eigenvalues of `A` are + the lumped chain's to 5e-14 (the continuum's `nπ/L √(GJ/Irn)` less the discretisation error, + 1.6e-4 for the first mode at 50 elements) and its roll stiffness `D − C A⁻¹ B` is `GJ/L` to + 1.5e-14; a 90° twisted lazy wave matches the deck's static solutions for a rolled and a moved + fairlead to 4.9e-4. Under linearisation the coupled-point rotation is stepped by 1e-4 rad + instead of 0.1 rad, which changes the rotation columns of a deck with a hang-off spring by up + to 0.17 %. - OpenFAST linearisation with the line dynamics, as MoorDyn-F's: the continuous states are the interior-node positions of every `EI = 0` line (MoorDyn's names and order) and the free degrees of freedom of every finite-EI cable (node positions and tangents), then their @@ -63,8 +74,8 @@ All notable changes to CableDyn are recorded in this file. The format follows and the Syrope slow strain are first-order states, so the reduction gives these ropes' relaxed static stiffness (each matches its deck's static solutions to 7e-5; held, they would read the chain 0.6 % and the polyester 2.9 times too stiff). Free/Connect points, a `Rigid` cable end - connection, VIV lines, bodies, rods, buoys, torsion and `CONTROL` fail closed with named - messages. This replaces the quasi-static linearisation without states. + connection, VIV lines, bodies, rods, buoys and `CONTROL` fail closed with named messages. This + replaces the quasi-static linearisation without states. - Composite Syrope lines: a Syrope polyester section between plain `EI = 0` sections, such as a chain-polyester-chain mooring, in one LINE. The static start puts every Syrope element on the rest curve of its load history with its own secant EA (the tension varies along a sagging diff --git a/CMakeLists.txt b/CMakeLists.txt index 7960bd80..14132b7a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2188,6 +2188,14 @@ target_link_libraries(test_coupled_torsion PRIVATE cabledyn_core) add_test(NAME coupled_torsion COMMAND test_coupled_torsion WORKING_DIRECTORY ${CMAKE_BINARY_DIR}) set_tests_properties(coupled_torsion PROPERTIES LABELS "fortran;unit;static;dynamic;openfast") +# OpenFAST linearisation of a line restrained in torsion, by the shell's lin_eval recipe on the +# aggregate: the twist modes of A against n pi/L sqrt(GJ/Irn), the reduced roll stiffness GJ/L +# (nodal twist and condensed), the damping and inertia columns of the platform's angular rates. +add_executable(test_lin_torsion tests/test_lin_torsion.f90) +target_link_libraries(test_lin_torsion PRIVATE cabledyn_core) +add_test(NAME lin_torsion COMMAND test_lin_torsion WORKING_DIRECTORY ${CMAKE_BINARY_DIR}) +set_tests_properties(lin_torsion PROPERTIES LABELS "fortran;unit;dynamic;openfast") + add_executable(test_torsion_orcaflex tests/test_torsion_orcaflex.f90) target_link_libraries(test_torsion_orcaflex PRIVATE cabledyn_core) add_test(NAME torsion_orcaflex diff --git a/VALIDATION.md b/VALIDATION.md index ffa88d62..142f3d4f 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -407,6 +407,27 @@ scripts, results, and source provenance are in and pitch are 7.29e6 N·m/rad below the module-level 6×6 for both mooring modules. A run with no mooring and only a constant −6.084e6 N vertical load at the platform reference point (HydroDyn `AddF0`) reproduces this term, so it comes from ElastoDyn/glue code and not from the mooring module. + - *Linearisation of a line restrained in torsion* + ([`validation/scripts/openfast_lin_torsion.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_torsion.py), + same case): the twist angles of the free nodes and their rates are states, and the platform + rotation turns the End A frame. A straight, taut 100 m line (`GJ` 5e4 N·m², `Irn` 2 kg·m, 50 + elements, rigid in torsion at both ends) has torsional modes in the eigenvalues of `A` equal + to the lumped chain's `2 √(GJ/Irn)/h sin(nπ/2N)` to 5e-14. They lie −1.6e-4, −6.6e-4 and + −1.5e-3 below the continuum's `nπ/L √(GJ/Irn)`, the discretisation error. The fairlead moment + about the line per unit platform rotation about it, `D − C A⁻¹ B`, is `GJ/L` to 1.5e-14. The + feedthrough `D` alone is the end element's `GJ/lₑ`, fifty times more, which is what the + reduction would give without twist states. The lazy-wave cable of the mixed deck, twisted + 90° and alone (pinned in bending, rigid in torsion, 3470 states), matches the deck's own + static solutions to ≤4.9e-4. These are the moment about the End A director per unit + rotation about it (82.4268 / 82.4263 N·m/rad, from `Pretwist(A) ± 0.5°`), the forces and + that moment per unit fairlead translation, and the forces per unit rotation against the + reciprocal moment row. `tests/test_lin_torsion.f90` repeats the straight-line gates with the + shell's evaluation sequence on the aggregate. It adds the condensed torsion, an elastic + torsional end (`1/(L/GJ + 1/kₜ)`), and the platform's angular rates: `Bt/L` per unit angular + velocity and the held end section's `Irn lₑ/2` per unit angular acceleration. Under + linearisation the platform rotation is stepped by 1e-4 rad instead of 0.1 rad. On a straight + line with a 2e5 N·m/rad hang-off spring, this brings the force per unit rotation to 4e-8 of + the static solutions (6.8e-6 with 0.1 rad). The mooring-only A/B compares an all-chain system that both codes model in the same way; the finite-EI cable under coupled motion is compared with OrcaFlex in L4-1c. @@ -801,7 +822,7 @@ stop with a named error. | Correction iterations (`NumCrctn > 0`) | Pass verified | bit-identical to own `NumCrctn = 0` run | | SeaState wave/current kinematics | Pass verified | wave A/B ≤0.16% of range | | Checkpoint-restart (incl. Free/Connect points) | Pass verified | restarted window = continuous run to 0.0; also with supercycling (`dtM` > `DT`, the held SeaState fields and the predictor loads checkpointed): IEA-15 VolturnUS-S, turbulent wind and JONSWAP sea, `openfast -restart` at 50 s reproduces every later OpenFAST and `.CD.out` row of the chain mooring at `dtM` = 4 `DT` (extrapolated and held loads) and `DT`, and of the chain + 248-element power-cable mooring at `dtM` = 2 `DT`. A finite-EI cable also checkpoints its committed boundary (held DOFs, end-connection directions, vessel frame): before, the rebuild took its fairlead from the restored input mesh, which differs in the last bits, and on the IEA-15 mixed deck restarted at 6 s the lazy-wave cable's `.CD.out` channels drifted by up to 9.4e-7 (relative) within 4 s; now all rows to 10 s match bit for bit at `dtM` = `DT` and 2 `DT`, `NumCrctn` 0 and 1, and with a rigid fairlead END CONNECTIONS row | -| Linearisation | Pass verified (line dynamics) | line states as MoorDyn-F's (882 on the UMaine chains); zero-frequency reduction `D − C A⁻¹ B` compared entry by entry with stock MoorDyn's (full-precision `.lin` output): fairlead stiffness ≤0.10%, transverse `H/X` term 0.29%, platform 6×6 diagonals ≤0.10%; lowest nine line-mode frequencies 0.04–0.30%, both state matrices stable; a mixed deck with a lazy-wave power cable (2976 cable states) matches its own static solutions at every coupled point to ≤3.3e-4, also with a hang-off spring ([`openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)) | +| Linearisation | Pass verified (line dynamics) | line states as MoorDyn-F's (882 on the UMaine chains); zero-frequency reduction `D − C A⁻¹ B` compared entry by entry with stock MoorDyn's (full-precision `.lin` output): fairlead stiffness ≤0.10%, transverse `H/X` term 0.29%, platform 6×6 diagonals ≤0.10%; lowest nine line-mode frequencies 0.04–0.30%, both state matrices stable; a mixed deck with a lazy-wave power cable (2976 cable states) matches its own static solutions at every coupled point to ≤3.3e-4, also with a hang-off spring ([`openfast_lin_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_ab.py)); a line restrained in torsion adds its twist angles as states: the straight line's torsional modes equal the lumped chain's to 5e-14 and its roll stiffness `GJ/L` to 1.5e-14, and a twisted lazy wave matches its static solutions to ≤4.9e-4 ([`openfast_lin_torsion.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_torsion.py)) | | FAST.Farm shared moorings + clumps + channel record | Pass verified | 600 s A/B of the r-test `MD_Shared` farm against stock MoorDyn (same deck, analysis from 100 s; [`fastfarm_shared_ab.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/fastfarm_shared_ab.py)): tension means ≤0.02%, minima and maxima ≤0.25%, platform motions within millimetres and 0.001°; shared-line tension std 2.2–2.7% lower, 1.0% at half the mooring step (CableDyn's implicit step at the 0.05 s coupling step against MoorDyn's 1e-4 s explicit step). On the shared lines, which have no Fixed end, `FairTen`/`AnchTen` name the opposite ends from MoorDyn's (see the migration guide). MoorDyn's initial settling does not converge for the anchor legs 6 and 7 (2.4 m excess length at t = 0), a start-up transient over by 100 s that most likely set the 3% end of the earlier 60 s record | | Slack-line tension convention | Pass verified | tension-only dynamics; BA on slack lines matches `MoorDyn_Line.f90` | | Farm + restart / Farm + linearisation | Not applicable | FAST.Farm has no restart and does not call module linearisation; the same applies to stock MoorDyn | diff --git a/doc/capabilities.rst b/doc/capabilities.rst index 77f203d5..53d7337a 100644 --- a/doc/capabilities.rst +++ b/doc/capabilities.rst @@ -93,13 +93,12 @@ Line and constitutive capability torsional damping (``GJ|K|Bt``), with turning Rigid6 bodies, ``vesselMotion``/``vesselRAO`` and the ``motionFile`` roll column standalone, and with the platform orientation in coupled OpenFAST and FAST.Farm - runs (torque returned to the platform, ``PtfmInit``, checkpoints; see - :doc:`openfast`) and through the C API with the host's rotations - (``CableDyn_InitDeckRotating``, :doc:`capi`); ``Torq``/``Twist`` channels and standalone - range graphs. Stopped by name: the standalone mixed ``EI = 0`` + finite-EI aggregate and - ``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by translation only), - OpenFAST linearisation of a line restrained in torsion, - rod ends, bodies other than Rigid6, modal analysis, and + runs (torque returned to the platform, ``PtfmInit``, checkpoints, linearisation with the + twist angles as states; see :doc:`openfast`) and through the C API with the host's + rotations (``CableDyn_InitDeckRotating``, :doc:`capi`); ``Torq``/``Twist`` channels and + standalone range graphs. Stopped by name: the standalone mixed ``EI = 0`` + finite-EI + aggregate and ``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by + translation only), rod ends, bodies other than Rigid6, modal analysis, and ``False alpha_force_blend``. Not modelled: seabed friction against twist, anisotropic sections, self-contact of a loop (see :ref:`theory-torsion`) * - Hockling loops, nonlinear cross-section laws @@ -217,7 +216,7 @@ OpenFAST coverage The ``CompMooring = 5`` shell covers normal coupled time-domain stepping with its own ``dtM``, nonzero ``PtfmInit``, correction iterations, SeaState fields, checkpoint/restart, scoped -quasi-static ``dYdu`` linearisation, line failures, active-tension control of ``EI = 0`` lines +linearisation with the line dynamics, line failures, active-tension control of ``EI = 0`` lines (linear-elastic, viscoelastic or Syrope segments) and finite-EI cables, and FAST.Farm shared moorings. Restart and linearisation do not arise under FAST.Farm, which does not call those module operations, and active-tension control is rejected diff --git a/doc/driver_format.md b/doc/driver_format.md index a9890723..c32d44eb 100644 --- a/doc/driver_format.md +++ b/doc/driver_format.md @@ -811,8 +811,8 @@ Behaviour: - Connection moments are included in the OpenFAST coupled-load mesh. Rows on an `EI = 0` line, duplicate rows, unknown line ids, null directions, negative stiffnesses, -and non-finite values fail deck validation. OpenFAST linearisation with a platform-relative end -connection is rejected at initialisation. +and non-finite values fail deck validation. OpenFAST linearisation with a `Rigid` end connection +is rejected at initialisation. #### Torsion columns @@ -881,9 +881,10 @@ restrained end (one end included) in a standalone deck mixing `EI = 0` and finit without a body or through the C API's `CableDyn_InitDeck`/`InitDeckAt`, which move the line ends by translation only (`a line restrained in torsion needs a host that turns its fairlead frame ...`; with a body such a deck runs on the multibody route, which supports torsion, and a C -API host passes its rotations after `CableDyn_InitDeckRotating`), OpenFAST linearisation of a line -restrained in torsion, and a `Torq`/`Twist` channel on a line that is not restrained at both -ends. Seabed friction does not resist twist (the laid part of a line twists freely), and there +API host passes its rotations after `CableDyn_InitDeckRotating`), and a `Torq`/`Twist` channel +on a line that is not restrained at both ends. OpenFAST linearisation takes the twist angles as +states (as for any line, not with a `Rigid` bending connection). Seabed friction does not resist +twist (the laid part of a line twists freely), and there is no torque–tension coupling. ### EQUIVALENT BUOYANCY (optional) diff --git a/doc/openfast.rst b/doc/openfast.rst index cad5ffc3..37e6bcfe 100644 --- a/doc/openfast.rst +++ b/doc/openfast.rst @@ -267,10 +267,9 @@ channels ``AnchFz``, ``AnchFH`` and ``TDPGrd``) and units are in :doc:` - CableDyn-owned, always written: the static-equilibrium profile of every line, one row per node (arc length, coordinates, effective tension, curvature, bend moment, declination, inclination, azimuth) — the coupled range graph, at the state of the printed line summary - * - ``.CD.rst.dat``, ``.CD.lin.dat`` - - temporary CableDyn-owned copies of the deck, written in the ``MooringFile`` folder only - when a run restarts from a checkpoint or linearises (see *Lifecycle features*), and - removed after use + * - ``.CD.rst.dat`` + - temporary CableDyn-owned copy of the deck, written in the ``MooringFile`` folder only + when a run restarts from a checkpoint (see *Lifecycle features*), and removed after use With ``WrVTK > 0`` OpenFAST writes its VTK visualisation files as usual, but CableDyn provides no mooring or cable meshes to them, and says so at initialisation: the lines do not appear in the @@ -344,11 +343,11 @@ step the line may turn by more than 90° about its end direction, because the st substeps; an output probe moves the frame without a step, is limited to 90° from the committed twist, and stops by name beyond it (a restart first restores the checkpoint's twist, so it is not limited this way). Formal -linearisation of a line restrained in torsion fails during initialisation: the torque's -rotational stiffness has no column in the translation-only quasi-static reduction. The C API's -``CableDyn_InitDeck``/``InitDeckAt`` and the standalone deck that mixes ``EI = 0`` and finite-EI -lines without a body move the line ends by translation only and refuse torsion columns; a C API -host that initialises with ``CableDyn_InitDeckRotating`` passes its rotations (:doc:`capi`). +linearisation takes the line's twist angles as states and the platform rotation as an input +(see `Linearisation`_). The C API's ``CableDyn_InitDeck``/``InitDeckAt`` and the standalone +deck that mixes ``EI = 0`` and finite-EI lines without a body move the line ends by translation +only and refuse torsion columns; a C API host that initialises with +``CableDyn_InitDeckRotating`` passes its rotations (:doc:`capi`). Lifecycle features ------------------ @@ -365,18 +364,13 @@ without an auxiliary process: temporary deck copy, ``.CD.rst.dat``, beside the ``MooringFile``, rebuilds the model from it and removes it; files the deck names (``bathymetryFile``, a WaterKin file, Syrope tables) resolve against the ``MooringFile`` folder as in the original run. Keep restart files with the exact executable and complete input set. -* **Linearisation** publishes the quasi-static mooring load derivative at a committed boundary. - It rebuilds the model from a temporary deck copy, ``.CD.lin.dat``, written beside the - ``MooringFile`` and removed after use, so side files resolve as on restart. Set ``dtM = DT`` and linearise at the initial - operating point (``CalcSteady = False``, +* **Linearisation** differentiates the line dynamics at the committed state (`Linearisation`_). + Set ``dtM = DT`` and linearise at the initial operating point (``CalcSteady = False``, ``LinTimes = 0``, platform at its still-water equilibrium, rotor speed and pitch at their steady values). Contact switching makes derivatives near touchdown non-smooth. OpenFAST writes the ``.lin`` matrices in the ``.fst`` ``OutFmt``; to compare them with MoorDyn's ``D - C A^-1 B``, use a full-precision format such as ``"ES24.15E3"``, because the usual - 4-digit format cannot resolve that reduction. A deck with - Rigid6 bodies, rods or ``Point3`` buoys is rejected at initialisation: the quasi-static - reduction would hold them at their deck pose instead of re-solving their equilibrium (a - ``Free`` point with the buoy's ``Mass``, ``Vol``, ``CdA`` and ``Ca`` is re-solved). + 4-digit format cannot resolve that reduction. * **FAST.Farm** selects CableDyn with ``Mod_SharedMooring = 5`` for shared lines and connections. Gravity, water density, depth, and ``TMax`` are host-owned and must agree across turbines, otherwise initialisation fails. @@ -453,6 +447,17 @@ Positions, tangents and coupled-point displacements are stepped by 1 µm, which seabed penetration of a light cable and the stretch of every taut element. Velocities are stepped by 0.1 m/s, MoorDyn-F's step. +A line restrained in torsion adds the twist angle of every node that its end frames do not hold +(all nodes but a torsionally ``Rigid`` end), after the cables' positions and tangents, and their +rates after the cables' velocities: ``Cable 1 node 2 twist, rad`` and ``Cable 1 node 2 twist +rate, rad/s``. The angles' accelerations come from the same evaluation as the cable's, with their +polar inertia ``Irn``. The coupled point's orientation turns the line's End A frame, so a platform +rotation twists the line; the point's angular velocity and acceleration turn the frame too, for the +torsional damping ``Bt`` and the held end section's polar inertia. The fairlead moment carries the +torque. Angles are stepped by 1 µrad and their rates by 0.01 rad/s, both of which enter linearly; the +coupled-point rotation is stepped by 1e-4 rad (a rotation moves no node, so no contact or slack +limits it, and the turn of an end frame or connection direction is nonlinear). + The zero-frequency reduction ``D − C A⁻¹ B`` is the static mooring stiffness. It agrees with MoorDyn-F and with CableDyn's own static solutions (:doc:`validation`). Quadratic drag has no slope at rest, so the 0.1 m/s step gives its equivalent linear damping at that velocity amplitude. @@ -469,9 +474,9 @@ stick anchors (a stuck laid run). Linearise from a settled operating point, such start at ``t = 0``. Initialisation fails with a named message for Free and Connect points, Point3 buoys, Rigid6 bodies -and rods, a line restrained in torsion, a line with VIV (``Cl > 0``: it oscillates about a lock-in -cycle, not an equilibrium), a ``CONTROL`` section, a cable with a ``Rigid`` end connection, and -FAST.Farm. Their states are not linearisation states. Time-domain runs support all of them. +and rods, a line with VIV (``Cl > 0``: it oscillates about a lock-in cycle, not an equilibrium), a +``CONTROL`` section, a cable with a ``Rigid`` end connection, and FAST.Farm. Their states are not +linearisation states. Time-domain runs support all of them. Performance ----------- diff --git a/doc/outputs.rst b/doc/outputs.rst index 31dc068e..c52645e9 100644 --- a/doc/outputs.rst +++ b/doc/outputs.rst @@ -985,10 +985,10 @@ output root: selected * - ``.FarmCD.static.out`` / ``.FarmCD.out`` - the same two files for a FAST.Farm run, named from the FAST.Farm output root - * - ``.CD.rst.dat`` / ``.CD.lin.dat`` - - temporary copies of the CableDyn deck, written in the ``MooringFile`` folder when a run - restarts from a checkpoint or linearises; the module rebuilds its model from them and - removes them after use (see :doc:`openfast`) + * - ``.CD.rst.dat`` + - temporary copy of the CableDyn deck, written in the ``MooringFile`` folder when a run + restarts from a checkpoint; the module rebuilds its model from it and removes it after use + (see :doc:`openfast`) ``.CD.out`` layout — note that it differs from the standalone ``.out``: diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index b9bb2e23..96a201fc 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -403,9 +403,6 @@ Torsion ``CableDyn_InitDeckRotating`` and pass the host's rotations, add a body (such a deck runs on the multibody route, which supports torsion), or set ``TorsStiffness Free`` in every ``END CONNECTIONS`` row. - * - ``formal OpenFAST linearization of a line restrained in torsion is not supported`` - - linearise the model with ``TorsStiffness Free``; the twist and the torque carry no - linearisation state. * - ``torsion: the twist would move more than pi/2 from its committed value`` - the host turned a fairlead by more than 90° about the line's end direction without a step (an output probe or a non-stepping input update). Keep the platform turn per diff --git a/src/CableDyn_OpenFAST_HermiteFMF.f90 b/src/CableDyn_OpenFAST_HermiteFMF.f90 index 55be3705..ee92d5d0 100644 --- a/src/CableDyn_OpenFAST_HermiteFMF.f90 +++ b/src/CableDyn_OpenFAST_HermiteFMF.f90 @@ -74,6 +74,7 @@ MODULE CableDyn_OpenFAST_HermiteFMF PUBLIC :: CD_HFMF_Set_EndConnection PUBLIC :: CD_HFMF_Set_Torsion PUBLIC :: CD_HFMF_Refresh_Acceleration + PUBLIC :: CD_HFMF_Twist_Lin_Count, CD_HFMF_Twist_Lin_Slots, CD_HFMF_Set_Twist_Frame_Rates PUBLIC :: CD_HFMF_NNodes PUBLIC :: CD_HFMF_GetNodePositions PUBLIC :: CD_HFMF_UpdateStates @@ -1274,6 +1275,77 @@ SUBROUTINE CD_HFMF_Refresh_Acceleration(self, ErrStat, ErrMsg) END IF END SUBROUTINE CD_HFMF_Refresh_Acceleration + INTEGER FUNCTION CD_HFMF_Twist_Lin_Count(self) RESULT(n) + !! Number of the cable's nodal-twist linearisation states of one kind: the free twist angles, + !! at every node but a torsionally rigid end (whose angle is held). Zero without torsion and + !! for the condensed torsion, whose torque M = (Phi - Theta(q))/C is an algebraic function of + !! the configuration and the end frames with no state of its own. + TYPE(CD_HFMF_ModuleType), INTENT(IN) :: self + n = 0 + IF (.NOT. self%initialized) RETURN + IF (.NOT. self%line%tw_active) RETURN + n = COUNT(self%line%tw_free) + END FUNCTION CD_HFMF_Twist_Lin_Count + + SUBROUTINE CD_HFMF_Twist_Lin_Slots(self, phi_slot, rate_slot, acc_slot, node, ErrStat, ErrMsg) + !! The slots, 1-based in this cable's CD_HFMF_PackMirror buffer, of the free twist angles phi, + !! their rates and their accelerations, with their model nodes (End B = node 1), in node order; + !! each array is sized CD_HFMF_Twist_Lin_Count. Angles, rates and accelerations are the first + !! three nn-blocks of the nodal-twist tail that closes the torsion block + !! (CD_HermiteCable_Dyn_Twist_Pack), so the slots of the free nodes are consecutive. + TYPE(CD_HFMF_ModuleType), INTENT(IN) :: self + INTEGER, INTENT(OUT) :: phi_slot(:), rate_slot(:), acc_slot(:), node(:) + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + INTEGER :: k0, i, k, n + ErrStat = CD_HFMF_OK + ErrMsg = '' + phi_slot = 0 + rate_slot = 0 + acc_slot = 0 + node = 0 + n = CD_HFMF_Twist_Lin_Count(self) + IF (SIZE(phi_slot) /= n .OR. SIZE(rate_slot) /= n .OR. SIZE(acc_slot) /= n .OR. SIZE(node) /= n) THEN + ErrStat = CD_HFMF_BADINPUT + ErrMsg = 'CD_HFMF_Twist_Lin_Slots: the slot arrays must be sized CD_HFMF_Twist_Lin_Count' + RETURN + END IF + IF (n == 0) RETURN + k0 = CD_HFMF_MirrorSize(self) - CD_HermiteCable_Dyn_Twist_Mirror_Size(self%line) + k = 0 + DO i = 1, self%line%nn + IF (.NOT. self%line%tw_free(i)) CYCLE + k = k + 1 + phi_slot(k) = k0 + i + rate_slot(k) = k0 + self%line%nn + i + acc_slot(k) = k0 + 2*self%line%nn + i + node(k) = i + END DO + END SUBROUTINE CD_HFMF_Twist_Lin_Slots + + SUBROUTINE CD_HFMF_Set_Twist_Frame_Rates(self, ErrStat, ErrMsg) + !! Linearisation of the nodal twist: give the parent-attached end frame the angular velocity + !! and acceleration of the parent last written (CD_HFMF_SetCoupledKinematics), the rates a + !! time step takes from the frame's turn over the step (tw_om, tw_oal of the committed step). + !! The frame turns rigidly with the parent, so its rates are the parent's, here in the solve + !! frame. With them the torsional damping of the element at a rigid end takes the frame's + !! turning rate, (Bt/l0) drho/dw . omega, and the reaction moment the polar inertia of the held + !! end section, as in the march; without them a linearisation would hold both at the committed + !! rates. A no-op without the nodal twist or a parent-attached frame. The caller restores the + !! committed rates with the mirror (CD_HFMF_UnpackMirror). + TYPE(CD_HFMF_ModuleType), INTENT(INOUT) :: self + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + ErrStat = CD_HFMF_OK + ErrMsg = '' + IF (.NOT. self%initialized) THEN + ErrStat = CD_HFMF_BADINPUT; ErrMsg = 'CD_HFMF_Set_Twist_Frame_Rates: module not initialised'; RETURN + END IF + IF (.NOT. (self%tors_parent .AND. self%line%tw_active)) RETURN + self%line%tw_om(:, self%tors_index) = frame_to_local(self, self%parent_omega) + self%line%tw_oal(:, self%tors_index) = frame_to_local(self, self%parent_alpha) + END SUBROUTINE CD_HFMF_Set_Twist_Frame_Rates + INTEGER FUNCTION CD_HFMF_NNodes(self) RESULT(n) !! Node count of the owned cable (the held-fluid sampling surface). Zero if !! uninitialised. diff --git a/src/openfast/CableDyn_OF.f90 b/src/openfast/CableDyn_OF.f90 index 01d7957a..e56f7910 100644 --- a/src/openfast/CableDyn_OF.f90 +++ b/src/openfast/CableDyn_OF.f90 @@ -55,10 +55,12 @@ MODULE CableDyn !! deck + state mirror, accepted on committed mooring-interval boundaries), !! linearization with the line dynamics (as MoorDyn-F: the continuous states are the !! EI=0 lines' interior-node positions and the finite-EI cables' free DOFs, positions - !! and tangents, then their velocities, and the rope models' constitutive states; A, B, C - !! and D by central differences of lin_eval, the accelerations and state rates evaluated - !! at the perturbed state; Free/Connect points, VIV lines, bodies, rods, Point3 buoys, - !! torsion, CONTROL and rigid cable ends fail closed), and + !! and tangents, and the free twist angles of a cable restrained in torsion, then their + !! velocities, and the rope models' constitutive states; A, B, C and D by central + !! differences of lin_eval, the accelerations and state rates evaluated at the perturbed + !! state; the coupled-point orientation turns a torsion end frame and the fairlead moment + !! carries the torque; Free/Connect points, VIV lines, bodies, rods, Point3 buoys, CONTROL + !! and rigid cable ends fail closed), and !! FAST.Farm farm-level moorings (FarmSize > 0: Turbine decks, !! per-turbine coupled meshes, shared lines; still-water hydro; farm restart and !! farm linearization fail closed with named messages). Checkpoint restart re-parses a @@ -99,7 +101,9 @@ MODULE CableDyn USE CableDyn_OpenFAST_HermiteFMF, ONLY: CD_HFMF_MirrorSize, CD_HFMF_PackMirror, CD_HFMF_UnpackMirror, & CD_HFMF_FrictionMirrorSize, CD_HFMF_BoundaryMirrorSize, & CD_HFMF_ForceMirrorSize, CD_HFMF_TorsionMirrorSize, CD_HFMF_VIVMirrorSize, & - CD_HFMF_Refresh_Acceleration, CD_HFMF_OK + CD_HFMF_Refresh_Acceleration, CD_HFMF_OK, & + CD_HFMF_Twist_Lin_Count, CD_HFMF_Twist_Lin_Slots, & + CD_HFMF_Set_Twist_Frame_Rates USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCable_Dyn_Reset_Profile, & CD_HermiteCable_Dyn_Disable_Profile, & CD_HermiteCable_Dyn_Get_Profile, & @@ -853,16 +857,9 @@ SUBROUTINE CD_Init(InitInp, u, p, x, xd, z, other, y, m, DTcoupling, InitOut, Er ErrStat, ErrMsg, RoutineName ) RETURN END IF - ! a line restrained in torsion returns a torque moment that turns with the platform - ! even at a bending-pinned end: its rotational stiffness a a^T / C has no column in - ! the translation-only reduction either - IF (Inst(id)%agg%cables(ic)%line%torsion%active) THEN - CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: formal OpenFAST linearization '// & - 'of a line restrained in torsion is not supported: its condensed torque '// & - 'carries no state of its own (set TorsStiffness Free to linearize).', & - ErrStat, ErrMsg, RoutineName ) - RETURN - END IF + ! (a line restrained in torsion linearises: its free twist angles and their rates + ! are states, lin_state_map, and the coupled-point orientation of the input turns its + ! End A frame; a condensed torsion's torque follows q and the frames, see lin_eval) END DO END IF CALL CD_AGG_GetInitMetadata( Inst(id)%agg, nreportlines, npoints, nsections, nei0, nfinite, es, em ) @@ -2713,16 +2710,17 @@ END SUBROUTINE CD_CalcContStateDeriv !---------------------------------------------------------------------------------------------------------------------------------- SUBROUTINE lin_state_map( inst_e, m, ErrStat, ErrMsg ) !! The x%states mirror slots of the linearization states (CD_InitVars under Linearize): for - !! every interior DOF of an EI = 0 line and every free DOF of a finite-EI cable, the slot of - !! its position, of its velocity and of its acceleration (lin_pos, lin_vel, lin_acc), and the - !! mirror buffers of lin_eval. + !! every interior DOF of an EI = 0 line, every free DOF of a finite-EI cable and every free + !! twist angle of a cable restrained in torsion, the slot of its position, of its velocity + !! and of its acceleration (lin_pos, lin_vel, lin_acc), and the mirror buffers of lin_eval. TYPE(CD_OF_Instance), INTENT(INOUT) :: inst_e TYPE(CD_MiscVarType), INTENT(IN) :: m INTEGER(IntKi), INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg - INTEGER(IntKi) :: il, ic, ndofl, nin, nf, csz, koff, n, k, j, es, n1, k1, kind + INTEGER(IntKi) :: il, ic, ndofl, nin, nf, csz, koff, n, k, j, es, n1, k1, kind, ntw CHARACTER(ErrMsgLen) :: em LOGICAL, ALLOCATABLE :: mask(:) + INTEGER, ALLOCATABLE :: tw_p(:), tw_r(:), tw_a(:), tw_n(:) ErrStat = ErrID_None ErrMsg = '' @@ -2736,7 +2734,7 @@ SUBROUTINE lin_state_map( inst_e, m, ErrStat, ErrMsg ) END DO DO ic = 1, inst_e%agg%ncable IF (CD_HFMF_MirrorSize( inst_e%agg%cables(ic) ) <= 0) CYCLE - n = n + COUNT(inst_e%agg%cables(ic)%line%freemask) + n = n + COUNT(inst_e%agg%cables(ic)%line%freemask) + CD_HFMF_Twist_Lin_Count( inst_e%agg%cables(ic) ) END DO ! the constitutive states: every viscoelastic and Syrope element, the per-element tail ! after the line's interior block (as pack_state_mirror) @@ -2801,6 +2799,31 @@ SUBROUTINE lin_state_map( inst_e, m, ErrStat, ErrMsg ) END DO koff = koff + csz END DO + ! the nodal twist of a cable restrained in torsion: each free node's angle phi, its rate and + ! its acceleration, in the cable's torsion tail (CD_HFMF_Twist_Lin_Slots) + koff = 0 + IF (inst_e%nlines > 0) koff = m%LineStateIsN(inst_e%nlines) + DO ic = 1, inst_e%agg%ncable + csz = CD_HFMF_MirrorSize( inst_e%agg%cables(ic) ) + IF (csz <= 0) CYCLE + ntw = CD_HFMF_Twist_Lin_Count( inst_e%agg%cables(ic) ) + IF (ntw > 0) THEN + ALLOCATE (tw_p(ntw), tw_r(ntw), tw_a(ntw), tw_n(ntw)) + CALL CD_HFMF_Twist_Lin_Slots( inst_e%agg%cables(ic), tw_p, tw_r, tw_a, tw_n, es, em ) + IF (es /= CD_HFMF_OK) THEN + CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))//': '// & + TRIM(em), ErrStat, ErrMsg, 'lin_state_map' ); RETURN + END IF + DO j = 1, ntw + k = k + 1 + inst_e%lin_pos(k) = koff + tw_p(j) + inst_e%lin_vel(k) = koff + tw_r(j) + inst_e%lin_acc(k) = koff + tw_a(j) + END DO + DEALLOCATE (tw_p, tw_r, tw_a, tw_n) + END IF + koff = koff + csz + END DO inst_e%lin_states = .TRUE. CONTAINS @@ -2907,7 +2930,11 @@ SUBROUTINE lin_eval( id, p, m, u, x_in, ErrStat, ErrMsg, dxdt, y_out ) CALL restore; RETURN END IF ! the input: the coupled points move to u, and the accelerations follow (the EI = 0 lines - ! in the non-probe update, the cables by their refresh) + ! in the non-probe update, the cables by their refresh). The orientation of a cable's + ! coupled point turns its parent-attached torsion end frame (CD_HFMF_SetCoupledKinematics): + ! the condensed torque (Phi - Theta)/C and a nodal twist's end element are then evaluated + ! with the turned frame, and the frame takes the point's angular velocity and acceleration + ! (CD_HFMF_Set_Twist_Frame_Rates: the torsional damping and the held section's inertia) CALL mesh_to_arrays( u%CoupledKinematics(1), Inst(id)%ncp, Inst(id)%ws_pos, Inst(id)%ws_vel, & Inst(id)%ws_acc, Inst(id)%ws_orient, Inst(id)%ws_omega, Inst(id)%ws_alpha, & ErrStat2, ErrMsg2 ) @@ -2923,7 +2950,8 @@ SUBROUTINE lin_eval( id, p, m, u, x_in, ErrStat, ErrMsg, dxdt, y_out ) CALL restore; RETURN END IF DO ic = 1, Inst(id)%agg%ncable - CALL CD_HFMF_Refresh_Acceleration( Inst(id)%agg%cables(ic), es, em ) + CALL CD_HFMF_Set_Twist_Frame_Rates( Inst(id)%agg%cables(ic), es, em ) + IF (es == CD_HFMF_OK) CALL CD_HFMF_Refresh_Acceleration( Inst(id)%agg%cables(ic), es, em ) IF (es /= CD_HFMF_OK) THEN CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))// & ' acceleration: '//TRIM(em), ErrStat, ErrMsg, RoutineName ) @@ -3504,17 +3532,31 @@ SUBROUTINE CD_InitVars(Vars, u, p, x, y, m, inst_, Linearize, ErrStat, ErrMsg) ! the constitutive states: a viscoelastic slow-branch stretch (m) takes the position step, ! a Syrope slow strain the strain of a micrometre over a metre REAL(R8Ki), PARAMETER :: LIN_DSLOW = 1.0E-6_R8Ki + ! the nodal twist: an angle enters the element twists and torques linearly, so the angle + ! step takes the position step's 1e-6 (rad), and its rate only the linear torsional + ! damping, so any rate step is exact up to round-off: 0.01 rad/s + REAL(R8Ki), PARAMETER :: LIN_DPHI = 1.0E-6_R8Ki, LIN_DW = 1.0E-2_R8Ki + ! the coupled-point rotation step under linearization: a rotation moves no node, so + ! neither contact nor slack constrains it, and the turn of a torsion end frame about axes + ! across its director (a solid angle) or of an end connection's direction is nonlinear: + ! 1e-4 rad keeps the central difference's O(h^2) error near 1e-9 and the difference of the + ! moments and accelerations some eight digits above round-off (the time-domain input + ! Jacobian keeps 0.1 rad) + REAL(R8Ki), PARAMETER :: LIN_DROT = 1.0E-4_R8Ki LOGICAL, ALLOCATABLE :: lin1m(:) - INTEGER(IntKi) :: kind1 + INTEGER(IntKi) :: kind1, ntw + INTEGER, ALLOCATABLE :: tw_p(:), tw_r(:), tw_a(:), tw_n(:) INTEGER(IntKi) :: ipass, nnc, inode, ikind, i0, nrun, icomp, k ! the position step of the line states and the coupled-point displacement step of the ! inputs under linearization (lin_disp_step), and a cable's tangent-rate step - REAL(R8Ki) :: dx_pos, dx_u, dtr + REAL(R8Ki) :: dx_pos, dx_u, dtr, dx_rot ErrStat = ErrID_None ErrMsg = '' dx_u = 0.05_R8Ki + dx_rot = 0.1_R8Ki IF (Linearize) THEN + dx_rot = LIN_DROT dx_u = LIN_DX CALL lin_disp_step( inst_, dx_u, ErrStat2, ErrMsg2 ) CALL SetErrStat( ErrStat2, ErrMsg2, ErrStat, ErrMsg, RoutineName ) @@ -3525,8 +3567,9 @@ SUBROUTINE CD_InitVars(Vars, u, p, x, y, m, inst_, Linearize, ErrStat, ErrMsg) IF (Linearize) THEN ! Linearization with the line dynamics, as MoorDyn-F: the continuous states are the ! positions of every EI = 0 line's interior nodes and of every finite-EI cable's free - ! DOFs (node positions r and tangents m = dr/ds), then their velocities, held in the - ! x%states mirror slots (lin_state_map), and the per-element constitutive states of the + ! DOFs (node positions r and tangents m = dr/ds) and the free twist angles phi of a + ! cable restrained in torsion, then their velocities, held in the x%states mirror slots + ! (lin_state_map), and the per-element constitutive states of the ! viscoelastic and Syrope ropes as first-order states. The acceleration and the other ! mirror blocks are not registered: the glue would take every registered x as a state. ALLOCATE (Vars%x(0), STAT=ErrStat2) @@ -3624,6 +3667,56 @@ SUBROUTINE CD_InitVars(Vars, u, p, x, y, m, inst_, Linearize, ErrStat, ErrMsg) END DO koff = koff + csz END DO + ! the nodal twist of every cable restrained in torsion, after the cables' r and m: + ! the angles phi of its free nodes (every node but a torsionally rigid end), then in + ! the second pass their rates, one consecutive run per cable (CD_HFMF_Twist_Lin_Slots) + koff = 0 + IF (inst_%nlines > 0) koff = m%LineStateIsN(inst_%nlines) + DO ic = 1, inst_%agg%ncable + csz = CD_HFMF_MirrorSize( inst_%agg%cables(ic) ) + IF (csz <= 0) CYCLE + ntw = CD_HFMF_Twist_Lin_Count( inst_%agg%cables(ic) ) + IF (ntw > 0) THEN + nnc = inst_%agg%cables(ic)%line%nn + ALLOCATE (tw_p(ntw), tw_r(ntw), tw_a(ntw), tw_n(ntw), CblLinPos(ntw), STAT=ErrStat2) + IF (ErrStat2 /= 0) THEN + CALL SetErrStat( ErrID_Fatal, 'Could not allocate cable twist lin-name work arrays.', & + ErrStat, ErrMsg, RoutineName ); RETURN + END IF + CALL CD_HFMF_Twist_Lin_Slots( inst_%agg%cables(ic), tw_p, tw_r, tw_a, tw_n, es, em ) + IF (es /= CD_HFMF_OK) THEN + CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))// & + ': '//TRIM(em), ErrStat, ErrMsg, RoutineName ); RETURN + END IF + ! one variable per cable and kind needs one consecutive run of mirror slots + IF (tw_p(ntw) - tw_p(1) /= ntw - 1 .OR. tw_r(ntw) - tw_r(1) /= ntw - 1) THEN + CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))// & + ': the free twist angles are not consecutive in the state mirror.', & + ErrStat, ErrMsg, RoutineName ); RETURN + END IF + ! the node named End A first, as the channels and the cable's r and m states + DO j = 1, ntw + LinStr = 'Cable '//TRIM(Num2LStr(ic))//' node '//TRIM(Num2LStr(nnc + 1 - tw_n(j))) + IF (ipass == 1) THEN + CblLinPos(j) = TRIM(LinStr)//' twist, rad' + ELSE + CblLinPos(j) = TRIM(LinStr)//' twist rate, rad/s' + END IF + END DO + LinStr = 'Cable '//TRIM(Num2LStr(ic))//' twist' + IF (ipass == 1) THEN + CALL MV_AddVar( Vars%x, LinStr, FieldScalar, DatLoc(CD_x_states), & + iAry=koff + tw_p(1), Num=ntw, Flags=VF_DerivOrder2, DerivOrder=0, & + Perturb=LIN_DPHI, LinNames=CblLinPos ) + ELSE + CALL MV_AddVar( Vars%x, TRIM(LinStr)//' rate', FieldScalar, DatLoc(CD_x_states), & + iAry=koff + tw_r(1), Num=ntw, Flags=VF_DerivOrder2, DerivOrder=1, & + Perturb=LIN_DW, LinNames=CblLinPos ) + END IF + DEALLOCATE (tw_p, tw_r, tw_a, tw_n, CblLinPos) + END IF + koff = koff + csz + END DO END DO ! the per-element constitutive states of the EI = 0 lines, first-order states: the ! viscoelastic slow-branch stretch dl_1 and the Syrope slow strain (the Syrope running @@ -4029,7 +4122,7 @@ SUBROUTINE CD_InitVars(Vars, u, p, x, y, m, inst_, Linearize, ErrStat, ErrMsg) DatLoc(CD_u_CoupledKinematics, ivT), & Mesh=u%CoupledKinematics(ivT), & Perturbs=[dx_u, & ! FieldTransDisp - 0.1_R8Ki, & ! FieldOrientation + dx_rot, & ! FieldOrientation 0.1_R8Ki, & ! FieldTransVel 0.1_R8Ki, & ! FieldAngularVel 0.1_R8Ki, & ! FieldTransAcc diff --git a/tests/test_lin_torsion.f90 b/tests/test_lin_torsion.f90 new file mode 100644 index 00000000..efd33dd4 --- /dev/null +++ b/tests/test_lin_torsion.f90 @@ -0,0 +1,586 @@ +! File: tests/test_lin_torsion.f90 +! SPDX-License-Identifier: Apache-2.0 +! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +PROGRAM test_lin_torsion + !! OpenFAST linearisation of a cable restrained in torsion, on the aggregate surface the OpenFAST + !! shell drives: the shell's lin_eval recipe (the mirror loaded with a perturbed state, the + !! coupled point moved to a perturbed input, the parent's rates given to the torsion end frame + !! (CD_HFMF_Set_Twist_Frame_Rates), the accelerations solved without a time step, the mirror + !! restored), the linearisation states of the nodal twist from CD_HFMF_Twist_Lin_Slots, and A, B, + !! C and D by central differences as CD_JacobianPContState and CD_JacobianPInput form them. The + !! line is a straight, neutrally buoyant 100 m cable held taut at 0.5 % strain between a coupled + !! fairlead (0, 0, -20) and a fixed anchor below it, pinned in bending and rigid in torsion at + !! both ends, GJ = 5e4 N m^2, 50 elements. + !! F torsional modes: with Irn = 2 kg m the twist block of A is decoupled from the line's + !! position and tangent states (its coupling entries vanish to the differences' round-off), + !! so its eigenvalues are eigenvalues of A: the frequencies of the first three twist modes + !! are n pi/L sqrt(GJ/Irn) of the continuum, within the lumped-inertia discretisation + !! error, and the lumped chain's own 2 sqrt(GJ/Irn)/h sin(n pi/(2N)) to 1e-6; + !! K roll stiffness: the zero-frequency reduction -(D - C A^-1 B) of the fairlead moment about + !! the line axis per unit platform rotation about it is GJ/L (to 1e-6), with the twist + !! angles as states; the feedthrough D alone (the interior twist held, as a linearisation + !! without twist states would give it) is the end element's GJ/l_e, N times too stiff; + !! C condensed torsion (the same line without Irn, its torque algebraic in q and the end + !! frames, no states of its own): the reduction gives GJ/L as well; + !! E an elastic torsional end (spring kt at End B): its end angle is a state too, and the + !! reduction gives the series stiffness 1/(L/GJ + 1/kt); + !! R frame rates: with the torsional damping Bt (GJ|0|Bt) the reduced moment per unit angular + !! velocity of the platform about the line axis is Bt/L, the steady-roll torque of the + !! march (test_nodal_twist_dynamic D), and it vanishes without the frame rates; the moment + !! per unit angular acceleration is the held end section's polar inertia Irn l_e/2. + USE CableDyn_Precision, ONLY: wp + USE CableDyn_OpenFAST_Aggregate, ONLY: CD_AGG_ModuleType, CD_AGG_Init_From_Deck, CD_AGG_NMovingPoints, & + CD_AGG_GetMovingPointMesh, CD_AGG_UpdateStates_Moving, & + CD_AGG_CalcOutput, CD_AGG_End, CD_AGG_OK + USE CableDyn_OpenFAST_HermiteFMF, ONLY: CD_HFMF_MirrorSize, CD_HFMF_PackMirror, CD_HFMF_UnpackMirror, & + CD_HFMF_Refresh_Acceleration, CD_HFMF_Set_Torsion, & + CD_HFMF_Twist_Lin_Count, CD_HFMF_Twist_Lin_Slots, & + CD_HFMF_Set_Twist_Frame_Rates, CD_HFMF_OK + USE CableDyn_HermiteTorsion, ONLY: CD_HermiteTorsionType + IMPLICIT NONE + + REAL(wp), PARAMETER :: PI = 3.14159265358979323846_wp, RHOW = 1025.0_wp, DT = 0.05_wp + REAL(wp), PARAMETER :: GJ = 5.0e4_wp, L = 100.0_wp, IRN = 2.0_wp, BT = 1.0e3_wp + INTEGER, PARAMETER :: NE = 50 + ! the linearisation steps of the OpenFAST shell (CD_InitVars): positions, tangents and twist + ! angles 1e-6, velocities 0.1 m/s (tangent rates 0.1 m/s over the element length), twist rates + ! 0.01 rad/s, rotations 1e-4 rad, angular velocities and accelerations 0.1 + REAL(wp), PARAMETER :: HX = 1.0e-6_wp, HV = 0.1_wp, HW = 1.0e-2_wp, HROT = 1.0e-4_wp, HOM = 0.1_wp + INTEGER :: nfail = 0 + + ! the shell's state of one cable: [r, m free; phi free; their rates], mirror slots and buffers + TYPE(CD_AGG_ModuleType) :: agg + INTEGER :: nf, ntw, nx2, msz + INTEGER, ALLOCATABLE :: q_slot(:), v_slot(:), a_slot(:), tp(:), tr(:), ta(:), tn(:) + REAL(wp), ALLOCATABLE :: buf0(:), wbuf(:) + REAL(wp) :: pos0(3, 1), vel0(3, 1), acc0(3, 1), t0 + + CALL check_modes_and_stiffness() + CALL check_condensed() + CALL check_elastic_end() + CALL check_frame_rates() + + IF (nfail > 0) THEN + WRITE (*, '(A,I0,A)') 'FAIL: ', nfail, ' assertion(s) failed' + ERROR STOP 1 + END IF + WRITE (*, '(A)') 'PASS: linearisation of a line restrained in torsion (modes, roll stiffness, condensed, '// & + 'elastic end, frame rates)' + +CONTAINS + + SUBROUTINE require(cond, label) + LOGICAL, INTENT(IN) :: cond + CHARACTER(*), INTENT(IN) :: label + IF (cond) RETURN + nfail = nfail + 1 + WRITE (*, '(A)') 'FAIL: '//TRIM(label) + END SUBROUTINE require + + SUBROUTINE write_deck(path, irn_v, bt_v, tors_b) + !! The straight vertical line, neutrally buoyant (mass rhoW pi d^2/4) and without drag or + !! added mass, so the 0.5 % strain is uniform; Irn irn_v, torsional damping bt_v, and the + !! torsional restraint of End B tors_b (default Rigid). + CHARACTER(*), INTENT(IN) :: path + REAL(wp), INTENT(IN) :: irn_v, bt_v + CHARACTER(*), INTENT(IN), OPTIONAL :: tors_b + INTEGER :: u + CHARACTER(240) :: ltype + CHARACTER(40) :: gj_col + gj_col = '5.0e4' + IF (bt_v > 0.0_wp) WRITE (gj_col, '(A,ES10.4)') '5.0e4|0|', bt_v + WRITE (ltype, '(A,ES24.16,A,A,A,ES12.5,A)') 'cab 0.2 ', RHOW*0.25_wp*PI*0.04_wp, & + ' 1.0e7 0.0 1.0e6 1.0e8 ', TRIM(gj_col), ' 1.0 ', irn_v, ' 0.0 0.0 0.0 0.0' + OPEN (NEWUNIT=u, FILE=path, STATUS='REPLACE', ACTION='WRITE') + WRITE (u, '(A)') 'linearisation of a line restrained in torsion' + WRITE (u, '(A)') '--- LINE TYPES ---' + WRITE (u, '(A)') 'Name Diam Mass EA BA EI GAs GJ Irt Irn Cdn Cdt Can Cat' + WRITE (u, '(A)') '(-) (m) (kg/m) (N) (-) (Nm2) (N) (Nm2) (kgm) (kgm) (-) (-) (-) (-)' + WRITE (u, '(A)') TRIM(ltype) + WRITE (u, '(A)') '--- POINTS ---' + WRITE (u, '(A)') 'ID Type X Y Z Mass Vol CdA Ca' + WRITE (u, '(A)') '(-) (-) (m) (m) (m) (kg) (m3) (m2) (-)' + WRITE (u, '(A)') '1 Coupled 0.0 0.0 -20.0 0 0 0 0' + WRITE (u, '(A)') '2 Fixed 0.0 0.0 -120.5 0 0 0 0' + WRITE (u, '(A)') '--- LINES ---' + WRITE (u, '(A)') 'ID NodeA NodeB Outputs' + WRITE (u, '(A)') '(-) (-) (-) (-)' + WRITE (u, '(A)') '1 1 2 -' + WRITE (u, '(A)') '--- SECTIONS ---' + WRITE (u, '(A)') 'LineID LineType Length NumSegs' + WRITE (u, '(A)') '(-) (-) (m) (-)' + WRITE (u, '(A,I0)') '1 cab 100.0 ', NE + WRITE (u, '(A)') '--- END CONNECTIONS ---' + WRITE (u, '(A)') 'LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist' + WRITE (u, '(A)') '(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg)' + WRITE (u, '(A)') '1 A Pinned 0 0 -1 Rigid 1 0 0 0' + IF (PRESENT(tors_b)) THEN + WRITE (u, '(A)') '1 B Pinned 0 0 -1 '//tors_b//' 1 0 0 0' + ELSE + WRITE (u, '(A)') '1 B Pinned 0 0 -1 Rigid 1 0 0 0' + END IF + WRITE (u, '(A)') '--- OPTIONS ---' + WRITE (u, '(A)') '9.80665 g' + WRITE (u, '(A)') '1025.0 rhoW' + WRITE (u, '(A)') '0.05 dtM' + WRITE (u, '(A)') '--- OUTPUTS ---' + WRITE (u, '(A)') 'Torq1N1' + WRITE (u, '(A)') '--- END ---' + CLOSE (u) + END SUBROUTINE write_deck + + SUBROUTINE setup(path, ok) + !! Build the aggregate (host orientation, as the shell) and the shell's state map of its cable. + CHARACTER(*), INTENT(IN) :: path + LOGICAL, INTENT(OUT) :: ok + INTEGER :: es, i, k + CHARACTER(512) :: em + REAL(wp) :: ld(3, 1) + CALL CD_AGG_Init_From_Deck(agg, path, DT, es, em, host_orientation=.TRUE.) + ok = es == CD_AGG_OK + CALL require(ok, 'the torsion line builds on the aggregate: '//TRIM(em)) + IF (.NOT. ok) RETURN + k = CD_AGG_NMovingPoints(agg, es, em) + ok = agg%ncable == 1 .AND. k == 1 + CALL require(ok, 'the deck is one coupled cable') + IF (.NOT. ok) RETURN + CALL map_states() + CALL CD_AGG_GetMovingPointMesh(agg, pos0, vel0, acc0, ld, es, em) + t0 = agg%cables(1)%line%t + ! the cable's r, m slots in its mirror [v_free; q_free; a_free] + IF (ALLOCATED(q_slot)) DEALLOCATE (q_slot, v_slot, a_slot) + ALLOCATE (q_slot(nf), v_slot(nf), a_slot(nf)) + k = 0 + DO i = 1, nf + k = k + 1 + v_slot(k) = i + q_slot(k) = nf + i + a_slot(k) = 2*nf + i + END DO + END SUBROUTINE setup + + SUBROUTINE map_states() + !! The state counts and the twist slots of the cable (re-read after a torsion change). + INTEGER :: es + CHARACTER(512) :: em + nf = COUNT(agg%cables(1)%line%freemask) + ntw = CD_HFMF_Twist_Lin_Count(agg%cables(1)) + nx2 = nf + ntw + msz = CD_HFMF_MirrorSize(agg%cables(1)) + IF (ALLOCATED(tp)) DEALLOCATE (tp, tr, ta, tn) + ALLOCATE (tp(ntw), tr(ntw), ta(ntw), tn(ntw)) + CALL CD_HFMF_Twist_Lin_Slots(agg%cables(1), tp, tr, ta, tn, es, em) + CALL require(es == CD_HFMF_OK, 'the twist slots: '//TRIM(em)) + IF (ALLOCATED(buf0)) DEALLOCATE (buf0, wbuf) + ALLOCATE (buf0(msz), wbuf(msz)) + CALL CD_HFMF_PackMirror(agg%cables(1), buf0, es, em) + CALL require(es == CD_HFMF_OK, 'the committed mirror packs: '//TRIM(em)) + END SUBROUTINE map_states + + FUNCTION rot_dcm(axis, ang) RESULT(r) + !! OpenFAST mesh orientation (global to local) of a turn ang about the global axis. + INTEGER, INTENT(IN) :: axis + REAL(wp), INTENT(IN) :: ang + REAL(wp) :: r(3, 3), c, s + INTEGER :: i, j + c = COS(ang) + s = SIN(ang) + r = 0.0_wp + r(axis, axis) = 1.0_wp + i = MOD(axis, 3) + 1 + j = MOD(axis + 1, 3) + 1 + r(i, i) = c + r(j, j) = c + r(i, j) = s + r(j, i) = -s + END FUNCTION rot_dcm + + SUBROUTINE state_of(x) + !! The linearisation state of the committed mirror: [q_free; phi_free; v_free; w_free]. + REAL(wp), INTENT(OUT) :: x(:) + x(1:nf) = buf0(q_slot) + x(nf + 1:nx2) = buf0(tp) + x(nx2 + 1:nx2 + nf) = buf0(v_slot) + x(nx2 + nf + 1:2*nx2) = buf0(tr) + END SUBROUTINE state_of + + SUBROUTINE lin_eval(x, axis, ang, om, al, xdot, mom, rates) + !! The shell's lin_eval on the cable: state x, the coupled point turned by ang about the global + !! axis (0: not turned) with angular velocity om and acceleration al; xdot = dx/dt and the + !! fairlead moment mom. rates = .FALSE. leaves out CD_HFMF_Set_Twist_Frame_Rates. + REAL(wp), INTENT(IN) :: x(:), ang, om(3), al(3) + INTEGER, INTENT(IN) :: axis + REAL(wp), INTENT(OUT) :: xdot(:), mom(3) + LOGICAL, INTENT(IN), OPTIONAL :: rates + REAL(wp) :: orient(3, 3, 1), omg(3, 1), alp(3, 1), p(3, 1), v(3, 1), a(3, 1), ld(3, 1), mm(3, 1) + INTEGER :: es + LOGICAL :: with_rates + CHARACTER(512) :: em + with_rates = .TRUE. + IF (PRESENT(rates)) with_rates = rates + wbuf = buf0 + wbuf(q_slot) = x(1:nf) + wbuf(tp) = x(nf + 1:nx2) + wbuf(v_slot) = x(nx2 + 1:nx2 + nf) + wbuf(tr) = x(nx2 + nf + 1:2*nx2) + CALL CD_HFMF_UnpackMirror(agg%cables(1), wbuf, t0, es, em) + CALL require(es == CD_HFMF_OK, 'lin_eval: the state loads: '//TRIM(em)) + orient(:, :, 1) = rot_dcm(MAX(axis, 1), MERGE(ang, 0.0_wp, axis > 0)) + omg(:, 1) = om + alp(:, 1) = al + CALL CD_AGG_UpdateStates_Moving(agg, pos0, vel0, acc0, es, em, output_probe=.FALSE., orientation=orient, & + angular_velocity=omg, angular_acceleration=alp) + CALL require(es == CD_AGG_OK, 'lin_eval: the input loads: '//TRIM(em)) + IF (with_rates) CALL CD_HFMF_Set_Twist_Frame_Rates(agg%cables(1), es, em) + CALL CD_HFMF_Refresh_Acceleration(agg%cables(1), es, em) + CALL require(es == CD_HFMF_OK, 'lin_eval: the accelerations: '//TRIM(em)) + CALL CD_HFMF_PackMirror(agg%cables(1), wbuf, es, em) + xdot(1:nf) = wbuf(v_slot) + xdot(nf + 1:nx2) = wbuf(tr) + xdot(nx2 + 1:nx2 + nf) = wbuf(a_slot) + xdot(nx2 + nf + 1:2*nx2) = wbuf(ta) + CALL CD_AGG_CalcOutput(agg, es, em) + CALL CD_AGG_GetMovingPointMesh(agg, p, v, a, ld, es, em, moment=mm) + CALL require(es == CD_AGG_OK, 'lin_eval: the outputs: '//TRIM(em)) + mom = mm(:, 1) + ! the committed state back + orient(:, :, 1) = rot_dcm(1, 0.0_wp) + omg = 0.0_wp + alp = 0.0_wp + CALL CD_AGG_UpdateStates_Moving(agg, pos0, vel0, acc0, es, em, output_probe=.TRUE., orientation=orient, & + angular_velocity=omg, angular_acceleration=alp) + CALL CD_HFMF_UnpackMirror(agg%cables(1), buf0, t0, es, em) + CALL require(es == CD_HFMF_OK, 'lin_eval: the committed state restores: '//TRIM(em)) + END SUBROUTINE lin_eval + + SUBROUTINE state_matrix(amat, cmom) + !! A = d xdot/dx and C = d M/dx (the fairlead moment) by central differences over the states. + REAL(wp), INTENT(OUT) :: amat(:, :), cmom(:, :) + REAL(wp) :: x0(2*nx2), x(2*nx2), fp(2*nx2), fm(2*nx2), mp(3), mn(3), h, z3(3) + INTEGER :: j + z3 = 0.0_wp + CALL state_of(x0) + DO j = 1, 2*nx2 + h = state_step(j) + x = x0 + x(j) = x0(j) + h + CALL lin_eval(x, 0, 0.0_wp, z3, z3, fp, mp) + x(j) = x0(j) - h + CALL lin_eval(x, 0, 0.0_wp, z3, z3, fm, mn) + amat(:, j) = (fp - fm)/(2.0_wp*h) + cmom(:, j) = (mp - mn)/(2.0_wp*h) + END DO + END SUBROUTINE state_matrix + + REAL(wp) FUNCTION state_step(j) RESULT(h) + !! The shell's step of state j: positions, tangents and angles HX; velocities HV, tangent + !! rates HV over the mean element length, twist rates HW. + INTEGER, INTENT(IN) :: j + INTEGER :: dof + IF (j <= nx2) THEN + h = HX + ELSE IF (j <= nx2 + nf) THEN + dof = 0 + h = HV + ! a tangent DOF (4-6 of its node) takes the tangent-rate step + dof = free_dof(j - nx2) + IF (MOD(dof - 1, 6) >= 3) h = HV*REAL(NE, wp)/SUM(agg%cables(1)%line%l0) + ELSE + h = HW + END IF + END FUNCTION state_step + + INTEGER FUNCTION free_dof(k) RESULT(dof) + !! The cable DOF of the k-th free DOF. + INTEGER, INTENT(IN) :: k + INTEGER :: i, c + c = 0 + dof = 0 + DO i = 1, SIZE(agg%cables(1)%line%freemask) + IF (.NOT. agg%cables(1)%line%freemask(i)) CYCLE + c = c + 1 + IF (c == k) THEN + dof = i + RETURN + END IF + END DO + END FUNCTION free_dof + + SUBROUTINE input_columns(axis, kind, b, dmom, rates) + !! B = d xdot/du and D = d M/du for one input of the coupled point: kind 1 the rotation about + !! the global axis, 2 its angular velocity, 3 its angular acceleration. + INTEGER, INTENT(IN) :: axis, kind + REAL(wp), INTENT(OUT) :: b(:), dmom(3) + LOGICAL, INTENT(IN), OPTIONAL :: rates + REAL(wp) :: x0(2*nx2), fp(2*nx2), fm(2*nx2), mp(3), mn(3), w(3), z3(3), h + z3 = 0.0_wp + CALL state_of(x0) + SELECT CASE (kind) + CASE (1) + h = HROT + CALL lin_eval(x0, axis, h, z3, z3, fp, mp, rates) + CALL lin_eval(x0, axis, -h, z3, z3, fm, mn, rates) + CASE (2) + h = HOM + w = 0.0_wp + w(axis) = h + CALL lin_eval(x0, 0, 0.0_wp, w, z3, fp, mp, rates) + CALL lin_eval(x0, 0, 0.0_wp, -w, z3, fm, mn, rates) + CASE DEFAULT + h = HOM + w = 0.0_wp + w(axis) = h + CALL lin_eval(x0, 0, 0.0_wp, z3, w, fp, mp, rates) + CALL lin_eval(x0, 0, 0.0_wp, z3, -w, fm, mn, rates) + END SELECT + b = (fp - fm)/(2.0_wp*h) + dmom = (mp - mn)/(2.0_wp*h) + END SUBROUTINE input_columns + + REAL(wp) FUNCTION reduced(amat, cmom, b, dmom, row) RESULT(k) + !! -(D - C A^-1 B) of the moment component row for one input column: A = [0 I; Kx Cx] and the + !! top rows of B vanish, so A^-1 B = [Kx^-1 b_acc; 0] and C A^-1 B = C_x Kx^-1 b_acc. + REAL(wp), INTENT(IN) :: amat(:, :), cmom(:, :), b(:), dmom(3) + INTEGER, INTENT(IN) :: row + REAL(wp), ALLOCATABLE :: kx(:, :), z(:, :) + INTEGER, ALLOCATABLE :: ipiv(:) + INTEGER :: info + EXTERNAL :: DGESV + ALLOCATE (kx(nx2, nx2), z(nx2, 1), ipiv(nx2)) + kx = amat(nx2 + 1:2*nx2, 1:nx2) + z(:, 1) = b(nx2 + 1:2*nx2) + CALL DGESV(nx2, 1, kx, nx2, ipiv, z, nx2, info) + CALL require(info == 0, 'the position block of A is regular') + k = -(dmom(row) - DOT_PRODUCT(cmom(row, 1:nx2), z(:, 1))) + END FUNCTION reduced + + SUBROUTINE twist_eigen(amat, omega, coupling) + !! The twist block of A, d a_phi/d phi = -M^-1 K with the lumped polar inertia M: omega^2 are + !! the eigenvalues of M^(1/2) (-A_pp) M^(-1/2) (symmetric; cyclic Jacobi), ascending. coupling + !! is the largest entry coupling the twist states to the r, m states, relative to the block. + REAL(wp), INTENT(IN) :: amat(:, :) + REAL(wp), INTENT(OUT) :: omega(:), coupling + REAL(wp) :: s(ntw, ntw), mass(ntw), big + INTEGER :: i, j + DO i = 1, ntw + mass(i) = agg%cables(1)%line%tw_mass(tn(i)) + END DO + DO j = 1, ntw + DO i = 1, ntw + s(i, j) = -amat(nx2 + nf + i, nf + j)*SQRT(mass(i)/mass(j)) + END DO + END DO + big = MAXVAL(ABS(s)) + s = 0.5_wp*(s + TRANSPOSE(s)) + CALL jacobi(s, omega) + omega = SQRT(MAX(omega, 0.0_wp)) + ! the twist rows against the r, m columns (positions and rates) and the r, m rows against the + ! twist columns, each scaled by its row block + ASSOCIATE (tw_rows => amat(nx2 + nf + 1:2*nx2, :), line_rows => amat(nx2 + 1:nx2 + nf, :)) + coupling = MAX(MAXVAL(ABS(tw_rows(:, 1:nf))), MAXVAL(ABS(tw_rows(:, nx2 + 1:nx2 + nf))))/ & + MAXVAL(ABS(tw_rows(:, nf + 1:nx2))) + coupling = MAX(coupling, MAX(MAXVAL(ABS(line_rows(:, nf + 1:nx2))), & + MAXVAL(ABS(line_rows(:, nx2 + nf + 1:2*nx2))))/MAXVAL(ABS(line_rows(:, 1:nf)))) + END ASSOCIATE + END SUBROUTINE twist_eigen + + SUBROUTINE jacobi(s, ev) + !! Eigenvalues of the symmetric matrix s by cyclic Jacobi rotations, ascending. + REAL(wp), INTENT(INOUT) :: s(:, :) + REAL(wp), INTENT(OUT) :: ev(:) + INTEGER :: n, p, q, k, sweep + REAL(wp) :: theta, t, c, sn, tau, off, apq, app, aqq, tmp + n = SIZE(s, 1) + DO sweep = 1, 100 + off = 0.0_wp + DO q = 2, n + DO p = 1, q - 1 + off = off + s(p, q)**2 + END DO + END DO + IF (off <= 1.0e-30_wp*SUM([(s(k, k)**2, k=1, n)])) EXIT + DO q = 2, n + DO p = 1, q - 1 + apq = s(p, q) + IF (ABS(apq) <= TINY(1.0_wp)) CYCLE + app = s(p, p) + aqq = s(q, q) + theta = (aqq - app)/(2.0_wp*apq) + t = SIGN(1.0_wp, theta)/(ABS(theta) + SQRT(theta**2 + 1.0_wp)) + c = 1.0_wp/SQRT(t**2 + 1.0_wp) + sn = t*c + tau = sn/(1.0_wp + c) + DO k = 1, n + IF (k == p .OR. k == q) CYCLE + tmp = s(k, p) + s(k, p) = tmp - sn*(s(k, q) + tau*tmp) + s(k, q) = s(k, q) + sn*(tmp - tau*s(k, q)) + s(p, k) = s(k, p) + s(q, k) = s(k, q) + END DO + s(p, p) = app - t*apq + s(q, q) = aqq + t*apq + s(p, q) = 0.0_wp + s(q, p) = 0.0_wp + END DO + END DO + END DO + DO k = 1, n + ev(k) = s(k, k) + END DO + DO p = 1, n - 1 + DO q = p + 1, n + IF (ev(q) < ev(p)) THEN + tmp = ev(p) + ev(p) = ev(q) + ev(q) = tmp + END IF + END DO + END DO + END SUBROUTINE jacobi + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_modes_and_stiffness() + REAL(wp), ALLOCATABLE :: amat(:, :), cmom(:, :), b(:), omega(:) + REAL(wp) :: dmom(3), coupling, w_cont, w_disc, e_cont, e_disc, k_red, k_ft, k_ref, h, kxx + INTEGER :: n, es, j + LOGICAL :: ok + CHARACTER(512) :: em + CALL write_deck('lin_torsion_modes.dat', IRN, 0.0_wp) + CALL setup('lin_torsion_modes.dat', ok) + IF (.NOT. ok) RETURN + ! rigid in torsion at both ends: the two end angles are held, the 49 interior ones are states + CALL require(ntw == NE - 1, 'F: the free twist angles are the interior nodes''') + ok = .TRUE. + DO j = 2, ntw + ok = ok .AND. tp(j) == tp(1) + j - 1 .AND. tr(j) == tr(1) + j - 1 .AND. ta(j) == ta(1) + j - 1 + END DO + CALL require(ok, 'F: the twist slots are consecutive') + CALL require(.NOT. (ANY(ABS(agg%cables(1)%line%tw_phi(tn) - buf0(tp)) > 0.0_wp) .OR. & + ANY(ABS(agg%cables(1)%line%tw_w(tn) - buf0(tr)) > 0.0_wp)), & + 'F: the slots hold the committed angles and rates') + ALLOCATE (amat(2*nx2, 2*nx2), cmom(3, 2*nx2), b(2*nx2), omega(ntw)) + CALL state_matrix(amat, cmom) + CALL twist_eigen(amat, omega, coupling) + h = L/REAL(NE, wp) + WRITE (*, '(A,I0,A,I0,A,ES10.3)') 'F: ', 2*nx2, ' states (', 2*ntw, ' twist); twist-line coupling / block ', & + coupling + CALL require(coupling <= 1.0e-8_wp, 'F: the twist block is decoupled from the line states') + DO n = 1, 3 + w_cont = REAL(n, wp)*PI/L*SQRT(GJ/IRN) + w_disc = 2.0_wp/h*SQRT(GJ/IRN)*SIN(REAL(n, wp)*PI/(2.0_wp*REAL(NE, wp))) + e_cont = omega(n)/w_cont - 1.0_wp + e_disc = omega(n)/w_disc - 1.0_wp + WRITE (*, '(A,I0,A,F12.8,A,F12.8,A,ES10.3,A,F12.8,A,ES10.3)') 'F: mode ', n, ' omega ', omega(n), & + ' rad/s; continuum ', w_cont, ' (', e_cont, '); lumped chain ', w_disc, ' (', e_disc, ')' + CALL require(ABS(e_disc) <= 1.0e-6_wp, 'F: the twist mode matches the lumped chain') + ! the lumped-inertia chain lies (n pi/N)^2/24 below the continuum + CALL require(ABS(e_cont) <= 1.2_wp*(REAL(n, wp)*PI/REAL(NE, wp))**2/24.0_wp + 1.0e-6_wp, & + 'F: the twist mode matches n pi/L sqrt(GJ/Irn) within the discretisation error') + END DO + ! K: the roll stiffness about the line axis (global z) + CALL input_columns(3, 1, b, dmom) + k_red = reduced(amat, cmom, b, dmom, 3) + k_ft = -dmom(3) + k_ref = GJ/L + WRITE (*, '(A,ES16.9,A,ES16.9,A,ES10.3,A,ES16.9,A,ES16.9)') 'K: -(D - C A^-1 B) ', k_red, ' N m/rad; GJ/L ', & + k_ref, ' (', k_red/k_ref - 1.0_wp, '); feedthrough D alone ', k_ft, '; GJ/l_e ', GJ/h + CALL require(ABS(k_red/k_ref - 1.0_wp) <= 1.0e-6_wp, 'K: the reduced roll stiffness is GJ/L') + CALL require(ABS(k_ft/(GJ/h) - 1.0_wp) <= 1.0e-6_wp, 'K: the feedthrough alone is the end element''s GJ/l_e') + ! a turn about an axis across the line does not load the straight pinned line + CALL input_columns(1, 1, b, dmom) + kxx = reduced(amat, cmom, b, dmom, 1) + WRITE (*, '(A,ES10.3,A)') 'K: about x: ', kxx, ' N m/rad' + CALL require(ABS(kxx) <= 1.0e-6_wp*k_ref, 'K: no roll stiffness across the straight pinned line') + CALL CD_AGG_End(agg, es, em) + END SUBROUTINE check_modes_and_stiffness + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_condensed() + !! The line of F and K with its torsion installed again without the polar inertia: the + !! condensed torsion, whose uniform torque has no state of its own. + TYPE(CD_HermiteTorsionType) :: tors + REAL(wp), ALLOCATABLE :: amat(:, :), cmom(:, :), b(:) + REAL(wp) :: dmom(3), k_red, k_ref, frame(3, 2), dcm(3, 3) + INTEGER :: es + LOGICAL :: ok + CHARACTER(512) :: em + CALL write_deck('lin_torsion_condensed.dat', IRN, 0.0_wp) + CALL setup('lin_torsion_condensed.dat', ok) + IF (.NOT. ok) RETURN + tors = agg%cables(1)%line%torsion + IF (ALLOCATED(tors%irn)) DEALLOCATE (tors%irn) + frame = agg%cables(1)%tors_frame_parent + dcm = agg%cables(1)%parent_dcm + CALL CD_HFMF_Set_Torsion(agg%cables(1), tors, es, em, coupled_frame_parent=frame, parent_orientation=dcm) + CALL require(es == CD_HFMF_OK, 'C: the condensed torsion installs: '//TRIM(em)) + IF (es /= CD_HFMF_OK) RETURN + CALL map_states() + CALL require(ntw == 0 .AND. .NOT. agg%cables(1)%line%tw_active, 'C: the condensed torsion has no twist states') + ALLOCATE (amat(2*nx2, 2*nx2), cmom(3, 2*nx2), b(2*nx2)) + CALL state_matrix(amat, cmom) + CALL input_columns(3, 1, b, dmom) + k_red = reduced(amat, cmom, b, dmom, 3) + k_ref = GJ/L + WRITE (*, '(A,ES16.9,A,ES16.9,A,ES10.3,A,ES16.9)') 'C: -(D - C A^-1 B) ', k_red, ' N m/rad; GJ/L ', k_ref, & + ' (', k_red/k_ref - 1.0_wp, '); D alone ', -dmom(3) + CALL require(ABS(k_red/k_ref - 1.0_wp) <= 1.0e-6_wp, 'C: the condensed roll stiffness is GJ/L') + CALL CD_AGG_End(agg, es, em) + END SUBROUTINE check_condensed + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_elastic_end() + !! The line of K with an elastic torsional spring kt at End B: its end angle is a state too, + !! and the reduced roll stiffness is that of the series compliance, 1/(L/GJ + 1/kt). + REAL(wp), PARAMETER :: KT = 2.0e3_wp + REAL(wp), ALLOCATABLE :: amat(:, :), cmom(:, :), b(:) + REAL(wp) :: dmom(3), k_red, k_ref + INTEGER :: es + LOGICAL :: ok + CHARACTER(512) :: em + CALL write_deck('lin_torsion_elastic.dat', IRN, 0.0_wp, tors_b='2.0e3') + CALL setup('lin_torsion_elastic.dat', ok) + IF (.NOT. ok) RETURN + CALL require(ntw == NE, 'E: the elastic end''s angle is a state') + ALLOCATE (amat(2*nx2, 2*nx2), cmom(3, 2*nx2), b(2*nx2)) + CALL state_matrix(amat, cmom) + CALL input_columns(3, 1, b, dmom) + k_red = reduced(amat, cmom, b, dmom, 3) + k_ref = 1.0_wp/(L/GJ + 1.0_wp/KT) + WRITE (*, '(A,ES16.9,A,ES16.9,A,ES10.3,A)') 'E: -(D - C A^-1 B) ', k_red, ' N m/rad; 1/(L/GJ + 1/kt) ', & + k_ref, ' (', k_red/k_ref - 1.0_wp, ')' + CALL require(ABS(k_red/k_ref - 1.0_wp) <= 1.0e-6_wp, 'E: the roll stiffness of the elastic end in series') + CALL CD_AGG_End(agg, es, em) + END SUBROUTINE check_elastic_end + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_frame_rates() + REAL(wp), ALLOCATABLE :: amat(:, :), cmom(:, :), b(:) + REAL(wp) :: dmom(3), k_om, k_om0, k_al, i_held, h + INTEGER :: es + LOGICAL :: ok + CHARACTER(512) :: em + CALL write_deck('lin_torsion_rates.dat', IRN, BT) + CALL setup('lin_torsion_rates.dat', ok) + IF (.NOT. ok) RETURN + ALLOCATE (amat(2*nx2, 2*nx2), cmom(3, 2*nx2), b(2*nx2)) + CALL state_matrix(amat, cmom) + CALL input_columns(3, 2, b, dmom) + k_om = reduced(amat, cmom, b, dmom, 3) + CALL input_columns(3, 2, b, dmom, rates=.FALSE.) + k_om0 = reduced(amat, cmom, b, dmom, 3) + WRITE (*, '(A,ES16.9,A,ES16.9,A,ES10.3,A,ES10.3)') 'R: moment per unit angular velocity ', k_om, & + ' N m s/rad; Bt/L ', BT/L, ' (', k_om/(BT/L) - 1.0_wp, '); without the frame rates ', k_om0 + CALL require(ABS(k_om/(BT/L) - 1.0_wp) <= 1.0e-6_wp, 'R: the steady-roll damping torque Bt/L') + CALL require(ABS(k_om0) <= 1.0e-9_wp*BT/L, 'R: without the frame rates the damping column vanishes') + CALL input_columns(3, 3, b, dmom) + k_al = -dmom(3) + h = L/REAL(NE, wp) + i_held = 0.5_wp*IRN*h + WRITE (*, '(A,ES16.9,A,ES16.9,A,ES10.3)') 'R: moment per unit angular acceleration ', k_al, & + ' kg m^2; Irn l_e/2 ', i_held, ' (', k_al/i_held - 1.0_wp, ')' + CALL require(ABS(k_al/i_held - 1.0_wp) <= 1.0e-6_wp, 'R: the held end section''s polar inertia') + CALL require(.NOT. MAXVAL(ABS(b)) > 0.0_wp, 'R: the angular acceleration does not drive the line states') + CALL CD_AGG_End(agg, es, em) + END SUBROUTINE check_frame_rates +END PROGRAM test_lin_torsion diff --git a/validation/scripts/openfast_lin_torsion.py b/validation/scripts/openfast_lin_torsion.py new file mode 100644 index 00000000..faa389e0 --- /dev/null +++ b/validation/scripts/openfast_lin_torsion.py @@ -0,0 +1,415 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +"""OpenFAST linearisation of finite-EI lines restrained in torsion (CompMooring = 5). + +Two decks, each linearised once at t = 0 in the case of openfast_lin_ab.py (the IEA-15MW +UMaine model, platform DOFs only, still water, OutFmt ES24.15E3, module-level output), with +the deck below as the only mooring: + + 1. A straight, neutrally buoyant 100 m line held taut at 0.5 % strain between a coupled + fairlead (0, 0, -20) and a fixed anchor below it, pinned in bending and rigid in torsion + at both ends, GJ = 5e4 N m^2, polar inertia Irn = 2 kg m, 50 elements, no drag or added + mass. Gated: + * the torsional modes from the eigenvalues of the module's A (the modes whose + eigenvectors lie on the twist states): the first three frequencies against the + continuum's n pi/L sqrt(GJ/Irn), within the lumped-inertia discretisation error + (n pi/N)^2/24, and against the lumped chain's 2 sqrt(GJ/Irn)/h sin(n pi/(2N)); + * the roll stiffness of the coupled point: -(D - C A^-1 B) of the fairlead moment about + the line axis per unit rotation about it against GJ/L; the feedthrough D alone is + printed (the end element's GJ/l_e: what a linearisation without twist states gives). + 2. The lazy-wave power cable of examples/iea15mw_umaine_mixed_cabledyn.dat (line 4, the + same mesh, seabed friction off) alone, with GJ = 5e4 N m^2 and the sections' polar + inertia, pinned in bending at both ends with the directors along its static end tangents, + rigid in torsion, and twisted by --pretwist (default 90 deg) at End B: a twisted, + non-planar lazy wave. Gated against the standalone driver's static solutions of the same + deck (TMax = 0), by central differences: + * rotation about the End A director d: Pretwist(A) = +-delta (--dtwist, default 0.5 deg) + rolls the fairlead frame about d as a platform rotation about d does, so + -d Torq1N1/d delta is d^T K_rot d (the moment on the fairlead about d is the torque); + * translation: the coupled point moved +-h (--cable-h, default 0.05 m) along each axis: + the 3x3 force stiffness and the torque row d^T K_M,x; + * the force column per rotation about d, K_F,rot d, against that torque row, its + reciprocal (the static stiffness is symmetric): the static force changes by about + 1e-3 N over the rotation step, below the 8 digits the driver writes, so its direct + difference is only printed; + entries >= 10 % of the largest of their block within --pct (default 1 %), every entry + >= 1 % of it within twice that. The operating-point moment about d must equal the + static Torq1N1. + +Measured (the 0.4.0 module): the three torsional modes are the lumped chain's to 5e-14 and the +continuum's within -1.6e-4, -6.6e-4, -1.5e-3; the straight line's roll stiffness is GJ/L to +1.5e-14 (feedthrough D alone 25 000 = GJ/l_e); the twisted lazy wave matches its static +solutions to 4.9e-4 (the moment about d per unit rotation 82.4268 / 82.4263 N m/rad, 5.9e-6). +An executable without twist states refuses both decks at initialisation ("formal OpenFAST +linearization of a line restrained in torsion is not supported"); with the twist angles held +the straight line's roll stiffness would be the end element's GJ/l_e, 50 times GJ/L. + +Usage: + python validation/scripts/openfast_lin_torsion.py --exe --case-dir + --driver [--ref-cd IEA-15-UMaine_CompMooring5_CableDyn.fst] + [--mixed-deck examples/iea15mw_umaine_mixed_cabledyn.dat] [--pretwist 90] + [--dtwist 0.5] [--cable-h 0.05] [--pct 1.0] [--skip-run] +""" + +from __future__ import annotations + +import argparse +import re +import subprocess +import sys +from pathlib import Path + +import numpy as np + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import openfast_lin_ab as ab # noqa: E402 + +RHOW = 1025.0 +GJ = 5.0e4 +L_STRAIGHT = 100.0 +N_STRAIGHT = 50 +IRN_STRAIGHT = 2.0 + + +def straight_deck() -> str: + mass = RHOW * 0.25 * np.pi * 0.2**2 + return "\n".join([ + "--------------------- CableDyn Input File ------------------------------------", + "Straight vertical line restrained in torsion (openfast_lin_torsion.py)", + "--------------------- LINE TYPES ---------------------------------------------", + "Name Diam Mass EA BA EI GAs GJ Irt Irn Cdn Cdt Can Cat", + "(-) (m) (kg/m) (N) (-) (Nm2) (N) (Nm2) (kgm) (kgm) (-) (-) (-) (-)", + f"cab 0.2 {mass:.16e} 1.0e7 0.0 1.0e6 1.0e8 {GJ:.1e} 1.0 {IRN_STRAIGHT} 0.0 0.0 0.0 0.0", + "--------------------- POINTS ------------------------------------------------", + "ID Type X Y Z", + "(-) (-) (m) (m) (m)", + "1 Coupled 0.0 0.0 -20.0", + "2 Fixed 0.0 0.0 -120.5", + "--------------------- LINES -------------------------------------------------", + "ID NodeA NodeB Outputs", + "(-) (-) (-) (-)", + "1 1 2 -", + "--------------------- SECTIONS ----------------------------------------------", + "LineID LineType Length NumSegs", + "(-) (-) (m) (-)", + f"1 cab {L_STRAIGHT} {N_STRAIGHT}", + "--------------------- END CONNECTIONS ---------------------------------------", + "LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist", + "(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg)", + "1 A Pinned 0 0 -1 Rigid 1 0 0 0", + "1 B Pinned 0 0 -1 Rigid 1 0 0 0", + "--------------------- OPTIONS -----------------------------------------------", + "0.025 dtM - CableDyn time step (s)", + "--------------------- OUTPUTS -----------------------------------------------", + '"Torq1N1"', + "END", + "--------------------- need this line ----------------------------------------", + "", + ]) + + +def lazy_wave_parts(mixed: Path) -> dict: + """Line 4 of the mixed example: its line types, end points, sections and options.""" + if not mixed.is_file(): + ab.die(f"mixed deck not found: {mixed}") + lines = mixed.read_text().splitlines() + sec = None + types, points, sections, options = {}, {}, [], [] + for ln in lines: + if ln.lstrip().startswith("-"): + up = ln.upper() + sec = next((s for s in ("LINE TYPES", "POINTS", "LINES", "SECTIONS", "OPTIONS", "OUTPUTS") + if s in up), None) + continue + tok = ln.split() + if not tok or tok[0].startswith("("): + continue + if sec == "LINE TYPES" and len(tok) == 10 and tok[0] in ("bare", "buoy"): + types[tok[0]] = tok + elif sec == "POINTS" and tok[0] in ("7", "8"): + points[tok[0]] = [float(v) for v in tok[2:5]] + elif sec == "SECTIONS" and tok[0] == "4": + sections.append(tok) + elif sec == "OPTIONS" and len(tok) >= 2 and tok[1] in ("kBot", "cBot", "rhoInf", "dtM"): + options.append(ln) + if set(types) != {"bare", "buoy"} or set(points) != {"7", "8"} or not sections: + ab.die(f"{mixed.name}: line 4 (bare/buoy lazy wave between points 7 and 8) not found") + return {"types": types, "points": points, "sections": sections, "options": options} + + +def lazy_wave_deck(parts: dict, ez_a, ez_b, pretwist_a: float, pretwist_b: float, torsion: bool, + point_a=None) -> str: + """The lazy-wave cable alone (line 1 between points 1 and 2), restrained in torsion.""" + # GAs, Irt and the polar inertia Irn of each section take the circular-section closure values + # EA/(2 (1 + 0.3)), m d^2/16 and m d^2/8 + rows = [] + for name in ("bare", "buoy"): + t = parts["types"][name] + d, m, ea = float(t[1]), float(t[2]), float(t[3]) + rows.append(f"{name} {t[1]} {t[2]} {t[3]} {t[4]} {t[5]} {ea / 2.6:.6e} {GJ:.1e} {m * d * d / 16:.6e} " + f"{m * d * d / 8:.6e} {' '.join(t[6:10])}") + pa = parts["points"]["7"] if point_a is None else point_a + pb = parts["points"]["8"] + out = [ + "--------------------- CableDyn Input File ------------------------------------", + "Twisted lazy-wave power cable restrained in torsion (openfast_lin_torsion.py)", + "--------------------- LINE TYPES ---------------------------------------------", + "Name Diam Mass EA BA EI GAs GJ Irt Irn Cdn Cdt Can Cat", + "(-) (m) (kg/m) (N) (-) (Nm2) (N) (Nm2) (kgm) (kgm) (-) (-) (-) (-)", + *rows, + "--------------------- POINTS ------------------------------------------------", + "ID Type X Y Z", + "(-) (-) (m) (m) (m)", + f"1 Coupled {pa[0]:.10f} {pa[1]:.10f} {pa[2]:.10f}", + f"2 Fixed {pb[0]:.10f} {pb[1]:.10f} {pb[2]:.10f}", + "--------------------- LINES -------------------------------------------------", + "ID NodeA NodeB Outputs", + "(-) (-) (-) (-)", + "1 1 2 -", + "--------------------- SECTIONS ----------------------------------------------", + "LineID LineType Length NumSegs", + "(-) (-) (m) (-)", + *["1 " + " ".join(s[1:4]) for s in parts["sections"]], + ] + if torsion: + out += [ + "--------------------- END CONNECTIONS ---------------------------------------", + "LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist", + "(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg)", + f"1 A Pinned {ez_a[0]:.12f} {ez_a[1]:.12f} {ez_a[2]:.12f} Rigid 0 1 0 {pretwist_a:.12f}", + f"1 B Pinned {ez_b[0]:.12f} {ez_b[1]:.12f} {ez_b[2]:.12f} Rigid 0 1 0 {pretwist_b:.12f}", + ] + out += [ + "--------------------- OPTIONS -----------------------------------------------", + *parts["options"], + "200.0 WtrDpth - Water depth (m)", + "none frictionMu - Seabed friction coefficient", + "--------------------- OUTPUTS -----------------------------------------------", + '"Point1Fx"', '"Point1Fy"', '"Point1Fz"', '"L1N1px"', '"L1N1py"', '"L1N1pz"', '"L1N2px"', + '"L1N2py"', '"L1N2pz"', + ] + if torsion: + out.append('"Torq1N1"') + out += ["END", "--------------------- need this line ----------------------------------------", ""] + return "\n".join(out) + + +def driver_solve(driver: Path, text: str, work: Path) -> dict: + """The deck solved by the standalone driver at TMax = 0; its first output row by name.""" + work.mkdir(parents=True, exist_ok=True) + text = text.replace("--------------------- OUTPUTS", + "0.0 TMax - Standalone duration (s); 0 solves the static start\n" + "--------------------- OUTPUTS", 1) + (work / "trial.dat").write_text(text) + proc = subprocess.run([str(driver), "trial.dat", "trial"], cwd=work, capture_output=True, text=True, + timeout=3600) + if proc.returncode != 0: + tail = "\n".join((proc.stdout + proc.stderr).splitlines()[-15:]) + ab.die(f"driver failed:\n{tail}") + rows = [r for r in (work / "trial.out").read_text().splitlines() if r.strip() and not r.startswith("#")] + head = rows[0].split() + vals = [float(v) for v in rows[1].split()] + return dict(zip(head, vals)) + + +def lin_case(args: argparse.Namespace, case: Path, name: str, deck_text: str) -> dict: + """Linearise the deck alone in the openfast_lin_ab case (its prepared CableDyn .fst).""" + deck = case / f"CableDyn_{name}.dat" + deck.write_text(deck_text) + base = case / "Main_lin_cd5.fst" + if not base.is_file(): + ab.prepare_lin_deck(case / args.ref_cd, base, 0.0, "ES24.15E3", 400.0) + fst = case / f"Main_lin_{name}.fst" + text = base.read_text() + moor = ab.file_entry(text, "MooringFile", base.name) + fst.write_text(text.replace(f'"{moor}"', f'"{deck.name}"')) + if not args.skip_run: + print(f"running {fst.name} ...") + ab.run_case(args.exe, fst) + return ab.parse_module_lin(case / f"Main_lin_{name}.1.CD.lin") + + +def mesh_rows(mod: dict, kinds: list[str], labels: str) -> list[int]: + out = [] + for kind in kinds: + idx = ab.match_indices(mod[labels], [kind]) + if len(idx) != 3: + ab.die(f"expected 3 '{kind}' labels on the single coupled point, got {len(idx)}") + out += idx + return out + + +def reduced_6x6(mod: dict) -> tuple[np.ndarray, np.ndarray]: + """K = -(D - C A^-1 B) and the feedthrough -D over [force; moment] x [translation; rotation].""" + K = ab.static_impedance(mod) + rows = mesh_rows(mod, [" force", " moment"], "y_labels") + cols = mesh_rows(mod, ["translation displacement", "orientation angle"], "u_labels") + return -K[np.ix_(rows, cols)], -mod["D"][np.ix_(rows, cols)] + + +def gate_straight(args: argparse.Namespace, case: Path) -> list[str]: + mod = lin_case(args, case, "tors_straight", straight_deck()) + fails = [] + # torsional modes: eigenvectors on the twist states + labels = [ab_label(s) for s in state_labels(case / "Main_lin_tors_straight.1.CD.lin", mod["n_x"])] + tw = np.array(["twist" in s for s in labels]) + print(f"straight line: {mod['n_x']} states, {int(tw.sum())} twist") + ev, vec = np.linalg.eig(mod["A"]) + share = np.sum(np.abs(vec[tw, :])**2, axis=0) / np.sum(np.abs(vec)**2, axis=0) + pick = (ev.imag > 1e-9) & (share > 0.999) + w = np.sort(np.abs(ev[pick])) + h = L_STRAIGHT / N_STRAIGHT + c = np.sqrt(GJ / IRN_STRAIGHT) + worst_c = worst_d = 0.0 + leak = float(np.max(1.0 - share[pick])) if pick.any() else 1.0 + if len(w) < 3: + ab.die(f"found {len(w)} torsional modes, expected at least 3") + for n in (1, 2, 3): + wc = n * np.pi / L_STRAIGHT * c + wd = 2.0 / h * c * np.sin(n * np.pi / (2 * N_STRAIGHT)) + ec, ed = w[n - 1] / wc - 1.0, w[n - 1] / wd - 1.0 + bound = 1.2 * (n * np.pi / N_STRAIGHT) ** 2 / 24.0 + 1e-6 + print(f" torsional mode {n}: {w[n - 1] / (2 * np.pi):.8f} Hz; continuum {wc / (2 * np.pi):.8f} " + f"({ec:+.3e}, bound {bound:.2e}); lumped chain {wd / (2 * np.pi):.8f} ({ed:+.3e})") + worst_c = max(worst_c, abs(ec) / bound) + worst_d = max(worst_d, abs(ed)) + print(f" max non-twist share of a torsional eigenvector {leak:.2e}") + if worst_c > 1.0 or worst_d > 1e-6: + fails.append("the torsional modes of A differ from n pi/L sqrt(GJ/Irn)") + K, Dft = reduced_6x6(mod) + k_zz, d_zz = K[5, 5], Dft[5, 5] + print(f" roll stiffness about the line axis -(D - C A^-1 B) = {k_zz:.9e} N m/rad; GJ/L = " + f"{GJ / L_STRAIGHT:.9e} ({k_zz / (GJ / L_STRAIGHT) - 1.0:+.2e}); feedthrough -D = {d_zz:.6e} " + f"(GJ/l_e = {GJ / h:.6e})") + print(f" rotational block about x, y: {K[3, 3]:.3e}, {K[4, 4]:.3e} N m/rad") + if abs(k_zz / (GJ / L_STRAIGHT) - 1.0) > 1e-6: + fails.append("the straight line's roll stiffness differs from GJ/L") + return fails + + +def state_labels(path: Path, n_x: int) -> list[str]: + text = path.read_text().splitlines() + out: list[str] = [] + for i, ln in enumerate(text): + if "Order of continuous states" in ln: + j = i + 1 + while j < len(text) and len(out) < n_x: + row = text[j].strip() + j += 1 + if row and row.split()[0].isdigit(): + out.append(row) + break + if len(out) != n_x: + ab.die(f"{path.name}: expected {n_x} state labels, got {len(out)}") + return out + + +def ab_label(row: str) -> str: + return row.split(None, 4)[-1] + + +def gate_lazy_wave(args: argparse.Namespace, case: Path) -> list[str]: + parts = lazy_wave_parts(args.mixed_deck.resolve()) + work = case / "tors_lw_work" + # the static end tangents of the untwisted, unrestrained cable: the bending-pinned directors + p0 = driver_solve(args.driver, lazy_wave_deck(parts, None, None, 0.0, 0.0, False), work) + t_a = np.array([p0["L1N2px"] - p0["L1N1px"], p0["L1N2py"] - p0["L1N1py"], p0["L1N2pz"] - p0["L1N1pz"]]) + t_a /= np.linalg.norm(t_a) + ez_b = np.array([1.0, 0.0, 0.0]) + deck = lazy_wave_deck(parts, t_a, ez_b, 0.0, args.pretwist, True) + mod = lin_case(args, case, "tors_lazywave", deck) + K, _ = reduced_6x6(mod) + d = t_a + rows = mesh_rows(mod, [" moment"], "y_labels") + m_op = ab.op_values(mod["y_labels"], rows) + s0 = driver_solve(args.driver, deck, work) + print(f"twisted lazy wave (Pretwist B {args.pretwist} deg): {mod['n_x']} states; End A director " + f"{np.array2string(d, precision=5)}") + print(f" operating point: moment about d {m_op @ d:.9e} N m, static Torq1N1 {s0['Torq1N1']:.9e} N m") + fails = [] + if abs(m_op @ d - s0["Torq1N1"]) > 1e-6 * max(abs(s0["Torq1N1"]), 1.0): + fails.append("the operating-point moment about the End A director is not the static torque") + # the static reference: rotation about d (Pretwist A) and translations of the coupled point + dl = np.radians(args.dtwist) + ref_rot = np.zeros(4) # [F; M.d] per unit rotation about d + sp = driver_solve(args.driver, lazy_wave_deck(parts, t_a, ez_b, args.dtwist, args.pretwist, True), work) + sm = driver_solve(args.driver, lazy_wave_deck(parts, t_a, ez_b, -args.dtwist, args.pretwist, True), work) + for k, c in enumerate("xyz"): + ref_rot[k] = -(sp[f"Point1F{c}"] - sm[f"Point1F{c}"]) / (2 * dl) + ref_rot[3] = -(sp["Torq1N1"] - sm["Torq1N1"]) / (2 * dl) + ref_tr = np.zeros((4, 3)) # [F; M.d] per unit translation + pa = np.array(parts["points"]["7"]) + for j in range(3): + e = np.zeros(3) + e[j] = args.cable_h + sp = driver_solve(args.driver, lazy_wave_deck(parts, t_a, ez_b, 0.0, args.pretwist, True, pa + e), work) + sm = driver_solve(args.driver, lazy_wave_deck(parts, t_a, ez_b, 0.0, args.pretwist, True, pa - e), work) + for k, c in enumerate("xyz"): + ref_tr[k, j] = -(sp[f"Point1F{c}"] - sm[f"Point1F{c}"]) / (2 * args.cable_h) + ref_tr[3, j] = -(sp["Torq1N1"] - sm["Torq1N1"]) / (2 * args.cable_h) + lin_rot = np.concatenate([K[0:3, 3:6] @ d, [d @ K[3:6, 3:6] @ d]]) + lin_tr = np.vstack([K[0:3, 0:3], d @ K[3:6, 0:3]]) + tol = args.pct / 100.0 + + def compare(what: str, lin: np.ndarray, ref: np.ndarray, units: list[str]) -> tuple[float, float]: + big = np.abs(ref).max() + dom = allv = 0.0 + for i in range(lin.shape[0]): + cells = [] + for j in range(lin.shape[1]): + rel = (lin[i, j] - ref[i, j]) / ref[i, j] if abs(ref[i, j]) > 1e-2 * big else 0.0 + if abs(ref[i, j]) >= 0.1 * big: + dom = max(dom, abs(rel)) + if abs(ref[i, j]) >= 1e-2 * big: + allv = max(allv, abs(rel)) + cells.append(f"{lin[i, j]:12.6g} / {ref[i, j]:12.6g} / {rel:+.2e}") + print(f" {what} {units[i]}: " + " | ".join(cells)) + return dom, allv + + print(" K lin / K static / rel. diff; the moment about d per unit rotation about d (N m/rad):") + d1, a1 = compare("rot", lin_rot[3:4, None], ref_rot[3:4, None], ["M.d"]) + print(" the force per unit translation x | y | z (N/m):") + d2, a2 = compare("tr ", lin_tr[0:3], ref_tr[0:3], ["Fx", "Fy", "Fz"]) + print(" the moment about d per unit translation x | y | z (N m/m):") + d3, a3 = compare("tr ", lin_tr[3:4], ref_tr[3:4], ["M.d"]) + # The force per unit rotation changes the fairlead force (1e4 N, written with 8 digits) by + # about 1e-3 N over the rotation step, below the output resolution: it is gated against the + # static moment per unit translation, its reciprocal (the static stiffness is symmetric), and + # the direct static difference is only printed. + print(" the force per unit rotation about d (N/rad) against the static moment per unit translation:") + d4, a4 = compare("rot", lin_rot[0:3, None], ref_tr[3:4].T, ["Fx", "Fy", "Fz"]) + print(" (the static force per unit rotation, at the output resolution: " + + ", ".join(f"{v:.4g}" for v in ref_rot[0:3]) + " N/rad)") + dom, allv = max(d1, d2, d3, d4), max(a1, a2, a3, a4) + print(f" twisted lazy wave: dominant entries max rel. diff {dom:.2e} (gate {tol:.1e}); all entries " + f">= 1% of block max {allv:.2e} (gate {2 * tol:.1e})") + if dom > tol or allv > 2 * tol: + fails.append("the twisted lazy wave's linearised stiffness differs from its static solutions") + return fails + + +def main() -> None: + ap = argparse.ArgumentParser() + ap.add_argument("--exe", type=Path, required=True) + ap.add_argument("--case-dir", type=Path, required=True) + ap.add_argument("--driver", type=Path, required=True) + ap.add_argument("--ref-cd", default="IEA-15-UMaine_CompMooring5_CableDyn.fst") + ap.add_argument("--mixed-deck", type=Path, + default=Path(__file__).resolve().parents[2] / "examples" / "iea15mw_umaine_mixed_cabledyn.dat") + ap.add_argument("--pretwist", type=float, default=90.0, help="End B pretwist of the lazy wave (deg)") + ap.add_argument("--dtwist", type=float, default=0.5, help="Pretwist(A) step of the static reference (deg)") + ap.add_argument("--cable-h", type=float, default=0.05, help="coupled-point step of the static reference (m)") + ap.add_argument("--pct", type=float, default=1.0, help="lazy-wave tolerance in %%") + ap.add_argument("--skip-run", action="store_true") + args = ap.parse_args() + if not args.driver.is_file(): + ab.die(f"driver not found: {args.driver}") + case = args.case_dir + fails = gate_straight(args, case) + gate_lazy_wave(args, case) + if fails: + ab.die("; ".join(fails)) + print("PASS") + + +if __name__ == "__main__": + main() From 939268fae6033eddb6564732270439e555cd233e Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 17:14:43 +0900 Subject: [PATCH 2/7] fix(openfast): review of the torsion linearisation - lin_eval reports a failure to set the torsion end-frame rates by its own name, no longer as the cable's acceleration. - The comments and the CHANGELOG say that in a Linearize run every input Jacobian, those of the time march before the linearisation times included, steps the coupled-point rotation by 1e-4 rad; a run without Linearize keeps 0.1 rad. - The angle-step comment states what is affine in the twist angles (the element twists, torques and their forces at a fixed configuration, also under GJ|K) and what is not (their coupling to the configuration). - The .lin operating-point outputs come from CD_CalcOutput, which keeps the committed accelerations and the end-frame rates of the last step's turn, while the matrices difference lin_eval with the input's angular rates. At a settled operating point (the documented still-water start) the two agree; at a moving one they differ by the inertia terms and the torsional damping and held-section inertia of the fairlead moment. This is documented (lin_eval, doc/openfast.rst) rather than changed: making CD_CalcOutput evaluate like lin_eval would change the operating-point outputs of every linearised cable, not only of torsion. - Docs: the turned frame is the coupled (host-driven) end's; doc/coupling.rst and doc/coupling_boundary.md no longer describe the zero-state quasi-static linearisation removed in #66. - openfast_lin_torsion.py: ruff clean. openfast_lin_torsion.py rerun on the rebuilt module: unchanged (twist modes to the lumped chain 5e-14, GJ/L to 1.5e-14, twisted lazy wave 4.9e-4). Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 11 +++++---- VALIDATION.md | 7 +++--- doc/coupling.rst | 17 +++++++------ doc/coupling_boundary.md | 10 ++++---- doc/driver_format.md | 6 ++--- doc/openfast.rst | 17 ++++++++----- src/openfast/CableDyn_OF.f90 | 28 ++++++++++++++++------ validation/scripts/openfast_lin_torsion.py | 5 ++-- 8 files changed, 63 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6cc37ca8..0343d60e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,15 +54,16 @@ All notable changes to CableDyn are recorded in this file. The format follows continues bit for bit. - OpenFAST linearisation of finite-EI lines restrained in torsion: the twist angles of the nodes the end frames do not hold, and their rates, are continuous states (`Cable 1 node 2 twist, - rad`); the coupled point's orientation turns the line's End A frame, its angular velocity and - acceleration reach the torsional damping and the held end section's inertia, and the fairlead + rad`); the coupled point's orientation turns the torsion frame of the line's coupled + (host-driven) end, its angular velocity and acceleration reach the torsional damping and the + held end section's inertia, and the fairlead moment carries the torque. A straight line's torsional modes from the eigenvalues of `A` are the lumped chain's to 5e-14 (the continuum's `nπ/L √(GJ/Irn)` less the discretisation error, 1.6e-4 for the first mode at 50 elements) and its roll stiffness `D − C A⁻¹ B` is `GJ/L` to 1.5e-14; a 90° twisted lazy wave matches the deck's static solutions for a rolled and a moved - fairlead to 4.9e-4. Under linearisation the coupled-point rotation is stepped by 1e-4 rad - instead of 0.1 rad, which changes the rotation columns of a deck with a hang-off spring by up - to 0.17 %. + fairlead to 4.9e-4. In a `Linearize = True` run every input Jacobian, those of the time march + included, steps the coupled-point rotation by 1e-4 rad instead of 0.1 rad, which changes the + rotation columns of a deck with a hang-off spring by up to 0.17 %. - OpenFAST linearisation with the line dynamics, as MoorDyn-F's: the continuous states are the interior-node positions of every `EI = 0` line (MoorDyn's names and order) and the free degrees of freedom of every finite-EI cable (node positions and tangents), then their diff --git a/VALIDATION.md b/VALIDATION.md index 142f3d4f..0a582143 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -410,7 +410,7 @@ scripts, results, and source provenance are in - *Linearisation of a line restrained in torsion* ([`validation/scripts/openfast_lin_torsion.py`](https://github.com/SMI-Lab-Inha/CableDyn/blob/main/validation/scripts/openfast_lin_torsion.py), same case): the twist angles of the free nodes and their rates are states, and the platform - rotation turns the End A frame. A straight, taut 100 m line (`GJ` 5e4 N·m², `Irn` 2 kg·m, 50 + rotation turns the torsion frame of the coupled (host-driven) end. A straight, taut 100 m line (`GJ` 5e4 N·m², `Irn` 2 kg·m, 50 elements, rigid in torsion at both ends) has torsional modes in the eigenvalues of `A` equal to the lumped chain's `2 √(GJ/Irn)/h sin(nπ/2N)` to 5e-14. They lie −1.6e-4, −6.6e-4 and −1.5e-3 below the continuum's `nπ/L √(GJ/Irn)`, the discretisation error. The fairlead moment @@ -424,8 +424,9 @@ scripts, results, and source provenance are in reciprocal moment row. `tests/test_lin_torsion.f90` repeats the straight-line gates with the shell's evaluation sequence on the aggregate. It adds the condensed torsion, an elastic torsional end (`1/(L/GJ + 1/kₜ)`), and the platform's angular rates: `Bt/L` per unit angular - velocity and the held end section's `Irn lₑ/2` per unit angular acceleration. Under - linearisation the platform rotation is stepped by 1e-4 rad instead of 0.1 rad. On a straight + velocity and the held end section's `Irn lₑ/2` per unit angular acceleration. In a + `Linearize = True` run every input Jacobian steps the platform rotation by 1e-4 rad instead of + 0.1 rad. On a straight line with a 2e5 N·m/rad hang-off spring, this brings the force per unit rotation to 4e-8 of the static solutions (6.8e-6 with 0.1 rad). diff --git a/doc/coupling.rst b/doc/coupling.rst index 5ce5b2f1..a5097995 100644 --- a/doc/coupling.rst +++ b/doc/coupling.rst @@ -27,7 +27,8 @@ angle convention visible directly in an OpenFAST run log. The module covers Moor integration surface: coupled time-domain analysis at a 0.1 s CableDyn step by default (with deck ``dtM`` control), a nonzero initial platform displacement (``PtfmInit``), glue correction iterations (``NumCrctn > 0``), SeaState wave/current kinematics on the moorings and finite-EI cables, -checkpoint-restart, quasi-static linearisation (``dYdu``), FAST.Farm farm-level shared moorings +checkpoint-restart, linearisation with the line dynamics (the line, cable and twist states, as +MoorDyn-F's; see :doc:`openfast`), FAST.Farm farm-level shared moorings (``Mod_SharedMooring = 5``), coupled ``Rigid6`` 6-DOF rigid bodies (buoyancy, ``C33``/``C44``/``C55`` hydrostatic restoring, restart state, and SeaState drag / Froude-Krylov / added-mass), including MoorDyn-F's coupled pinned bodies (``CoupledPinned``, force only), coupled @@ -36,12 +37,14 @@ coupled rigid rods with host-driven endpoints, correction rewind, checkpoint sta Gauss SeaState sampling, including MoorDyn-F's coupled pinned rods (``CoupledPinned``, force only) and rods pinned to a fixed point. -The input/output Jacobian has two deliberately different contracts. During an ordinary nonlinear -OpenFAST run, CableDyn returns the partial direct-feedthrough derivative at fixed committed internal -state, which is the derivative required by OpenFAST's algebraic input/output solve. During formal -linearisation, where CableDyn exposes a zero-state quasi-static representation, it instead returns -the re-equilibrated zero-frequency mooring stiffness. Substituting the latter into the runtime glue -solve is mathematically incorrect; changing ``NumCrctn`` does not change that derivative contract. +The input/output Jacobian is a partial derivative in both kinds of run. During an ordinary +nonlinear OpenFAST run, CableDyn returns the direct-feedthrough derivative at fixed committed +internal state, which is the derivative OpenFAST's algebraic input/output solve requires. During +formal linearisation (``Linearize = True``) the line and cable degrees of freedom, and the twist +angles of a line restrained in torsion, are continuous states, and ``A``, ``B``, ``C`` and ``D`` +are partial derivatives of the line dynamics at the operating point; the static mooring stiffness +is their zero-frequency reduction ``D − C A⁻¹ B``, not a derivative CableDyn returns. Changing +``NumCrctn`` does not change either contract. .. admonition:: Remaining integration surface :class: warning diff --git a/doc/coupling_boundary.md b/doc/coupling_boundary.md index 666c336d..d2276308 100644 --- a/doc/coupling_boundary.md +++ b/doc/coupling_boundary.md @@ -59,10 +59,12 @@ contributions. The `eps_fd` argument must be non-negative and does not affect th call leaves the handle at the supplied operating point; a caller that needs its previous state must save and restore it. -**Two derivative contracts in OpenFAST.** During a nonlinear OpenFAST run the shell returns the +**Derivatives in OpenFAST.** During a nonlinear OpenFAST run the shell returns the direct-feedthrough derivative at fixed committed internal state, which the host's input–output -solve requires. During linearisation it returns the re-equilibrated zero-frequency mooring -stiffness. The two are not interchangeable. +solve requires. During linearisation the line and cable degrees of freedom (with the twist angles +of a line restrained in torsion) are continuous states and the shell returns the partial +derivatives `A`, `B`, `C`, `D` of the line dynamics; the static mooring stiffness is their +zero-frequency reduction `D − C A⁻¹ B` (see [OpenFAST](openfast.rst)). ## Cadence @@ -126,7 +128,7 @@ point mesh. It supports: - nonzero `PtfmInit` and correction iterations; - checkpoint/restart, with continuous states (including constitutive and rigid-body states) stored in the OpenFAST state record; -- quasi-static linearisation; +- linearisation with the line dynamics (line, cable and twist states, as MoorDyn-F's); - FAST.Farm shared moorings; - line failures, and active tension control of `EI = 0` lines and finite-EI cables; - WaterKin files with independent selection of host wave and host current. SeaState's standard diff --git a/doc/driver_format.md b/doc/driver_format.md index c32d44eb..e4f9575a 100644 --- a/doc/driver_format.md +++ b/doc/driver_format.md @@ -882,9 +882,9 @@ without a body or through the C API's `CableDyn_InitDeck`/`InitDeckAt`, which mo ends by translation only (`a line restrained in torsion needs a host that turns its fairlead frame ...`; with a body such a deck runs on the multibody route, which supports torsion, and a C API host passes its rotations after `CableDyn_InitDeckRotating`), and a `Torq`/`Twist` channel -on a line that is not restrained at both ends. OpenFAST linearisation takes the twist angles as -states (as for any line, not with a `Rigid` bending connection). Seabed friction does not resist -twist (the laid part of a line twists freely), and there +on a line that is not restrained at both ends. OpenFAST linearisation includes the twist angles +as states; like any cable, the line must not have a `Rigid` bending connection there. Seabed +friction does not resist twist (the laid part of a line twists freely), and there is no torque–tension coupling. ### EQUIVALENT BUOYANCY (optional) diff --git a/doc/openfast.rst b/doc/openfast.rst index 37e6bcfe..7341ece8 100644 --- a/doc/openfast.rst +++ b/doc/openfast.rst @@ -451,12 +451,17 @@ A line restrained in torsion adds the twist angle of every node that its end fra (all nodes but a torsionally ``Rigid`` end), after the cables' positions and tangents, and their rates after the cables' velocities: ``Cable 1 node 2 twist, rad`` and ``Cable 1 node 2 twist rate, rad/s``. The angles' accelerations come from the same evaluation as the cable's, with their -polar inertia ``Irn``. The coupled point's orientation turns the line's End A frame, so a platform -rotation twists the line; the point's angular velocity and acceleration turn the frame too, for the -torsional damping ``Bt`` and the held end section's polar inertia. The fairlead moment carries the -torque. Angles are stepped by 1 µrad and their rates by 0.01 rad/s, both of which enter linearly; the -coupled-point rotation is stepped by 1e-4 rad (a rotation moves no node, so no contact or slack -limits it, and the turn of an end frame or connection direction is nonlinear). +polar inertia ``Irn``. The coupled point's orientation turns the torsion frame of the line's +coupled (host-driven) end, so a platform rotation twists the line; the point's angular velocity and +acceleration turn that frame too, for the torsional damping ``Bt`` and the held end section's polar +inertia. The fairlead moment carries the torque. Angles are stepped by 1 µrad, as positions, and +their rates by 0.01 rad/s (they enter only the linear damping). In a ``Linearize = True`` run the +coupled-point rotation is stepped by 1e-4 rad, also in the input Jacobians of the time march +before the linearisation times (a rotation moves no node, so no contact or slack limits it, and the +turn of an end frame or connection direction is nonlinear); a run without linearisation keeps +0.1 rad. The ``.lin`` operating-point outputs are those of the committed step; at a settled +operating point, such as the still-water start, they lie on the linearised surface, while at a +moving one the accelerations and the end-frame rates of the last step enter them. The zero-frequency reduction ``D − C A⁻¹ B`` is the static mooring stiffness. It agrees with MoorDyn-F and with CableDyn's own static solutions (:doc:`validation`). Quadratic drag has no diff --git a/src/openfast/CableDyn_OF.f90 b/src/openfast/CableDyn_OF.f90 index e56f7910..55864a9f 100644 --- a/src/openfast/CableDyn_OF.f90 +++ b/src/openfast/CableDyn_OF.f90 @@ -2949,9 +2949,18 @@ SUBROUTINE lin_eval( id, p, m, u, x_in, ErrStat, ErrMsg, dxdt, y_out ) CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: '//TRIM(em), ErrStat, ErrMsg, RoutineName ) CALL restore; RETURN END IF + ! (The operating-point outputs of the .lin file come from CD_CalcOutput, which keeps the + ! committed state's accelerations and the end-frame rates of its last step's turn; at a + ! settled operating point, such as the still-water start the documentation prescribes, + ! they are those of this surface, and the matrices are differences of this surface alone.) DO ic = 1, Inst(id)%agg%ncable CALL CD_HFMF_Set_Twist_Frame_Rates( Inst(id)%agg%cables(ic), es, em ) - IF (es == CD_HFMF_OK) CALL CD_HFMF_Refresh_Acceleration( Inst(id)%agg%cables(ic), es, em ) + IF (es /= CD_HFMF_OK) THEN + CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))// & + ' torsion end-frame rates: '//TRIM(em), ErrStat, ErrMsg, RoutineName ) + CALL restore; RETURN + END IF + CALL CD_HFMF_Refresh_Acceleration( Inst(id)%agg%cables(ic), es, em ) IF (es /= CD_HFMF_OK) THEN CALL SetErrStat( ErrID_Fatal, 'CableDyn mooring module: cable '//TRIM(Num2LStr(ic))// & ' acceleration: '//TRIM(em), ErrStat, ErrMsg, RoutineName ) @@ -3532,16 +3541,21 @@ SUBROUTINE CD_InitVars(Vars, u, p, x, y, m, inst_, Linearize, ErrStat, ErrMsg) ! the constitutive states: a viscoelastic slow-branch stretch (m) takes the position step, ! a Syrope slow strain the strain of a micrometre over a metre REAL(R8Ki), PARAMETER :: LIN_DSLOW = 1.0E-6_R8Ki - ! the nodal twist: an angle enters the element twists and torques linearly, so the angle - ! step takes the position step's 1e-6 (rad), and its rate only the linear torsional - ! damping, so any rate step is exact up to round-off: 0.01 rad/s + ! the nodal twist: at a fixed configuration the element twist phi_{e+1} - phi_e + rho_e(q) + ! (with GJ|K, + (K/GJ)(l_e - l0), which the angles do not change) and so the torques and + ! their forces M_e drho_e/dq on the cable are affine in the angles; the coupling of the + ! angles to the configuration (rho_e, the stretch) is not, and the angle takes the + ! position step's 1e-6 rad, as the r and m it is differenced with. A rate enters only the + ! linear torsional damping, so any rate step is exact up to round-off: 0.01 rad/s REAL(R8Ki), PARAMETER :: LIN_DPHI = 1.0E-6_R8Ki, LIN_DW = 1.0E-2_R8Ki - ! the coupled-point rotation step under linearization: a rotation moves no node, so + ! the coupled-point rotation step of a linearization run: a rotation moves no node, so ! neither contact nor slack constrains it, and the turn of a torsion end frame about axes ! across its director (a solid angle) or of an end connection's direction is nonlinear: ! 1e-4 rad keeps the central difference's O(h^2) error near 1e-9 and the difference of the - ! moments and accelerations some eight digits above round-off (the time-domain input - ! Jacobian keeps 0.1 rad) + ! moments and accelerations some eight digits above round-off. In a Linearize run every + ! input Jacobian goes through lin_eval with this step, the glue's time-domain + ! input-output solves before the linearization times included; a run without + ! Linearize keeps 0.1 rad REAL(R8Ki), PARAMETER :: LIN_DROT = 1.0E-4_R8Ki LOGICAL, ALLOCATABLE :: lin1m(:) INTEGER(IntKi) :: kind1, ntw diff --git a/validation/scripts/openfast_lin_torsion.py b/validation/scripts/openfast_lin_torsion.py index faa389e0..6efbe120 100644 --- a/validation/scripts/openfast_lin_torsion.py +++ b/validation/scripts/openfast_lin_torsion.py @@ -54,7 +54,6 @@ from __future__ import annotations import argparse -import re import subprocess import sys from pathlib import Path @@ -62,7 +61,7 @@ import numpy as np sys.path.insert(0, str(Path(__file__).resolve().parent)) -import openfast_lin_ab as ab # noqa: E402 +import openfast_lin_ab as ab RHOW = 1025.0 GJ = 5.0e4 @@ -202,7 +201,7 @@ def driver_solve(driver: Path, text: str, work: Path) -> dict: "--------------------- OUTPUTS", 1) (work / "trial.dat").write_text(text) proc = subprocess.run([str(driver), "trial.dat", "trial"], cwd=work, capture_output=True, text=True, - timeout=3600) + timeout=3600, check=False) if proc.returncode != 0: tail = "\n".join((proc.stdout + proc.stderr).splitlines()[-15:]) ab.die(f"driver failed:\n{tail}") From 952d02fa825e8d2a255209ed1a26703c96b1df92 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 15:35:15 +0900 Subject: [PATCH 3/7] feat(torsion): active line control of lines restrained in torsion Active line control (deck CONTROL, CD_HermiteCable_Dyn_Set_SegmentLength) refused a finite-EI line restrained in torsion. It now takes it, and every torsion quantity that depends on l0 follows the length change: - read at evaluation, as before: the condensed compliance sum l0/GJ, the nodal twist's GJ/l0 and Bt/l0, the coupling term (K/GJ)(l - l0) and the element shape. The committed force keeps them at the committed lengths (enter/leave_committed_lengths), the step's force takes the new ones, as for the rest of the residual, so a ramp does not lag at alpha_f > 0. - rebuilt with the length caches (new torsion_length_terms, also when the committed-state evaluation hands the present lengths back): the lumped polar inertia Irn l0/2 and a torsional damping given as -zeta, which the torsion now keeps (CD_HermiteTorsionType bt_zeta, set by the deck) and re-resolves as zeta l0 sqrt(GJ Irn) (CD_HermiteTorsion_Zeta_Damping, the deck's own formula); a direct Bt stays. The torsion query cache is dropped on a length change. - the torsional damping takes the rate of the twist per length, as the axial damping takes the strain rate: M = (GJ/l0) tau + (Bt/l0)(tau_dot - tau l0_dot/l0), with tau_dot gaining (l0_dot/l0)(m . g_m - (K/GJ) l0) (the reference twist depends on m only through l0 m and m/|m|), and the matching tangent. - the snapshot and the recovering step keep the committed torque as it was formed instead of re-deriving it with the present lengths. No new restart state: the torsion terms are functions of the lengths, which the shell re-applies before the mirror reload. test_control_torsion: - Q: a taut line paid out and hauled in carries GJ Phi/L(t) + K (H - L)/L (condensed 2.8e-16 and 9.6e-15 with K, nodal twist 1.5e-12; a frozen compliance misses by 6.5e-3 and 0.23) and the tension EA (H - L)/L + K Phi/L to 3.6e-6; - D: a constant pay-out under GJ|K|Bt carries GJ chi + Bt chi_dot to 5.8e-6 N m of a 0.642 N m damping share; without the rate 0.646; - F: the length-rate damping on a bowed line equals Bt l0_dot d(tau/l0)/dl0 by central differences to 1.1e-10 (the straight-line value is 1.7 % off); - Z: the inertia and damping a command rebuilds equal a fresh build bit for bit; a committed-state evaluation takes the committed lengths and leaves the present ones; saved control and a snapshot taken between a command and its step take it back, the committed torque included; - E: a pay-out under a ringing twist (real Irn, rho_inf 1) changes the energy by the work of the length change to 7.8e-5 of it; - L: a slow pay-out at rho_inf 0.4 follows rho_inf 0 to 1.4e-3 of the per-step torque change, also with the committed force evaluated afresh each step (at the new lengths it lags by alpha_f of the change, 0.29); - R, S: restarts mid-ramp from a snapshot, a checkpoint mirror and a CONTROL deck on the coupled aggregate are bit-identical; the deck keeps and re-resolves its -zeta damping, and its Torq1N1 follows GJ Twist1/L(t) to 6e-11 (its torsional damping included). Ablations of the rate term, the rebuilt terms, their hand-back, the committed-length force and the snapshot torque each fail a gate. Full suite passes; all 53 example decks are bit-identical. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 8 + CMakeLists.txt | 12 + VALIDATION.md | 24 + doc/capabilities.rst | 3 +- doc/driver_format.md | 15 +- doc/openfast.rst | 3 +- doc/theory.rst | 42 +- src/CableDyn_DeckDriver.f90 | 21 +- src/CableDyn_HermiteCableDynamic.f90 | 123 +++- src/CableDyn_HermiteTorsion.f90 | 33 + tests/test_control_torsion.f90 | 898 +++++++++++++++++++++++++++ tests/test_hermite_cable_control.f90 | 10 +- 12 files changed, 1147 insertions(+), 45 deletions(-) create mode 100644 tests/test_control_torsion.f90 diff --git a/CHANGELOG.md b/CHANGELOG.md index 0343d60e..c4e1e63c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -95,6 +95,14 @@ All notable changes to CableDyn are recorded in this file. The format follows and the OpenFAST checkpoint mirror. Decks with torsion whose `Irn` was a placeholder (the column was unused before) need the section's real value. The Python deck reader and builder take `GJ|K|Bt` (builder `gj=(GJ, K, Bt)`). +- Active line control (`CONTROL`) of a finite-EI cable restrained in torsion, which was refused: + the torsional compliance, the nodal twist's `GJ`/l and `Bt`/l, the torque–tension coupling and + the polar inertia take the new lengths, a `-ζ` torsional damping keeps its `ζ`, and the damping + acts on the rate of the twist per length. A taut line paid out and hauled in carries + `GJ Φ/L(t) + K (H − L)/L` to 1.5e-12 and its tension to 4e-6; a constant pay-out carries the + Kelvin–Voigt torque to 6e-6 N m of its 0.64 N m damping share; a pay-out under a ringing twist + balances the energy to 8e-5 of the work done; restarts mid-ramp (snapshot, checkpoint mirror, + a coupled deck) are bit-identical. - Torque–tension coupling of finite-EI cables: the 14-column LINE TYPES row's `GJ` column takes `GJ|K`, with `K` the coupling of an armoured cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`). The cable carries the axial stiffness `EA − K²/GJ` of a section free to twist. diff --git a/CMakeLists.txt b/CMakeLists.txt index 14132b7a..50fba05f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -715,6 +715,15 @@ target_link_libraries(test_hermite_cable_control PRIVATE cabledyn_core) add_test(NAME hermite_cable_control COMMAND test_hermite_cable_control) set_tests_properties(hermite_cable_control PROPERTIES LABELS "fortran;unit;dynamic;hermite") +# Active line control of a line restrained in torsion: the quasi-static torque GJ Phi/L(t) (with +# torque-tension coupling), the torsional damping of the twist per length, the length terms a +# fresh build carries, the energy of a length change with a real Irn, no lag at alpha_f > 0, +# restart mid-ramp (snapshot, mirror) and a CONTROL deck on the coupled aggregate. +add_executable(test_control_torsion tests/test_control_torsion.f90) +target_link_libraries(test_control_torsion PRIVATE cabledyn_core) +add_test(NAME control_torsion COMMAND test_control_torsion WORKING_DIRECTORY ${CMAKE_BINARY_DIR}) +set_tests_properties(control_torsion PROPERTIES LABELS "fortran;unit;dynamic;hermite;openfast") + add_executable(test_hermite_added_mass tests/test_hermite_added_mass.f90) target_link_libraries(test_hermite_added_mass PRIVATE cabledyn_core) add_test(NAME hermite_added_mass COMMAND test_hermite_added_mass) @@ -2845,6 +2854,7 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU") test_hermite_drag_dynamics test_hermite_axial_damping test_hermite_cable_control + test_control_torsion test_endconn_spring test_torsion_coupling) target_compile_options(${_cabledyn_exact_real_test} PRIVATE -Wno-compare-reals) @@ -2857,6 +2867,7 @@ if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU") target_compile_options(test_hermite_cable_control PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized) target_compile_options(test_syrope_control PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized) target_compile_options(test_viscoelastic_control PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized) + target_compile_options(test_control_torsion PRIVATE -Wno-uninitialized -Wno-maybe-uninitialized) endif() if(CABLEDYN_ENABLE_COVERAGE) @@ -2908,6 +2919,7 @@ if(CABLEDYN_ENABLE_COVERAGE) test_hermite_drag_dynamics test_hermite_axial_damping test_hermite_cable_control + test_control_torsion test_hermite_added_mass test_hermite_wave_forcing test_lazywave_dynamics diff --git a/VALIDATION.md b/VALIDATION.md index 0a582143..831ddfa8 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -102,6 +102,7 @@ article's methods, are compared in | **T-8** | Cross-check with the Cosserat rod path | Cosserat path | shape 4.2e-4 L, torque 5.2e-5 | <1% | Pass | | **T-9** | Bordered Newton step on post-buckled states | predicted linear rate without the rank-one term | 3 iterations; rate 0.055 / 0.217 vs 0.055 / 0.218 | ≤4; within 25% | Pass | | **T-10** | Torsion dynamics, restart and body torque | quasi-static torque, energy, uninterrupted run, pendulum | torque 2.2e-16; energy band 4.9e-4; restart bit-identical; pendulum 6.4e-5 | see [Torsion](#torsion) | Pass | +| **T-14** | Active line control of a line restrained in torsion | `GJ Φ/L(t) + K (H − L)/L`; Kelvin–Voigt torque of a pay-out; finite differences; energy of a length change; `ρ∞ = 0`; uninterrupted run | torque ≤1.5e-12, tension 3.6e-6; damping 5.8e-6 N·m of 0.64 N·m; FD 1.1e-10; energy 7.8e-5; no lag (1.4e-3 of the per-step change); restart bit-identical | see [Torsion](#torsion) | Pass | | **T-13** | Nodal twist (torsional inertia and damping) | condensed torsion in the limit of no inertia; continuum torsional wave; `ζ = ω Bt/(2 GJ)`; energy; restart | ≤6e-7 against the condensed torsion; wave torque 0.07 %; decrement 6 %; energy band 4.9e-4; restart bit-identical | see [Torsion](#torsion) | Pass | | **T-12** | Torque–tension coupling | `T = EA ε + K τ`, `M = GJ τ + K ε` closed forms; kernel FD; march | ≤1e-7 against every closed form; kernel gradient 1.7e-10, Hessian 9.8e-11 | see [Torsion](#torsion) | Pass | | **T-11** | Torsion on the coupled OpenFAST / FAST.Farm route | `GJ (−roll)/L`; single coupled cable; uninterrupted run | twist ≤1.8e-15°, torque ≤1.7e-13 N·m; aggregate = single cable bit for bit; restart bit-identical (aggregate and `openfast -restart`) | see [Torsion](#torsion) | Pass | @@ -1047,6 +1048,29 @@ in parentheses). roll (`GJ (−roll)/l_e`) against the frozen interior. The example `torsion_lazy_wave_hangoff_twist.dat` (Irn of the section) moves by at most 7e-5 of the torque against the condensed torsion. +- **T-14 active line control** (`control_torsion`). The fairlead span (2 of 10 elements) of a + taut straight line between rigid torsional ends 10.1 m apart (EA 1e5 N, GJ 80 N·m², + `Φ = 90°`) is commanded: + - paid out and hauled in by ±0.065 m over 10 s, the line carries `GJ Φ/L(t) + K (H − L)/L` + (condensed 2.8e-16, with `K = 500 N·m` 9.6e-15, nodal twist with `Irn = 1e-9 kg·m` + 1.5e-12; a frozen compliance would miss by 6.5e-3 and 0.23) and the tension + `EA (H − L)/L + K Φ/L` with the axial damping's share to 3.6e-6; + - paid out at 0.01 m/s under `Bt = 100 N·m²·s` with `K`, every element keeps one twist per + length χ and the torque is `GJ χ + Bt χ̇` to 5.8e-6 N·m of its 0.642 N·m damping share + (0.646 N·m off without the length rate); + - on a bowed line the length-rate share of the damping torque equals `Bt l̇0 ∂(τ/l0)/∂l0` by + central differences of the element twist to 1.1e-10 (1.7 % from the straight-line value); + - the polar inertia and a `-ζ` damping a command rebuilds equal those of a model built with + the new lengths bit for bit, and a committed-state evaluation, a saved control state and a + snapshot take the committed lengths and terms; + - paid out by 0.5 m under a ringing twist (`Irn = 0.5 kg·m`, `ρ∞ = 1`, centreline held), the + twist and polar kinetic energy change by the work of the length change to 7.8e-5 of it; + - paid out slowly, the run at `ρ∞ = 0.4` follows the one at `ρ∞ = 0` to 1.4e-3 of the + per-step torque change, also with the committed force evaluated afresh each step (taken at + the new lengths it lags by `α_f` of the change, 0.29); + - restarts mid-ramp from a snapshot, from the checkpoint mirror with the command re-applied, + and of a `CONTROL` deck on the coupled aggregate (whose `Torq1N1` follows `GJ Twist1/L(t)` + to 6e-11) continue bit-identically. - **Backward compatibility and refusals** (`torsion_deck`, full suite). Without torsion columns, with `Free` columns (whatever their normal), or with one restrained end, every output is byte-identical to the 6-column deck, and `Rigid`, `Infinity`, `Inf` and a quoted `"Rigid"` diff --git a/doc/capabilities.rst b/doc/capabilities.rst index 53d7337a..49b453e5 100644 --- a/doc/capabilities.rst +++ b/doc/capabilities.rst @@ -95,7 +95,8 @@ Line and constitutive capability column standalone, and with the platform orientation in coupled OpenFAST and FAST.Farm runs (torque returned to the platform, ``PtfmInit``, checkpoints, linearisation with the twist angles as states; see :doc:`openfast`) and through the C API with the host's - rotations (``CableDyn_InitDeckRotating``, :doc:`capi`); ``Torq``/``Twist`` channels and + rotations (``CableDyn_InitDeckRotating``, :doc:`capi`), active line control + (``CONTROL``) of the fairlead segment on the coupled route; ``Torq``/``Twist`` channels and standalone range graphs. Stopped by name: the standalone mixed ``EI = 0`` + finite-EI aggregate and ``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by translation only), rod ends, bodies other than Rigid6, modal analysis, and diff --git a/doc/driver_format.md b/doc/driver_format.md index e4f9575a..84306960 100644 --- a/doc/driver_format.md +++ b/doc/driver_format.md @@ -274,8 +274,9 @@ cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`; see `GJ|K|Bt` adds the torsional damping `Bt` [N·m²·s] of the nodal twist (the torque `Bt dτ/dt`, stiffness-proportional: a torsional mode of frequency `ω` has the damping ratio `ω Bt/(2 GJ)`); a negative `Bt` is `-ζ`, the fraction of an element's critical torsional damping -`l0 √(GJ Irn)` on the final mesh, as `BA` is for the axial damping. It needs a finite-EI type; -`GJ|0|Bt` is damping without coupling. +`l0 √(GJ Irn)` on the final mesh, as `BA` is for the axial damping (an element whose length +active line control changes keeps its `ζ`). It needs a finite-EI type; `GJ|0|Bt` is damping +without coupling. **Viscoelastic axial stiffness (MoorDyn `ElasticMod`).** The EA and BA columns accept bar-separated parts: @@ -1143,8 +1144,14 @@ bounds that would make it zero or negative (possible when it is shorter than hal the bounds above, a cable of one section scales each element within [0.5, 2] of its initial length; on a cable of several sections the scaling can leave that range, beyond the resolution its static mesh was built for, so keep large commands on a fairlead section whose - segments are at least `UnstrLen`/N long. A cable restrained in torsion cannot be controlled - (the coupled route rejects torsion stiffness in END CONNECTIONS). + segments are at least `UnstrLen`/N long. +- On a cable restrained in torsion at both ends the torsion follows the lengths too: the line's + torsional compliance, the elements' torsional stiffness `GJ`/l and damping `Bt`/l, the + torque–tension coupling and the polar inertia `Irn` l/2 at the nodes take the new lengths, a + torsional damping written as `-ζ` keeps its `ζ` (`Bt` = ζ l √(GJ `Irn`) at the new length; a + positive `Bt` stays), and the damping acts on the rate of the twist per unit length, so a + segment paid out at constant twist per length carries no damping torque. A haul-in raises the + torque of a fixed end-to-end twist as `GJ` Twist/L does. The host input arrays are sized to the highest channel id. diff --git a/doc/openfast.rst b/doc/openfast.rst index 7341ece8..3ba7a555 100644 --- a/doc/openfast.rst +++ b/doc/openfast.rst @@ -382,7 +382,8 @@ without an auxiliary process: (:doc:`driver_format`, CONTROL). A viscoelastic or Syrope polyester segment carries its slow stretch over the length change, as MoorDyn-F and MoorDyn-C do. On a finite-EI cable the command scales every cable element - of that segment, and needs the force-blended generalised-α (the default). On both kinds a + of that segment, and needs the force-blended generalised-α (the default); on a cable + restrained in torsion the torsion follows the new lengths (:ref:`theory-torsion`). On both kinds a command outside MoorDyn-F's bounds, from minus half to plus one ``UnstrLen``/N of the line (the controlled segment's initial length on a line of one section), stops the run with a message that names the line, as it stops MoorDyn-F; so does a command that would make the diff --git a/doc/theory.rst b/doc/theory.rst index f1098f58..e32ab2b9 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -559,6 +559,45 @@ between steps (the direct feedthrough) twists the end element against the frozen the end's translation stretches it. The node torque (``TorqN``) is the mean of its two elements', and the material twists of the elements sum to the twist channels. +**Active line control.** A length command on a controlled element (see Active line control +below) changes every torsion term that reads :math:`L_0`: the condensed compliance +:math:`C = \sum_e L_{0,e}/GJ_e + 1/k_1 + 1/k_2`, the element stiffness :math:`GJ/L_0` and damping +:math:`B_t/L_0` of the nodal twist, the coupling term :math:`(K/GJ)(l - L_0)` and, through the +Hermite interpolant, the element holonomy. Each is evaluated with the lengths of its time level, +as the rest of the residual: the committed force with the lengths the committed state was reached +with, the step's force with the new ones. The lumped polar inertia :math:`I_{rn} L_0/2` is rebuilt +with the consistent mass (its rate term is not modelled either), and a torsional damping written +as :math:`-\zeta` is resolved again at the new length, :math:`B_t = \zeta L_0 \sqrt{GJ I_{rn}}`, so +the element keeps its fraction of critical damping; a positive :math:`B_t` is a section property +and stays (the axial ``BA`` keeps its initial resolution, as in MoorDyn). The torsional damping +takes the rate of the twist per unit length :math:`\hat\tau/L_0` that the elastic torque reads, as +the axial damping takes the rate of the strain: + +.. math:: + + M_e = \frac{GJ_e}{L_{0,e}}\,\hat\tau_e + B_{t,e}\,\frac{d}{dt}\frac{\hat\tau_e}{L_{0,e}} + = \frac{GJ_e}{L_{0,e}}\,\hat\tau_e + \frac{B_{t,e}}{L_{0,e}} + \Big(\dot{\hat\tau}_e - \hat\tau_e\,\frac{\dot L_{0,e}}{L_{0,e}}\Big) . + +At fixed :math:`\mathbf{q}` the twist changes with :math:`L_0` through the coupling term and the +element's shape. The reference twist depends on the tangent handles only through +:math:`L_0\mathbf{m}` (the Hermite :math:`\mathbf{r}'` and :math:`\mathbf{r}''`) and +:math:`\mathbf{m}/|\mathbf{m}|`, and so does :math:`l_e`, so +:math:`L_0\,\partial(m_e + c_e l_e)/\partial L_0 = \mathbf{m}_1\cdot\partial/\partial\mathbf{m}_1 + +\mathbf{m}_2\cdot\partial/\partial\mathbf{m}_2` of the same with :math:`c_e = K_e/GJ_e`, and + +.. math:: + + \dot{\hat\tau}_e = \dot\varphi_{k+1} - \dot\varphi_k + \nabla\hat\tau_e\cdot\dot{\mathbf{q}} + + \frac{\dot L_{0,e}}{L_{0,e}}\Big(\mathbf{m}_1\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{m}_1} + + \mathbf{m}_2\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{m}_2} - c_e L_{0,e}\Big) , + +with the matching tangent terms. A segment paid out at a constant twist per length carries no +damping torque. The test suite checks the quasi-static torque :math:`GJ\Phi/L(t) + K(H - L)/L` of a +taut line paid out and hauled in (condensed and nodal twist), the Kelvin–Voigt torque of a constant +pay-out, the length-rate term against finite differences on a bowed line, the energy a length +change puts into a ringing twist, and that the step does not lag at :math:`\alpha_f > 0`. + **Limits.** Seabed friction does not resist twist, so the laid part of a line twists freely (the friction torque of a cable on the seabed can be comparable with the twist torque near touchdown). There is no anisotropic or pre-twisted section, and no self-contact: a loop that @@ -2869,7 +2908,8 @@ the end-position part, and a segment paid out at constant strain carries no damping force. The position Jacobian of the damping force gains :math:`-BA\, H'_a H'_b\, (\dot L_0/L_0^2)\, \mathbf{t}\mathbf{t}^\mathsf{T}` on -the end-position columns. +the end-position columns. On a cable restrained in torsion the torsion follows the lengths in the +same way (:ref:`theory-torsion`, Active line control). Tension and coupled loads ------------------------- diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index b922d085..d8bbf840 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -113,7 +113,7 @@ MODULE CableDyn_DeckDriver CD_HermiteCable_Dyn_Element_Twist, CD_HermiteCable_Dyn_Coupling_Tension, & CD_HermiteCable_Dyn_Node_Torque, CD_HermiteCable_Dyn_End_Twist USE CableDyn_HermiteTorsion, ONLY: CD_HermiteTorsionType, CD_HermiteTorsion_Compliance, CD_HTORS_MAX_STEP, & - CD_HTORS_MAX_TWIST + CD_HTORS_MAX_TWIST, CD_HermiteTorsion_Zeta_Damping USE CableDyn_EndConnection, ONLY: CD_ENDCONN_PINNED, CD_ENDCONN_FINITE, CD_ENDCONN_RIGID USE CableDyn_Vessel, ONLY: CD_VesselRAOType, CD_Vessel_Euler_DCM, CD_Vessel_Euler_Angular, & CD_Vessel_Point_Kinematics, CD_Vessel_RAO_Set, CD_Vessel_RAO_Eval, & @@ -372,7 +372,8 @@ MODULE CableDyn_DeckDriver REAL(wp) :: ktt = CD_ZERO ! torsional damping Bt [N m^2 s] of the GJ column's third part (GJ|K|Bt), the torque Bt dtau/dt ! of the nodal twist; negative: -zeta, the fraction of an element's critical torsional - ! damping l0 sqrt(GJ Irn), resolved on the final mesh + ! damping l0 sqrt(GJ Irn), resolved on the final mesh (and again at the lengths active line + ! control sets) REAL(wp) :: bt = CD_ZERO REAL(wp) :: i_rt = CD_ZERO, i_rn = CD_ZERO REAL(wp) :: cdn = CD_ZERO, cdt = CD_ZERO, can = CD_ZERO, cat = CD_ZERO @@ -3421,12 +3422,20 @@ SUBROUTINE torsion_stage(est, emt, f_nodal) tors%irn = i_rn_in IF (SIZE(lf) /= SIZE(ld)) CALL remap_elem_by_reference_arc(tors%irn, ld, lf) ! torsional damping (GJ|K|Bt): a negative value is -zeta of an element's critical torsional - ! damping l0 sqrt(GJ Irn), on the final mesh + ! damping l0 sqrt(GJ Irn), on the final mesh; the elements keep their zeta (bt_zeta), so a + ! length change by active line control re-resolves it IF (ANY(ABS(bt_in) > CD_ZERO)) THEN tors%bt = bt_in IF (SIZE(lf) /= SIZE(ld)) CALL remap_elem_by_reference_arc(tors%bt, ld, lf) + IF (ANY(tors%bt < CD_ZERO)) THEN + ALLOCATE (tors%bt_zeta(SIZE(tors%bt))) + tors%bt_zeta = CD_ZERO + END IF DO k = 1, SIZE(tors%bt) - IF (tors%bt(k) < CD_ZERO) tors%bt(k) = -tors%bt(k)*lf(k)*SQRT(tors%gj(k)*tors%irn(k)) + IF (tors%bt(k) < CD_ZERO) THEN + tors%bt_zeta(k) = -tors%bt(k) + tors%bt(k) = CD_HermiteTorsion_Zeta_Damping(tors%bt_zeta(k), lf(k), tors%gj(k), tors%irn(k)) + END IF END DO END IF DO k = 1, 2 @@ -8080,10 +8089,6 @@ SUBROUTINE build_aggregate_control_table(ctrls, lines, points, rods, sections, t CALL fail(ErrStat, ErrMsg, 'CONTROL line '//TRIM(lid)//' has no finite-EI cable'); RETURN END IF ASSOCIATE (cab => agg%cables(obj)%line) - IF (cab%torsion%active) THEN - CALL fail(ErrStat, ErrMsg, 'CONTROL line '//TRIM(lid)//': active line control of a finite-EI '// & - 'line restrained in torsion is not supported'); RETURN - END IF IF (cab%has_contact .AND. .NOT. cab%has_seabed_recompute) THEN CALL fail(ErrStat, ErrMsg, 'CONTROL line '//TRIM(lid)//' was built without the seabed '// & 'recompute inputs'); RETURN diff --git a/src/CableDyn_HermiteCableDynamic.f90 b/src/CableDyn_HermiteCableDynamic.f90 index 03757502..b8f46e9e 100644 --- a/src/CableDyn_HermiteCableDynamic.f90 +++ b/src/CableDyn_HermiteCableDynamic.f90 @@ -83,7 +83,7 @@ MODULE CableDyn_HermiteCableDynamic CD_HermiteTorsion_Element_Stretch, CD_HermiteTorsion_Element, & CD_HermiteTorsion_Stretch_Derivatives, CD_HermiteTwist_Reference, & CD_HermiteTwist_Carry, CD_HermiteTwist_Angle, CD_HermiteTwist_Omega, & - CD_HermiteTwist_Omega_Gradient, CD_HTORS_PI + CD_HermiteTwist_Omega_Gradient, CD_HTORS_PI, CD_HermiteTorsion_Zeta_Damping USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY: INT64 !$ USE OMP_LIB, ONLY: omp_get_max_threads, omp_in_parallel IMPLICIT NONE @@ -248,7 +248,11 @@ MODULE CableDyn_HermiteCableDynamic ! change; from then on l0_dot(ne) holds the unstretched-length rate of every element ! (zero outside the controlled span), which the axial damping subtracts from the strain ! rate. A model that is never controlled leaves has_ctrl false and l0_dot unallocated, so - ! every evaluation is unchanged. BA keeps its initial resolution. + ! every evaluation is unchanged. BA keeps its initial resolution. On a line restrained in + ! torsion every torsion term reads l0 when it is evaluated (the compliance sum l0/GJ, the + ! nodal twist's GJ/l0 and Bt/l0, the coupling term (K/GJ)(l - l0), the element shape), the + ! lumped polar inertia and a -zeta torsional damping are rebuilt with the other caches + ! (torsion_length_terms), and the torsional damping takes the rate of the twist per length. LOGICAL :: has_ctrl = .FALSE. REAL(wp), ALLOCATABLE :: l0_dot(:) ! The lengths and rates the committed state was reached with (allocated with l0_dot, set @@ -445,6 +449,9 @@ MODULE CableDyn_HermiteCableDynamic REAL(wp) :: tors_step_ends(3, 4) = CD_ZERO, tors_step_phi = CD_ZERO REAL(wp) :: tors_drive_ends(3, 4) = CD_ZERO, tors_drive_phi = CD_ZERO REAL(wp) :: snap_torsion_theta = CD_ZERO, snap_torsion_phi = CD_ZERO, snap_torsion_ends(3, 4) = CD_ZERO + ! the committed torque of the snapshot, kept as it was formed (under active line control the + ! committed state's compliance is that of the committed lengths, not of the present ones) + REAL(wp) :: snap_torsion_torque = CD_ZERO ! Torsion query cache (allocation-free read-only queries): Theta, dTheta/d[w_1, w_2] and ! dTheta/dr at both end nodes, evaluated at tors_c_q with the end frames tors_c_ends and ! unwrapped against tors_c_prev. A query uses it only when the model's q, end frames and @@ -1681,11 +1688,17 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_SegmentLength(model, elems, l0_new, l0_dot, E !! A call that changes no length and no rate (bit for bit, a rate of -0 counting as +0) !! returns at once, so a zero command of either sign on an uncontrolled model leaves it !! untouched. The update is atomic: every check and rebuild runs before the model is - !! written. A line restrained in torsion is refused (its condensed torsional compliance - !! has no length-control law here), as is a contact model without the seabed recompute - !! inputs and a model on the configuration-blended generalised-alpha (force blend off, - !! CD_HermiteCable_Dyn_Set_ForceBlend), whose blended state has no committed-length - !! treatment, so a ramp would lag by alpha_f times the length change. restored = .TRUE. (a checkpoint + !! written. On a line restrained in torsion the torsion follows the lengths in the same way: + !! the terms read at evaluation (the condensed compliance sum l0/GJ, the nodal twist's element + !! stiffness GJ/l0 and damping Bt/l0, the coupling term (K/GJ)(l - l0)) take l0 there, the + !! lumped polar inertia Irn l0/2 and a torsional damping given as -zeta (zeta l0 sqrt(GJ Irn)) + !! are rebuilt with the caches, and the committed force keeps its torsion part at l0_c with + !! the rest. The rate enters the torsional damping as it enters the axial one: the damping + !! takes the rate of the twist per length (assemble_twist). A contact model without the seabed + !! recompute inputs is refused, as is a model on the configuration-blended generalised-alpha + !! (force blend off, CD_HermiteCable_Dyn_Set_ForceBlend), whose blended state has no + !! committed-length treatment, so a ramp would lag by alpha_f times the length change. + !! restored = .TRUE. (a checkpoint !! restart re-applying the command the committed state was reached with) makes the !! lengths and rates the committed ones at once; a committed force reloaded with the !! state belongs to them and stays valid. @@ -1722,10 +1735,6 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_SegmentLength(model, elems, l0_new, l0_dot, E IF (ANY(l0_new <= CD_ZERO)) THEN CALL fail('l0 must be positive'); RETURN END IF - IF (model%torsion%active) THEN - CALL fail('a line restrained in torsion is not supported (the condensed torsional compliance '// & - 'has no length-control law)'); RETURN - END IF IF (model%has_contact .AND. .NOT. model%has_seabed_recompute) THEN CALL fail('a seabed-contact model needs the seabed recompute inputs '// & '(CD_HermiteCable_Dyn_Set_Control_Seabed)'); RETURN @@ -1923,8 +1932,9 @@ SUBROUTINE rebuild_length_caches(model, l0_new, ErrStat, ErrMsg) !! the constant mass Mgb (element by element, then the attachment masses), the nodal !! tributary lengths and, on a contact model, the nodal seabed coefficients !! (CD_Nodal_Seabed_Stiffness, as the deck builds them) with the friction spring - !! stiffness that follows them. Everything is built first; the model is written only - !! when every build succeeded. + !! stiffness that follows them, and on a line restrained in torsion the torsion terms built + !! from the lengths (torsion_length_terms). Everything is built first; the model is + !! written only when every build succeeded. TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: model REAL(wp), INTENT(IN) :: l0_new(:) INTEGER, INTENT(OUT) :: ErrStat @@ -1982,15 +1992,38 @@ SUBROUTINE rebuild_length_caches(model, l0_new, ErrStat, ErrMsg) CALL MOVE_ALLOC(cn_new, model%contact_cn) IF (model%fr_active) model%fr_k = model%contact_kn END IF - ! the lumped polar inertia of the nodal twist follows the lengths - IF (model%tw_active) CALL tw_set_derived(model, model%torsion) + CALL torsion_length_terms(model) END SUBROUTINE rebuild_length_caches + SUBROUTINE torsion_length_terms(model) + !! The torsion terms built from the unstretched lengths, from model%l0 in the order + !! initialisation used (CD_HermiteCable_Dyn_Set_Torsion, the deck's torsion stage): the lumped + !! polar inertia of the nodal twist, half of each adjacent element's Irn l0 (tw_set_derived), + !! and the torsional damping of an element given as -zeta, Bt = zeta l0 sqrt(GJ Irn) + !! (CD_HermiteTorsion_Zeta_Damping), so the element keeps its fraction of critical damping. A + !! direct Bt is a section property and stays. The torsion query cache, keyed on the state and + !! not on the lengths, is dropped (Theta depends on l0 through the element shape and the + !! coupling term). Without torsion nothing is written. + TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: model + INTEGER :: e + IF (.NOT. model%torsion%active) RETURN + model%tors_c_valid = .FALSE. + IF (.NOT. model%tw_active) RETURN + CALL tw_set_derived(model, model%torsion) + IF (.NOT. (ALLOCATED(model%torsion%bt_zeta) .AND. ALLOCATED(model%torsion%bt))) RETURN + DO e = 1, model%ne + IF (model%torsion%bt_zeta(e) > CD_ZERO) & + model%torsion%bt(e) = CD_HermiteTorsion_Zeta_Damping(model%torsion%bt_zeta(e), model%l0(e), & + model%torsion%gj(e), model%torsion%irn(e)) + END DO + END SUBROUTINE torsion_length_terms + SUBROUTINE enter_committed_lengths(model, aside, ErrStat, ErrMsg) !! Install the lengths and rates the committed state was reached with (l0_c, l0_dot_c) for !! one evaluation of the committed state, setting the present ones aside: after a length !! change the length-dependent caches are rebuilt from l0_c, and leave_committed_lengths - !! moves the present ones back bit for bit. A model that is not under active line control, + !! moves the present ones back bit for bit (the torsion terms, rebuilt from them). A model + !! that is not under active line control, !! or whose lengths and rates are the committed ones, is left as it is. On failure nothing !! is written. TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: model @@ -2037,6 +2070,8 @@ SUBROUTINE leave_committed_lengths(model, aside) CALL MOVE_ALLOC(aside%cn, model%contact_cn) IF (model%fr_active) CALL MOVE_ALLOC(aside%frk, model%fr_k) END IF + ! the torsion terms of the present lengths, rebuilt from them as they were built + CALL torsion_length_terms(model) END IF IF (aside%rates) model%l0_dot = aside%rate aside%lengths = .FALSE. @@ -5170,7 +5205,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Step_Recovering(model, dt, max_iter, tol, ErrStat REAL(wp) :: tensile_force_save, tensile_threshold_save, tensile_xi_save, tensile_time_save ! The step-rotation diagnostic must not keep the turn of a step that is rewound. REAL(wp) :: rotation_save - REAL(wp) :: tors_theta0, tors_phi0, tors_phi1, tors_ends0(3, 4), tors_ends1(3, 4), tors_sub(3, 4) + REAL(wp) :: tors_theta0, tors_phi0, tors_phi1, tors_ends0(3, 4), tors_ends1(3, 4), tors_sub(3, 4), tors_torque0 CHARACTER(1024) :: em ! Tensile-qualification failure flag reported by each step (classified by flag, not by ! message text, so a short caller buffer cannot change the recovery decision). @@ -5271,6 +5306,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Step_Recovering(model, dt, max_iter, tol, ErrStat tors_theta0 = model%torsion%theta tors_phi0 = model%torsion%phi tors_ends0 = model%torsion%ends + tors_torque0 = model%torsion%torque IF (model%tw_active) CALL tw_pack(model, model%ws_recovery_tw) tors_phi1 = tors_phi0 tors_ends1 = tors_ends0 @@ -5511,13 +5547,13 @@ SUBROUTINE CD_HermiteCable_Dyn_Step_Recovering(model, dt, max_iter, tol, ErrStat CONTAINS SUBROUTINE restore_torsion() - !! Interval-start torsion state (frames, Phi, Theta) after a rewind; no pending drive. + !! Interval-start torsion state (frames, Phi, Theta, torque) after a rewind; no pending drive. IF (.NOT. model%torsion%active) RETURN model%torsion%theta = tors_theta0 model%torsion%phi = tors_phi0 model%torsion%ends = tors_ends0 IF (model%tw_active) CALL tw_unpack(model, model%ws_recovery_tw) - model%torsion%torque = (tors_phi0 - tors_theta0)/CD_HermiteTorsion_Compliance(model%torsion, model%l0) + model%torsion%torque = tors_torque0 model%tors_drive_set = .FALSE. END SUBROUTINE restore_torsion END SUBROUTINE CD_HermiteCable_Dyn_Step_Recovering @@ -7444,6 +7480,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_Torsion(model, torsion, ErrStat, ErrMsg) TYPE(CD_HermiteTorsionType) :: saved REAL(wp) :: th, mt REAL(wp) :: saved_step_ends(3, 4), saved_step_phi, saved_snap_theta, saved_snap_phi, saved_snap_ends(3, 4) + REAL(wp) :: saved_snap_torque REAL(wp) :: saved_drive_ends(3, 4), saved_drive_phi LOGICAL :: saved_snap_valid, saved_drive_set, saved_tw_active REAL(wp), ALLOCATABLE :: saved_tw(:) @@ -7539,6 +7576,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_Torsion(model, torsion, ErrStat, ErrMsg) saved_snap_theta = model%snap_torsion_theta saved_snap_phi = model%snap_torsion_phi saved_snap_ends = model%snap_torsion_ends + saved_snap_torque = model%snap_torsion_torque saved_snap_valid = model%snap_valid model%tors_use_step = .FALSE. model%tors_drive_set = .FALSE. @@ -7547,6 +7585,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_Torsion(model, torsion, ErrStat, ErrMsg) model%snap_torsion_theta = model%torsion%theta model%snap_torsion_phi = model%torsion%phi model%snap_torsion_ends = model%torsion%ends + model%snap_torsion_torque = model%torsion%torque ! the snapshot predates the new load set (as for CD_HermiteCable_Dyn_Set_EndConnection) model%snap_valid = .FALSE. model%fc_valid = .FALSE. @@ -7565,6 +7604,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_Torsion(model, torsion, ErrStat, ErrMsg) model%snap_torsion_theta = saved_snap_theta model%snap_torsion_phi = saved_snap_phi model%snap_torsion_ends = saved_snap_ends + model%snap_torsion_torque = saved_snap_torque model%snap_valid = saved_snap_valid ErrStat = es ErrMsg = 'CD_HermiteCable_Dyn_Set_Torsion: '//TRIM(em) @@ -7762,6 +7802,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Snapshot(model, ErrStat, ErrMsg) model%snap_torsion_theta = model%torsion%theta model%snap_torsion_phi = model%torsion%phi model%snap_torsion_ends = model%torsion%ends + model%snap_torsion_torque = model%torsion%torque IF (model%tw_active) THEN IF (.NOT. ALLOCATED(model%snap_tw)) ALLOCATE (model%snap_tw(tw_pack_size(model)), model%snap_tw_fcR(model%nn)) CALL tw_pack(model, model%snap_tw) @@ -7844,8 +7885,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Restore(model, ErrStat, ErrMsg) model%torsion%theta = model%snap_torsion_theta model%torsion%phi = model%snap_torsion_phi model%torsion%ends = model%snap_torsion_ends - IF (model%torsion%active) model%torsion%torque = (model%torsion%phi - model%torsion%theta)/ & - CD_HermiteTorsion_Compliance(model%torsion, model%l0) + IF (model%torsion%active) model%torsion%torque = model%snap_torsion_torque model%tors_drive_set = .FALSE. model%tors_use_step = .FALSE. IF (model%tw_active) CALL tw_unpack(model, model%snap_tw) @@ -7992,6 +8032,7 @@ SUBROUTINE CD_HermiteCable_Dyn_End(model) model%snap_torsion_theta = CD_ZERO model%snap_torsion_phi = CD_ZERO model%snap_torsion_ends = CD_ZERO + model%snap_torsion_torque = CD_ZERO CALL tw_release(model) model%tw_rigid = .FALSE. model%tw_psi = CD_ZERO @@ -8954,6 +8995,17 @@ SUBROUTINE assemble_twist(model, q_cfg, v_cfg, want_residual, want_tangent, R, K !! g (H q_dot)^T) and Kvb (Bt/l0) g g^T, and the coupling to the angles is kept per element !! for the solve (tw_eg, tw_ehv, tw_ek, tw_ed, tw_lg, tw_lk; want_tangent). tw_me holds the !! element torques and tw_tsum the summed twist. + !! + !! An element whose length changes at the rate l0_dot (active line control) damps the rate of + !! its twist per length, the quantity tau/l0 its elastic torque GJ tau/l0 reads, as the axial + !! damping takes the rate of the strain: M_e = (GJ/l0) tau + (Bt/l0) (d tau/dt - tau l0_dot/l0), + !! so a segment paid out at a constant twist per length carries no damping torque. At fixed q, + !! tau changes with l0 through the coupling term -(K/GJ) l0 and through the element's shape: + !! rho_e depends on the tangent handles m only through l0 m (the Hermite r' and r'') and m/|m|, + !! so l0 drho/dl0 = m_1 . drho/dm_1 + m_2 . drho/dm_2 - (K/GJ) l0 (an Euler identity of the + !! gradient g), and d tau/dt gains (l0_dot/l0)(m . g_m - (K/GJ) l0). The angle stiffness of the + !! element becomes GJ/l0 - (Bt/l0) l0_dot/l0 and its q-gradient gains (Bt/l0)(l0_dot/l0) + !! (g_m + H m), H the Hessian of rho_e. TYPE(CD_HermiteCableDynType), INTENT(INOUT), TARGET :: model REAL(wp), INTENT(IN) :: q_cfg(:), v_cfg(:) LOGICAL, INTENT(IN) :: want_residual, want_tangent @@ -8965,6 +9017,10 @@ SUBROUTINE assemble_twist(model, q_cfg, v_cfg, want_residual, want_tangent, R, K REAL(wp) :: om(3, 2), ew(3, 2) LOGICAL :: turning REAL(wp) :: tau, rate, mt, psi, gl(3), hl(3, 3), k, tw + ! length-rate share of the damping (active line control): l0_dot/l0, the element's tangent + ! handles (m in the 12-DOF layout, the r slots zero) and the angle stiffness it leaves + REAL(wp) :: rr, mv(12), gmv(12), kel_t, cpl + LOGICAL :: ctrl_rate INTEGER :: e, iend, node, b, i, j, es CHARACTER(1024) :: em @@ -9004,6 +9060,20 @@ SUBROUTINE assemble_twist(model, q_cfg, v_cfg, want_residual, want_tangent, R, K tau = phi(e + 1) - phi(e) + rho rate = w(e + 1) - w(e) + DOT_PRODUCT(g, ve) IF (turning .AND. kd > CD_ZERO) rate = rate + DOT_PRODUCT(ew(:, 1), om(:, 1)) + DOT_PRODUCT(ew(:, 2), om(:, 2)) + kel_t = kel + rr = CD_ZERO + IF (model%has_ctrl .AND. kd > CD_ZERO) rr = model%l0_dot(e)/model%l0(e) + ctrl_rate = ABS(rr) > CD_ZERO + mv = CD_ZERO + IF (ctrl_rate) THEN + ! the rate of the twist per length (see the header): (l0_dot/l0)(m . g_m - (K/GJ) l0 - tau) + mv(4:6) = q_cfg(6*e - 2:6*e) + mv(10:12) = q_cfg(6*e + 4:6*e + 6) + cpl = CD_ZERO + IF (ALLOCATED(model%torsion%couple)) cpl = model%torsion%couple(e) + rate = rate + rr*(DOT_PRODUCT(g, mv) - cpl*model%l0(e) - tau) + kel_t = kel - kd*rr + END IF mt = kel*tau + kd*rate model%tw_me(e) = mt model%tw_tsum = model%tw_tsum + tau @@ -9015,9 +9085,16 @@ SUBROUTINE assemble_twist(model, q_cfg, v_cfg, want_residual, want_tangent, R, K IF (want_tangent) THEN hv = CD_ZERO IF (kd > CD_ZERO) hv = MATMUL(h, ve) + ! the length-rate share: d(m . g_m)/dq = g_m + H m (H symmetric), and -tau rr in kel_t + IF (ctrl_rate) THEN + gmv = CD_ZERO + gmv(4:6) = g(4:6) + gmv(10:12) = g(10:12) + hv = MATMUL(h, ve + rr*mv) + rr*gmv + END IF DO j = 1, 12 DO i = 1, 12 - ke(i, j) = mt*h(i, j) + kel*g(i)*g(j) + kd*g(i)*hv(j) + ke(i, j) = mt*h(i, j) + kel_t*g(i)*g(j) + kd*g(i)*hv(j) END DO END DO CALL scatter12_band(Kb, ke, e) @@ -9031,7 +9108,7 @@ SUBROUTINE assemble_twist(model, q_cfg, v_cfg, want_residual, want_tangent, R, K END IF model%tw_eg(:, e) = g model%tw_ehv(:, e) = hv - model%tw_ek(e) = kel + model%tw_ek(e) = kel_t model%tw_ed(e) = kd END IF END DO diff --git a/src/CableDyn_HermiteTorsion.f90 b/src/CableDyn_HermiteTorsion.f90 index 75743309..d93094f6 100644 --- a/src/CableDyn_HermiteTorsion.f90 +++ b/src/CableDyn_HermiteTorsion.f90 @@ -49,6 +49,7 @@ MODULE CableDyn_HermiteTorsion PUBLIC :: CD_HermiteTorsionType PUBLIC :: CD_HermiteTorsion_Compliance PUBLIC :: CD_HermiteTorsion_Validate + PUBLIC :: CD_HermiteTorsion_Zeta_Damping PUBLIC :: CD_HermiteTorsion_Bordered_Solve PUBLIC :: CD_HermiteTorsion_Inertia PUBLIC :: CD_HermiteTorsion_Lowest_Mode @@ -120,6 +121,11 @@ MODULE CableDyn_HermiteTorsion !! (torque Bt d tau/dt). With irn unallocated the dynamics keeps the condensed, quasi-static !! torsion; the statics never read them. REAL(wp), ALLOCATABLE :: irn(:), bt(:) + !! The fraction zeta of an element's critical torsional damping l0 sqrt(GJ Irn) that a + !! negative deck Bt (-zeta) asked for, 0 on an element with a direct Bt; unallocated: every + !! Bt is direct. bt holds the resolved value zeta l0 sqrt(GJ Irn) (CD_HermiteTorsion_Zeta_Damping), + !! which active line control re-resolves when it changes l0, so the element keeps its zeta. + REAL(wp), ALLOCATABLE :: bt_zeta(:) INTEGER :: quadrature_order = 4 !! State: the accepted Theta (unwrapped) once has_theta; before that theta_hint selects the !! 2 pi branch of the first evaluation (0 for an untwisted start). @@ -173,6 +179,14 @@ PURE REAL(wp) FUNCTION CD_HermiteTorsion_Compliance(tors, l0) RESULT(c) c = tors%end_compliance(1) + tors%end_compliance(2) + SUM(l0/tors%gj) END FUNCTION CD_HermiteTorsion_Compliance + ELEMENTAL REAL(wp) FUNCTION CD_HermiteTorsion_Zeta_Damping(zeta, l0, gj, irn) RESULT(bt) + !! The torsional damping Bt [N m^2 s] of an element of length l0 that a deck Bt of -zeta asks + !! for: zeta times the element's critical torsional damping l0 sqrt(GJ Irn) (the convention + !! of the axial BA, with GJ for EA and the polar inertia Irn for the mass per length). + REAL(wp), INTENT(IN) :: zeta, l0, gj, irn + bt = zeta*l0*SQRT(gj*irn) + END FUNCTION CD_HermiteTorsion_Zeta_Damping + PURE SUBROUTINE CD_HermiteTorsion_Validate(tors, l0, ErrStat, ErrMsg) !! Fail-closed check of an active torsion description against a mesh of SIZE(l0) elements. TYPE(CD_HermiteTorsionType), INTENT(IN) :: tors @@ -245,6 +259,25 @@ PURE SUBROUTINE CD_HermiteTorsion_Validate(tors, l0, ErrStat, ErrMsg) RETURN END IF END IF + IF (ALLOCATED(tors%bt_zeta)) THEN + IF (.NOT. ALLOCATED(tors%bt)) THEN + ErrMsg = 'torsion: a torsional damping ratio needs the torsional damping it resolves' + RETURN + END IF + IF (SIZE(tors%bt_zeta) /= SIZE(l0)) THEN + ErrMsg = 'torsion: the torsional damping ratio must have one entry per element' + RETURN + END IF + IF (.NOT. CD_All_Finite(tors%bt_zeta)) THEN + ErrStat = CD_HTORS_NONFINITE + ErrMsg = 'torsion: non-finite torsional damping ratio' + RETURN + END IF + IF (ANY(tors%bt_zeta < CD_ZERO)) THEN + ErrMsg = 'torsion: the torsional damping ratio must be non-negative' + RETURN + END IF + END IF IF (ANY(tors%end_compliance < CD_ZERO)) THEN ErrMsg = 'torsion: end compliances must be non-negative' RETURN diff --git a/tests/test_control_torsion.f90 b/tests/test_control_torsion.f90 new file mode 100644 index 00000000..864e3f26 --- /dev/null +++ b/tests/test_control_torsion.f90 @@ -0,0 +1,898 @@ +! File: tests/test_control_torsion.f90 +! SPDX-License-Identifier: Apache-2.0 +! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +PROGRAM test_control_torsion + !! Active line control (CD_HermiteCable_Dyn_Set_SegmentLength, deck CONTROL) of a finite-EI line + !! restrained in torsion. Unless named otherwise the line is straight along +x, 10 elements of + !! 1 m unstretched held between rigid torsional ends H = 10.1 m apart (1 % strain), with the + !! imposed twist Phi; its fairlead-side span (the last two elements, S = 2 m) is controlled. + !! Q quasi-static: the span paid out and hauled in, DeltaL = 0.05 sin(2 pi t/10 s), carries the + !! torque GJ Phi/L(t) + K (H - L)/L and the tension EA (H - L)/L + K Phi/L (L = 10 m + DeltaL, + !! with the axial damping's BA d(eps)/dt): + !! condensed torsion without and with torque-tension coupling K, and the nodal twist with a + !! negligible Irn (1e-9) and K (every node torque); + !! D torsional damping with the length rate: a constant pay-out Ldot of the span under GJ|K|Bt + !! (Irn 1e-9) keeps the twist per length uniform, so the torque is the Kelvin-Voigt + !! GJ chi + Bt chi_dot with chi = (Phi + (K/GJ) H)/L - K/GJ; without the rate it is not; + !! F the length-rate share of the torsional damping on a bowed line equals Bt l0_dot + !! d(tau/l0)/dl0 by central differences of the element twist at fixed q (the Euler identity + !! l0 drho/dl0 = m . drho/dm of the element shape); + !! Z the torsion terms a length change rebuilds equal those of a model built with the new + !! lengths bit for bit (the lumped polar inertia Irn l0/2, a -zeta torsional damping + !! re-resolved as zeta l0 sqrt(GJ Irn), a direct Bt kept); a committed-state evaluation + !! between the command and the step takes the committed lengths and leaves the present ones, + !! and a saved control state and a snapshot take a command back bit for bit; + !! E energy with a real Irn: with the centreline held, a span paid out under a ringing twist + !! changes the twist and polar kinetic energy by the work of the length change, + !! integral of sum (dE/dl0) l0_dot + 1/2 I_dot w^2 (the mass of the new lengths, without the + !! rate term, as for the translational mass); + !! L a slow pay-out under a twist with a real Irn: the torque follows GJ Phi/L(t), the run at + !! rho_inf = 0.4 (alpha_f = 2/7) follows the one at rho_inf = 0 within a few per cent of the + !! per-step torque change, also with the committed force evaluated afresh each step rather + !! than reused (it keeps its torsion at the committed lengths; taking it at the new ones + !! lags by alpha_f of it), and no step jumps; + !! R restart mid-ramp: a rolling, twisting, torsionally damped coupled cable under a pay-out + !! ramp continues bit-identically from a snapshot and from a module rebuilt from the + !! checkpoint mirror with the command re-applied; + !! S deck: a straight torsion line with a pretwist and a CONTROL row on the coupled aggregate + !! (the CompMooring = 5 route; the standalone driver takes no CONTROL) initialises, its + !! Torq1N1 follows GJ Twist1/L(t) through a haul-in ramp, and the shell's checkpoint recipe + !! continues bit-identically. + USE CableDyn_Precision, ONLY: wp + USE CableDyn_EndConnection, ONLY: CD_ENDCONN_RIGID + USE CableDyn_HermiteTorsion, ONLY: CD_HermiteTorsionType, CD_HermiteTorsion_Line, CD_HermiteTorsion_Unwrap, & + CD_HermiteTorsion_Zeta_Damping, CD_HTORS_OK + USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCableDynType, CD_HermiteCable_Dyn_Init, & + CD_HermiteCable_Dyn_Step, CD_HermiteCable_Dyn_Reaction, & + CD_HermiteCable_Dyn_Set_SegmentLength, & + CD_HermiteCable_Dyn_Set_Axial_Damping, & + CD_HermiteCable_Dyn_Set_Torsion, CD_HermiteCable_Dyn_Set_Torsion_Drive, & + CD_HermiteCable_Dyn_Torsion_State, CD_HermiteCable_Dyn_Node_Torque, & + CD_HermiteCable_Dyn_Element_Twist, CD_HermiteCable_Dyn_Element_Torque, & + CD_HermiteCable_Dyn_Recompute_Acceleration, CD_HermiteCable_Dyn_Snapshot, & + CD_HermiteCable_Dyn_Restore, CD_HermiteCableControlSaveType, & + CD_HermiteCable_Dyn_Save_Control, CD_HermiteCable_Dyn_Restore_Control, & + CD_HermiteCable_Dyn_Set_ForceBlend, CD_HermiteCable_Dyn_End, CD_HCDYN_OK + USE CableDyn_OpenFAST_HermiteFMF, ONLY: CD_HFMF_ModuleType, CD_HFMF_Init, CD_HFMF_Set_EndConnection, & + CD_HFMF_Set_Torsion, CD_HFMF_UpdateStates, CD_HFMF_Set_SegmentLength, & + CD_HFMF_Snapshot, CD_HFMF_Restore, CD_HFMF_MirrorSize, & + CD_HFMF_PackMirror, CD_HFMF_UnpackMirror, CD_HFMF_End, CD_HFMF_OK + USE CableDyn_OpenFAST_Aggregate, ONLY: CD_AGG_ModuleType, CD_AGG_Init_From_Deck, CD_AGG_GetMovingPointMesh, & + CD_AGG_UpdateStates_Moving, CD_AGG_Step_Moving, CD_AGG_CalcOutput, & + CD_AGG_Apply_LineControl, CD_AGG_EvalChannel, CD_AGG_End, CD_AGG_OK + USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY: INT64 + IMPLICIT NONE + + REAL(wp), PARAMETER :: PI = 3.14159265358979323846_wp + ! the straight line of Q, D, Z, E, L + INTEGER, PARAMETER :: NE = 10, NN = NE + 1, NDOF = 6*NN + REAL(wp), PARAMETER :: LS = 10.0_wp, HH = 10.1_wp, EA = 1.0e5_wp, EI = 100.0_wp, GJ = 80.0_wp + REAL(wp), PARAMETER :: PHI0 = 0.5_wp*PI, KTT = 500.0_wp + INTEGER, PARAMETER :: SPAN(2) = [NE - 1, NE] + INTEGER :: nfail = 0 + + CALL check_quasi_static('condensed', 0.0_wp, 0.0_wp) + CALL check_quasi_static('condensed, coupled', KTT, 0.0_wp) + CALL check_quasi_static('nodal twist, coupled', KTT, 1.0e-9_wp) + CALL check_damping_rate() + CALL check_rate_identity() + CALL check_rebuild() + CALL check_energy() + CALL check_lag() + CALL check_restart() + CALL check_deck() + + IF (nfail > 0) THEN + WRITE (*, '(A,I0,A)') 'FAIL: ', nfail, ' assertion(s) failed' + ERROR STOP 1 + END IF + WRITE (*, '(A)') 'PASS: active line control of lines restrained in torsion' + +CONTAINS + + SUBROUTINE require(cond, label) + LOGICAL, INTENT(IN) :: cond + CHARACTER(*), INTENT(IN) :: label + IF (cond) RETURN + nfail = nfail + 1 + WRITE (*, '(A)') 'FAIL: '//TRIM(label) + END SUBROUTINE require + + LOGICAL FUNCTION same_bits(x, y) RESULT(same) + REAL(wp), INTENT(IN) :: x(:), y(:) + same = SIZE(x) == SIZE(y) + IF (same) same = ALL(TRANSFER(x, 0_INT64, SIZE(x)) == TRANSFER(y, 0_INT64, SIZE(y))) + END FUNCTION same_bits + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE build_line(m, l0, rho_inf, rhoa, ktt_in, irn, ba, hold_all, es, em, bt, zeta, phi) + !! The straight line: nodes at x = s H/L with m = (H/L, 0, 0) (uniform strain, at rest in + !! equilibrium without weight), every transverse DOF held (an axial and torsional problem), + !! the end translations held (hold_all: every DOF, the twist alone moves). The kernel takes + !! EA - K^2/GJ, as the deck gives it under coupling. Torsion: both ends along +x with the + !! reference normal +z, rigid, imposed twist phi (default Phi0), GJ, coupling ktt_in, the + !! polar inertia irn (> 0: nodal twist), a direct Bt (bt) or a -zeta damping (zeta, resolved + !! as the deck does). ba > 0 adds axial damping. + TYPE(CD_HermiteCableDynType), INTENT(OUT) :: m + REAL(wp), INTENT(IN) :: l0(NE), rho_inf, rhoa, ktt_in, irn, ba + LOGICAL, INTENT(IN) :: hold_all + INTEGER, INTENT(OUT) :: es + CHARACTER(*), INTENT(OUT) :: em + REAL(wp), INTENT(IN), OPTIONAL :: bt(NE), zeta(NE), phi + TYPE(CD_HermiteTorsionType) :: tors + REAL(wp) :: q(NDOF), s, g(NDOF), raw, lt + INTEGER, ALLOCATABLE :: fixed(:) + INTEGER :: i, k + lt = SUM(l0) + q = 0.0_wp + fixed = [INTEGER ::] + DO i = 1, NN + s = SUM(l0(1:i - 1)) + q(6*i - 5) = s*HH/lt + q(6*i - 2) = HH/lt + fixed = [fixed, 6*i - 4, 6*i - 3, 6*i - 1, 6*i] + IF (hold_all .OR. i == 1 .OR. i == NN) fixed = [fixed, 6*i - 5] + IF (hold_all) fixed = [fixed, 6*i - 2] + END DO + CALL CD_HermiteCable_Dyn_Init(m, l0, [(EA - ktt_in**2/GJ, k=1, NE)], [(EI, k=1, NE)], [(rhoa, k=1, NE)], & + [(0.0_wp, k=1, NE)], q, fixed, -1.0e3_wp, 0.0_wp, rho_inf, es, em) + IF (es /= CD_HCDYN_OK) RETURN + IF (ba > 0.0_wp) THEN + CALL CD_HermiteCable_Dyn_Set_Axial_Damping(m, [(ba, k=1, NE)], es, em) + IF (es /= CD_HCDYN_OK) RETURN + END IF + tors%active = .TRUE. + tors%phi = PHI0 + IF (PRESENT(phi)) tors%phi = phi + tors%ends = RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 1.0_wp, 0.0_wp, 0.0_wp, & + 0.0_wp, 0.0_wp, 1.0_wp], [3, 4]) + tors%end_compliance = 0.0_wp + ALLOCATE (tors%gj(NE)) + tors%gj = GJ + IF (ktt_in > 0.0_wp) tors%couple = [(ktt_in/GJ, k=1, NE)] + IF (irn > 0.0_wp) tors%irn = [(irn, k=1, NE)] + IF (PRESENT(bt)) tors%bt = bt + IF (PRESENT(zeta)) THEN + IF (.NOT. ALLOCATED(tors%bt)) tors%bt = [(0.0_wp, k=1, NE)] + tors%bt_zeta = zeta + DO k = 1, NE + IF (zeta(k) > 0.0_wp) tors%bt(k) = CD_HermiteTorsion_Zeta_Damping(zeta(k), l0(k), GJ, irn) + END DO + END IF + CALL CD_HermiteTorsion_Line(q, l0, tors%ends, raw, g, es, em, couple=tors%couple) + IF (es /= CD_HTORS_OK) RETURN + tors%theta = CD_HermiteTorsion_Unwrap(raw, 0.0_wp) + tors%has_theta = .TRUE. + CALL CD_HermiteCable_Dyn_Set_Torsion(m, tors, es, em) + END SUBROUTINE build_line + + SUBROUTINE command(m, dl, dldot, es, em, restored) + !! The span from its base S = 2 m to S + dl, each element scaled by (S + dl)/S, rate dldot l/S. + TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: m + REAL(wp), INTENT(IN) :: dl, dldot + INTEGER, INTENT(OUT) :: es + CHARACTER(*), INTENT(OUT) :: em + LOGICAL, INTENT(IN), OPTIONAL :: restored + REAL(wp), PARAMETER :: S = 2.0_wp + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, SPAN, [1.0_wp, 1.0_wp]*((S + dl)/S), [1.0_wp, 1.0_wp]*(dldot/S), & + es, em, restored=restored) + END SUBROUTINE command + + REAL(wp) FUNCTION end_tension(m) RESULT(t) + !! Axial pull of the line on its held fairlead node (the last node). + TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: m + REAL(wp) :: f(3) + INTEGER :: es + CHARACTER(200) :: em + CALL CD_HermiteCable_Dyn_Reaction(m, NN, f, es, em) + t = -f(1) + IF (es /= CD_HCDYN_OK) t = HUGE(1.0_wp) + END FUNCTION end_tension + + REAL(wp) FUNCTION line_torque(m) RESULT(tq) + !! The torque of the line: the condensed torque, or the node torque of the nodal twist furthest + !! from the mean (so a non-uniform torque shows). + TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: m + REAL(wp) :: th, ntq(NN) + INTEGER :: es + CHARACTER(300) :: em + IF (m%tw_active) THEN + CALL CD_HermiteCable_Dyn_Node_Torque(m, ntq, es, em) + tq = ntq(MAXLOC(ABS(ntq - SUM(ntq)/REAL(NN, wp)), 1)) + ELSE + CALL CD_HermiteCable_Dyn_Torsion_State(m, th, tq, es, em) + END IF + IF (es /= CD_HCDYN_OK) tq = HUGE(1.0_wp) + END FUNCTION line_torque + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_quasi_static(label, kc, irn) + !! Q: rho_inf = 0, a light line (0.01 kg/m) with axial damping, 1000 steps of 0.01 s. + CHARACTER(*), INTENT(IN) :: label + REAL(wp), INTENT(IN) :: kc, irn + REAL(wp), PARAMETER :: DT = 0.01_wp, AMP = 0.05_wp, PER = 10.0_wp, BA = 100.0_wp + TYPE(CD_HermiteCableDynType) :: m + REAL(wp) :: l0(NE), t, dl, dldot, lt, mexp, texp, err_m, err_t, frozen + INTEGER :: k, es + CHARACTER(300) :: em + l0 = 1.0_wp + CALL build_line(m, l0, 0.0_wp, 0.01_wp, kc, irn, BA, .FALSE., es, em) + CALL require(es == CD_HCDYN_OK, 'Q '//label//': build: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + CALL require(m%tw_active .EQV. irn > 0.0_wp, 'Q '//label//': the twist model') + err_m = 0.0_wp + err_t = 0.0_wp + frozen = 0.0_wp + DO k = 1, NINT(PER/DT) + t = REAL(k, wp)*DT + dl = AMP*(SIN(2.0_wp*PI*t/PER) - 0.5_wp*SIN(4.0_wp*PI*t/PER)) + dldot = AMP*(2.0_wp*PI/PER)*(COS(2.0_wp*PI*t/PER) - COS(4.0_wp*PI*t/PER)) + CALL command(m, dl, dldot, es, em) + CALL require(es == CD_HCDYN_OK, 'Q '//label//': command: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) EXIT + CALL CD_HermiteCable_Dyn_Step(m, DT, 50, 1.0e-10_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'Q '//label//': step: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) EXIT + lt = LS + dl + mexp = GJ*PHI0/lt + kc*(HH - lt)/lt + ! the axial Kelvin-Voigt share BA d(eps)/dt of the uniform strain eps = H/L - 1 + texp = EA*(HH - lt)/lt - BA*HH*dldot/lt**2 + kc*PHI0/lt + err_m = MAX(err_m, ABS(line_torque(m) - mexp)/mexp) + err_t = MAX(err_t, ABS(end_tension(m) - texp)/texp) + frozen = MAX(frozen, ABS(GJ*PHI0/LS + kc*(HH - LS)/LS - mexp)/mexp) + END DO + WRITE (*, '(A,A,A,3ES10.2)') 'Q quasi-static (', label, '): torque, tension rel. error; a frozen '// & + 'compliance would miss by ', err_m, err_t, frozen + CALL require(err_m <= 1.0e-7_wp, 'Q '//label//': the torque is GJ Phi/L(t) + K (H - L)/L') + CALL require(err_t <= 1.0e-5_wp, 'Q '//label//': the tension is EA (H - L)/L + K Phi/L') + CALL CD_HermiteCable_Dyn_End(m) + END SUBROUTINE check_quasi_static + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_damping_rate() + !! D: the span paid out at Ldot = 0.01 m/s from t = 0 over 4 s, Bt = 100 N m2 s, K as in Q. + !! Every element obeys GJ chi_e + Bt chi_e_dot = M with one M (the angles carry no inertia) and + !! starts from one chi, so chi stays uniform, and the end constraint gives sum chi_e l_e = + !! Phi + (K/GJ)(H - L): M = GJ chi + Bt chi_dot, chi_dot = -(Phi + (K/GJ) H) Ldot/L^2. + REAL(wp), PARAMETER :: DT = 0.01_wp, LDOT = 0.01_wp, TEND = 4.0_wp, BT = 100.0_wp + TYPE(CD_HermiteCableDynType) :: m + REAL(wp) :: l0(NE), t, lt, chi, chid, mexp, err(2), lag, c + INTEGER :: k, es, pass + CHARACTER(300) :: em + c = KTT/GJ + l0 = 1.0_wp + lag = BT*(PHI0 + c*HH)*LDOT/(LS + LDOT*TEND)**2 + DO pass = 1, 2 + CALL build_line(m, l0, 0.0_wp, 0.01_wp, KTT, 1.0e-9_wp, 100.0_wp, .FALSE., es, em, bt=[(BT, k=1, NE)]) + CALL require(es == CD_HCDYN_OK, 'D: build: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + err(pass) = 0.0_wp + DO k = 1, NINT(TEND/DT) + t = REAL(k, wp)*DT + CALL command(m, LDOT*t, MERGE(LDOT, 0.0_wp, pass == 1), es, em) + IF (es == CD_HCDYN_OK) CALL CD_HermiteCable_Dyn_Step(m, DT, 50, 1.0e-10_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'D: march: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) EXIT + IF (t < 1.0_wp) CYCLE + lt = LS + LDOT*t + chi = (PHI0 + c*HH)/lt - c + chid = -(PHI0 + c*HH)*LDOT/lt**2 + mexp = GJ*chi + BT*chid + err(pass) = MAX(err(pass), ABS(line_torque(m) - mexp)) + END DO + CALL CD_HermiteCable_Dyn_End(m) + END DO + WRITE (*, '(A,ES10.3,A,ES10.3,A,ES10.3,A)') 'D torsional damping lag ', lag, ' N m; max torque error with '// & + 'the length rate ', err(1), ', without ', err(2), ' N m' + CALL require(err(1) <= 1.0e-2_wp*lag, 'D: the torque is GJ chi + Bt chi_dot (the twist per length damped)') + CALL require(err(2) > 0.2_wp*lag, 'D: without the length rate the damping torque is wrong') + END SUBROUTINE check_damping_rate + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_rate_identity() + !! F: a bowed line at rest (transverse DOFs free, nodal twist, Bt = 30 N m2 s, no coupling), + !! elements 5 and 6 at the rate l0_dot = 0.02 m/s: the change of their committed torque is + !! Bt l0_dot d(tau/l0)/dl0 at fixed q, against central differences of the element twist over + !! l0 (+- 1e-5 m), and against the straight-line value -Bt l0_dot tau/l0^2 that leaves out + !! the shape's dependence on l0. + REAL(wp), PARAMETER :: BT = 30.0_wp, RATE = 0.02_wp, DELTA = 1.0e-5_wp + INTEGER, PARAMETER :: EL(2) = [5, 6] + TYPE(CD_HermiteCableDynType) :: m + TYPE(CD_HermiteTorsionType) :: tors + REAL(wp) :: l0(NE), q(NDOF), s, g(NDOF), raw, tw0(NE), twp(NE), twm(NE), mt0(NE), mt1(NE) + REAL(wp) :: fd(2), share(2), shape(2), err + INTEGER :: i, k, es + CHARACTER(300) :: em + l0 = 1.0_wp + q = 0.0_wp + DO i = 1, NN + s = REAL(i - 1, wp) + q(6*i - 5) = s + q(6*i - 4) = 0.8_wp*SIN(PI*s/LS)**2 + q(6*i - 3) = 0.4_wp*SIN(2.0_wp*PI*s/LS)**2 + q(6*i - 2) = 1.0_wp + q(6*i - 1) = 0.8_wp*(PI/LS)*SIN(2.0_wp*PI*s/LS) + q(6*i) = 0.4_wp*(2.0_wp*PI/LS)*SIN(4.0_wp*PI*s/LS) + END DO + CALL CD_HermiteCable_Dyn_Init(m, l0, [(EA, k=1, NE)], [(EI, k=1, NE)], [(1.0_wp, k=1, NE)], [(0.0_wp, k=1, NE)], & + q, [1, 2, 3, NDOF - 5, NDOF - 4, NDOF - 3], -1.0e3_wp, 0.0_wp, 0.0_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'F: init: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + tors%active = .TRUE. + tors%phi = 1.0_wp + tors%ends = RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 1.0_wp, 0.0_wp, 0.0_wp, & + 0.0_wp, 0.0_wp, 1.0_wp], [3, 4]) + tors%end_compliance = 0.0_wp + tors%gj = [(GJ, k=1, NE)] + tors%irn = [(0.05_wp, k=1, NE)] + tors%bt = [(BT, k=1, NE)] + CALL CD_HermiteTorsion_Line(q, l0, tors%ends, raw, g, es, em) + tors%theta = CD_HermiteTorsion_Unwrap(raw, 0.0_wp) + tors%has_theta = .TRUE. + CALL CD_HermiteCable_Dyn_Set_Torsion(m, tors, es, em) + CALL require(es == CD_HCDYN_OK .AND. m%tw_active, 'F: nodal twist on the bowed line: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + CALL CD_HermiteCable_Dyn_Element_Twist(m, tw0, es, em) + CALL CD_HermiteCable_Dyn_Element_Torque(m, mt0, es, em) + ! the element twist at l0 +- DELTA (the committed angles and q kept) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL) + DELTA, [0.0_wp, 0.0_wp], es, em) + CALL CD_HermiteCable_Dyn_Element_Twist(m, twp, es, em) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL) - DELTA, [0.0_wp, 0.0_wp], es, em) + CALL CD_HermiteCable_Dyn_Element_Twist(m, twm, es, em) + ! the rate at the base lengths, committed, and the torque of that committed state + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL), [RATE, RATE], es, em, restored=.TRUE.) + CALL require(es == CD_HCDYN_OK, 'F: the committed rate: '//TRIM(em)) + CALL CD_HermiteCable_Dyn_Recompute_Acceleration(m, es, em) + CALL require(es == CD_HCDYN_OK, 'F: the committed state with the rate: '//TRIM(em)) + CALL CD_HermiteCable_Dyn_Element_Torque(m, mt1, es, em) + err = 0.0_wp + DO k = 1, 2 + i = EL(k) + fd(k) = BT*RATE*(twp(i)/(l0(i) + DELTA) - twm(i)/(l0(i) - DELTA))/(2.0_wp*DELTA) + shape(k) = -BT*RATE*tw0(i)/l0(i)**2 + share(k) = mt1(i) - mt0(i) + err = MAX(err, ABS(share(k) - fd(k))/ABS(fd(k))) + END DO + WRITE (*, '(A,2ES13.5,A,2ES13.5,A,2ES13.5,A,ES9.2)') 'F length-rate damping torque ', share, & + '; by differences ', fd, '; straight-line value ', shape, '; rel. error ', err + CALL require(err <= 1.0e-6_wp, 'F: the length-rate damping is Bt l0_dot d(tau/l0)/dl0 at fixed q') + CALL require(MAXVAL(ABS(shape - fd)) > 1.0e3_wp*err*MAXVAL(ABS(fd)), & + 'F: the element shape''s dependence on l0 is resolved by the check') + CALL require(same_bits(mt1(1:4), mt0(1:4)) .AND. same_bits(mt1(7:NE), mt0(7:NE)), & + 'F: elements without a rate keep their torque') + CALL CD_HermiteCable_Dyn_End(m) + END SUBROUTINE check_rate_identity + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_rebuild() + !! Z: Irn 0.5 kg m, K, a -zeta damping (zeta 0.1) on every element but element 3, which takes + !! a direct Bt of 7 N m2 s; the span lengthened by 30 % at 0.05 m/s. + REAL(wp), PARAMETER :: LAM = 1.3_wp, IRN = 0.5_wp, ZETA = 0.1_wp, DT = 0.01_wp + TYPE(CD_HermiteCableDynType) :: a, b, ref, twin + TYPE(CD_HermiteCableControlSaveType) :: saved + REAL(wp) :: l0(NE), l0b(NE), zt(NE), btd(NE), bt_keep(NE), mass_keep(NN), torque_keep + INTEGER :: k, es + CHARACTER(300) :: em + l0 = 1.0_wp + zt = ZETA + zt(3) = 0.0_wp + btd = 0.0_wp + btd(3) = 7.0_wp + CALL build_line(a, l0, 0.0_wp, 0.01_wp, KTT, IRN, 100.0_wp, .FALSE., es, em, bt=btd, zeta=zt) + CALL require(es == CD_HCDYN_OK .AND. a%tw_active, 'Z: build: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + ref = a + CALL CD_HermiteCable_Dyn_Set_SegmentLength(a, SPAN, LAM*l0(SPAN), [0.05_wp, 0.05_wp], es, em) + CALL require(es == CD_HCDYN_OK .AND. a%has_ctrl, 'Z: a line restrained in torsion takes a length command: '// & + TRIM(em)) + l0b = l0 + l0b(SPAN) = LAM*l0(SPAN) + CALL build_line(b, l0b, 0.0_wp, 0.01_wp, KTT, IRN, 100.0_wp, .FALSE., es, em, bt=btd, zeta=zt) + CALL require(es == CD_HCDYN_OK, 'Z: fresh build at the new lengths: '//TRIM(em)) + CALL require(same_bits(a%tw_mass, b%tw_mass), 'Z: the lumped polar inertia equals a fresh build bit for bit') + CALL require(same_bits(a%torsion%bt, b%torsion%bt), 'Z: the torsional damping equals a fresh build bit for bit') + CALL require(ALL(a%torsion%bt(SPAN) == CD_HermiteTorsion_Zeta_Damping(ZETA, LAM, GJ, IRN)) .AND. & + ALL(a%torsion%bt(SPAN) > ref%torsion%bt(SPAN)), & + 'Z: a -zeta damping is re-resolved as zeta l0 sqrt(GJ Irn) at the new lengths') + CALL require(a%torsion%bt(3) == 7.0_wp .AND. same_bits(a%torsion%bt(1:NE - 2), ref%torsion%bt(1:NE - 2)), & + 'Z: a direct Bt and the elements outside the span keep their damping') + ! a committed-state evaluation between the command and the step takes the committed lengths + ! (the acceleration of a never-commanded twin) and leaves the present torsion terms + CALL CD_HermiteCable_Dyn_Recompute_Acceleration(ref, es, em) + CALL CD_HermiteCable_Dyn_Recompute_Acceleration(a, es, em) + CALL require(es == CD_HCDYN_OK .AND. same_bits(a%a, ref%a) .AND. same_bits(a%tw_al, ref%tw_al) .AND. & + same_bits(a%tw_mt, ref%tw_mt), 'Z: the committed state is evaluated at the committed lengths') + CALL require(same_bits(a%tw_mass, b%tw_mass) .AND. same_bits(a%torsion%bt, b%torsion%bt) .AND. & + same_bits(a%l0, l0b), 'Z: the committed-state evaluation leaves the present torsion terms') + ! a saved control state takes a command back + bt_keep = a%torsion%bt + mass_keep = a%tw_mass + CALL CD_HermiteCable_Dyn_Save_Control(a, saved) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(a, SPAN, 0.6_wp*l0(SPAN), [-0.2_wp, -0.2_wp], es, em) + CALL require(es == CD_HCDYN_OK .AND. .NOT. same_bits(a%tw_mass, mass_keep), 'Z: a command to take back') + CALL CD_HermiteCable_Dyn_Restore_Control(a, saved, es, em) + CALL require(es == CD_HCDYN_OK .AND. same_bits(a%tw_mass, mass_keep) .AND. same_bits(a%torsion%bt, bt_keep), & + 'Z: the saved control state takes the torsion terms back bit for bit') + ! snapshot, command, step, restore: lengths, torsion terms and committed torque come back + DO k = 1, 3 + CALL CD_HermiteCable_Dyn_Step(a, DT, 50, 1.0e-10_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'Z: step: '//TRIM(em)) + END DO + ! the snapshot falls between a command and its step: the committed torque belongs to the + ! committed lengths, not to the commanded ones + CALL CD_HermiteCable_Dyn_Set_SegmentLength(a, SPAN, 0.9_wp*l0(SPAN), [-0.1_wp, -0.1_wp], es, em) + twin = a + torque_keep = a%torsion%torque + CALL CD_HermiteCable_Dyn_Snapshot(a, es, em) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(a, SPAN, 0.8_wp*l0(SPAN), [-0.1_wp, -0.1_wp], es, em) + CALL CD_HermiteCable_Dyn_Step(a, DT, 50, 1.0e-10_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'Z: step after the command: '//TRIM(em)) + CALL CD_HermiteCable_Dyn_Restore(a, es, em) + CALL require(es == CD_HCDYN_OK .AND. same_bits(a%l0, twin%l0) .AND. same_bits(a%tw_mass, twin%tw_mass) .AND. & + same_bits(a%torsion%bt, twin%torsion%bt) .AND. same_bits(a%tw_phi, twin%tw_phi) .AND. & + same_bits([a%torsion%torque], [torque_keep]), & + 'Z: restore brings back the lengths, the torsion terms, the twist and the torque bit for bit') + CALL CD_HermiteCable_Dyn_End(a) + CALL CD_HermiteCable_Dyn_End(b) + CALL CD_HermiteCable_Dyn_End(ref) + CALL CD_HermiteCable_Dyn_End(twin) + END SUBROUTINE check_rebuild + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE energy_of(m, e) + !! Twist and polar kinetic energy of the held straight line, from the element twists and the + !! lengths (sum GJ tau^2/(2 l0) + 1/2 sum I w^2, I the lumped Irn l0/2 of the lengths). + TYPE(CD_HermiteCableDynType), INTENT(IN) :: m + REAL(wp), INTENT(OUT) :: e + REAL(wp), PARAMETER :: IRN = 0.5_wp + REAL(wp) :: tw(NE), inertia(NN) + INTEGER :: es, k + CHARACTER(300) :: em + CALL CD_HermiteCable_Dyn_Element_Twist(m, tw, es, em) + inertia = 0.0_wp + DO k = 1, NE + inertia(k) = inertia(k) + 0.5_wp*IRN*m%l0(k) + inertia(k + 1) = inertia(k + 1) + 0.5_wp*IRN*m%l0(k) + END DO + e = SUM(0.5_wp*GJ*tw**2/m%l0) + 0.5_wp*SUM(inertia*m%tw_w**2) + IF (es /= CD_HCDYN_OK) e = HUGE(1.0_wp) + END SUBROUTINE energy_of + + FUNCTION control_power(m) RESULT(p) + !! The work rate of the length change at the state of m: p(1) the elastic share, the sum over + !! the elements of dE/dl0 l0_dot = -GJ tau^2 l0_dot/(2 l0^2), and p(2) the inertial one, + !! 1/2 I_dot w^2 at the nodes. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: m + REAL(wp) :: p(2) + REAL(wp), PARAMETER :: IRN = 0.5_wp + REAL(wp) :: tw(NE), idot(NN) + INTEGER :: es, k + CHARACTER(300) :: em + p = 0.0_wp + IF (.NOT. m%has_ctrl) RETURN + CALL CD_HermiteCable_Dyn_Element_Twist(m, tw, es, em) + idot = 0.0_wp + DO k = 1, NE + idot(k) = idot(k) + 0.5_wp*IRN*m%l0_dot(k) + idot(k + 1) = idot(k + 1) + 0.5_wp*IRN*m%l0_dot(k) + END DO + p(1) = SUM(-0.5_wp*GJ*tw**2*m%l0_dot/m%l0**2) + p(2) = 0.5_wp*SUM(idot*m%tw_w**2) + IF (es /= CD_HCDYN_OK) p = HUGE(1.0_wp) + END FUNCTION control_power + + SUBROUTINE check_energy() + !! E: Irn 0.5 kg m, no damping, rho_inf = 1, every cable DOF held. Over the first 0.5 s the + !! imposed twist is driven from 1 to 1.3 rad (with zero rate at both ends), which then holds + !! and rings (the first mode at 4 rad/s); from t = 0.5 s the span is paid out by 0.5 m on a + !! smoothstep over 10 s, then held to 15 s. The energy change since the end of the drive is + !! compared with the trapezoidal integral of control_power over the steps. + REAL(wp), PARAMETER :: DT = 0.005_wp, T0 = 0.5_wp, TR = 10.0_wp, TEND = 15.0_wp, AMP = 0.5_wp + TYPE(CD_HermiteCableDynType) :: m + REAL(wp) :: l0(NE), t, u, dl, dldot, e0, e1, w(2), p0(2), p1(2), err, wmax + INTEGER :: k, es + CHARACTER(300) :: em + l0 = 1.0_wp + CALL build_line(m, l0, 1.0_wp, 1.0_wp, 0.0_wp, 0.5_wp, 0.0_wp, .TRUE., es, em, phi=1.0_wp) + CALL require(es == CD_HCDYN_OK .AND. m%tw_active, 'E: build: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + DO k = 1, NINT(T0/DT) + t = REAL(k, wp)*DT + CALL CD_HermiteCable_Dyn_Set_Torsion_Drive(m, m%torsion%ends, & + 1.0_wp + 0.3_wp*(t/T0 - SIN(2.0_wp*PI*t/T0)/(2.0_wp*PI)), es, em) + IF (es == CD_HCDYN_OK) CALL CD_HermiteCable_Dyn_Step(m, DT, 50, 1.0e-11_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'E: the driven steps: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + END DO + CALL energy_of(m, e0) + p0 = control_power(m) + w = 0.0_wp + err = 0.0_wp + wmax = 0.0_wp + DO k = NINT(T0/DT) + 1, NINT(TEND/DT) + t = REAL(k, wp)*DT + u = MIN(MAX((t - T0)/TR, 0.0_wp), 1.0_wp) + dl = AMP*u**3*(10.0_wp - 15.0_wp*u + 6.0_wp*u**2) + dldot = AMP*30.0_wp*u**2*(1.0_wp - u)**2/TR + CALL command(m, dl, dldot, es, em) + IF (es == CD_HCDYN_OK) CALL CD_HermiteCable_Dyn_Step(m, DT, 50, 1.0e-11_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'E: march: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) EXIT + CALL energy_of(m, e1) + p1 = control_power(m) + ! trapezoidal work of the step: the power at t_{k-1} (its lengths and the rate commanded + ! then) and at t_k + w = w + 0.5_wp*DT*(p0 + p1) + p0 = p1 + err = MAX(err, ABS(e1 - e0 - SUM(w))) + wmax = MAX(wmax, ABS(SUM(w))) + END DO + WRITE (*, '(A,2ES12.4,A,ES12.5,A,ES10.3)') 'E energy: work of the length change (elastic, inertial) ', w, & + ' J of ', e1, ' J; max balance error ', err/wmax + CALL require(wmax > 1.0e-2_wp*e0, 'E: the length change does measurable work') + CALL require(err <= 2.0e-3_wp*wmax, 'E: the twist energy changes by the work of the length change') + CALL require(ABS(w(2)) > 10.0_wp*err, 'E: the balance resolves the inertial share (the lumped Irn l0/2 follows)') + CALL CD_HermiteCable_Dyn_End(m) + END SUBROUTINE check_energy + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE check_lag() + !! L: Irn 0.5 kg m, -zeta 0.2 damping, every cable DOF held, Phi = 1 rad; the span paid out by + !! 0.5 m on a smoothstep over 20 s, dt 0.01 s, at rho_inf = 0 and 0.4, and at 0.4 with the + !! committed force dropped before every step (re-selecting the force blend does), so each + !! step evaluates it at the committed lengths instead of reusing the converged one. + REAL(wp), PARAMETER :: DT = 0.01_wp, TR = 20.0_wp, AMP = 0.5_wp + INTEGER, PARAMETER :: NSTEP = NINT(TR/DT) + TYPE(CD_HermiteCableDynType) :: m + REAL(wp) :: l0(NE), t, u, dl, dldot, hist(NSTEP, 3), ntq(NN), err_qs, d_step, diff, diff_fresh, jump, prev, mqs + INTEGER :: k, es, pass + CHARACTER(300) :: em + l0 = 1.0_wp + err_qs = 0.0_wp + jump = 0.0_wp + DO pass = 1, 3 + CALL build_line(m, l0, MERGE(0.0_wp, 0.4_wp, pass == 1), 1.0_wp, 0.0_wp, 0.5_wp, 0.0_wp, .TRUE., es, em, & + zeta=[(0.2_wp, k=1, NE)], phi=1.0_wp) + CALL require(es == CD_HCDYN_OK, 'L: build: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) RETURN + prev = GJ*1.0_wp/LS + DO k = 1, NSTEP + t = REAL(k, wp)*DT + u = MIN(t/TR, 1.0_wp) + dl = AMP*u**3*(10.0_wp - 15.0_wp*u + 6.0_wp*u**2) + dldot = AMP*30.0_wp*u**2*(1.0_wp - u)**2/TR + CALL command(m, dl, dldot, es, em) + IF (pass == 3 .AND. es == CD_HCDYN_OK) CALL CD_HermiteCable_Dyn_Set_ForceBlend(m, .TRUE., es, em) + IF (es == CD_HCDYN_OK) CALL CD_HermiteCable_Dyn_Step(m, DT, 50, 1.0e-11_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'L: march: '//TRIM(em)) + IF (es /= CD_HCDYN_OK) EXIT + CALL CD_HermiteCable_Dyn_Node_Torque(m, ntq, es, em) + hist(k, pass) = ntq(1) + mqs = GJ*1.0_wp/(LS + dl) + err_qs = MAX(err_qs, ABS(ntq(1) - mqs)/mqs) + jump = MAX(jump, ABS(ntq(1) - prev)) + prev = ntq(1) + END DO + CALL CD_HermiteCable_Dyn_End(m) + END DO + ! the largest per-step change of the quasi-static torque GJ Phi/L(t): at the peak rate, + ! 15/8 AMP/TR, at the mid-ramp length + d_step = GJ*1.0_wp*(15.0_wp/8.0_wp)*AMP/TR*DT/(LS + 0.5_wp*AMP)**2 + diff = MAXVAL(ABS(hist(:, 2) - hist(:, 1))) + diff_fresh = MAXVAL(ABS(hist(:, 3) - hist(:, 1))) + WRITE (*, '(A,ES10.3,A,ES10.3,A,2ES10.3,A,ES10.3)') 'L slow pay-out: torque vs GJ Phi/L(t) ', err_qs, & + '; per-step change ', d_step, ' N m; rho_inf 0.4 vs 0 (reused, fresh committed force) ', diff, diff_fresh, & + '; largest step ', jump + CALL require(err_qs <= 1.0e-3_wp, 'L: the torque follows GJ Phi/L(t)') + CALL require(diff <= 5.0e-2_wp*d_step, 'L: the alpha_f > 0 run follows the alpha_f = 0 one (no lag)') + CALL require(diff_fresh <= 5.0e-2_wp*d_step, & + 'L: a committed force evaluated afresh is taken at the committed lengths (no lag)') + CALL require(jump <= 1.5_wp*d_step, 'L: no step changes the torque by more than the quasi-static change') + END SUBROUTINE check_lag + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE build_coupled(cab, es, em) + !! The bowed 10 m HFMF cable of the nodal-twist gates (20 elements): node 21 coupled, node 1 + !! held, Rigid bending ends along +x, the coupled torsion frame on the parent, Irn 0.05, + !! K 200 N m, -zeta 0.1 torsional damping, Phi 1 rad. + TYPE(CD_HFMF_ModuleType), INTENT(INOUT) :: cab + INTEGER, INTENT(OUT) :: es + CHARACTER(*), INTENT(OUT) :: em + INTEGER, PARAMETER :: NE2 = 20, NN2 = NE2 + 1, ND2 = 6*NN2 + REAL(wp), PARAMETER :: KC = 200.0_wp + TYPE(CD_HermiteTorsionType) :: tors + REAL(wp) :: q(ND2), l0(NE2), eye(3, 3), frame(3, 2), s, g(ND2), raw + INTEGER :: k + l0 = LS/REAL(NE2, wp) + q = 0.0_wp + DO k = 1, NN2 + s = LS*REAL(k - 1, wp)/REAL(NE2, wp) + q(6*k - 5) = s + q(6*k - 4) = 0.3_wp*SIN(PI*s/LS)**2 + q(6*k - 3) = 0.1_wp*SIN(2.0_wp*PI*s/LS)**2 + q(6*k - 2) = 1.0_wp + q(6*k - 1) = 0.3_wp*(PI/LS)*SIN(2.0_wp*PI*s/LS) + q(6*k) = 0.1_wp*(2.0_wp*PI/LS)*SIN(4.0_wp*PI*s/LS) + END DO + eye = 0.0_wp + DO k = 1, 3 + eye(k, k) = 1.0_wp + END DO + CALL CD_HFMF_Init(cab, l0, [(EA - KC**2/GJ, k=1, NE2)], [(EI, k=1, NE2)], [(1.0_wp, k=1, NE2)], & + [(0.0_wp, k=1, NE2)], q, [1, 2, 3, ND2 - 5, ND2 - 4, ND2 - 3], 0.0_wp, 0.0_wp, 0.8_wp, 0.01_wp, & + NN2, es, em, max_iter=60, tol=1.0e-10_wp) + IF (es /= CD_HFMF_OK) RETURN + CALL CD_HFMF_Set_EndConnection(cab, [0.0_wp, 0.0_wp], RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp], & + [3, 2]), es, em, & + coupled_d0_parent=[1.0_wp, 0.0_wp, 0.0_wp], parent_orientation=eye, & + connection_mode=[CD_ENDCONN_RIGID, CD_ENDCONN_RIGID]) + IF (es /= CD_HFMF_OK) RETURN + tors%active = .TRUE. + tors%phi = 1.0_wp + tors%ends = RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 1.0_wp, 0.0_wp, 0.0_wp, & + 0.0_wp, 0.0_wp, 1.0_wp], [3, 4]) + tors%end_compliance = 0.0_wp + tors%gj = [(GJ, k=1, NE2)] + tors%couple = [(KC/GJ, k=1, NE2)] + tors%irn = [(0.05_wp, k=1, NE2)] + tors%bt_zeta = [(0.1_wp, k=1, NE2)] + tors%bt = CD_HermiteTorsion_Zeta_Damping(tors%bt_zeta, l0, GJ, 0.05_wp) + CALL CD_HermiteTorsion_Line(q, l0, tors%ends, raw, g, es, em, couple=tors%couple) + IF (es /= CD_HTORS_OK) RETURN + tors%theta = CD_HermiteTorsion_Unwrap(raw, 0.0_wp) + tors%has_theta = .TRUE. + frame(:, 1) = [1.0_wp, 0.0_wp, 0.0_wp] + frame(:, 2) = [0.0_wp, 0.0_wp, 1.0_wp] + CALL CD_HFMF_Set_Torsion(cab, tors, es, em, coupled_frame_parent=frame, parent_orientation=eye) + END SUBROUTINE build_coupled + + SUBROUTINE coupled_command(cab, k, es, em, restored) + !! The command of step k: the two elements at the coupled end (base 0.5 m each) paid out by + !! 0.15 m on a half cosine over 3 s, then held. + TYPE(CD_HFMF_ModuleType), INTENT(INOUT) :: cab + INTEGER, INTENT(IN) :: k + INTEGER, INTENT(OUT) :: es + CHARACTER(*), INTENT(OUT) :: em + LOGICAL, INTENT(IN), OPTIONAL :: restored + REAL(wp), PARAMETER :: TR = 3.0_wp, AMP = 0.15_wp, S = 1.0_wp + REAL(wp) :: t, dl, dldot + t = 0.01_wp*REAL(k, wp) + IF (t < TR) THEN + dl = AMP*0.5_wp*(1.0_wp - COS(PI*t/TR)) + dldot = AMP*0.5_wp*(PI/TR)*SIN(PI*t/TR) + ELSE + dl = AMP + dldot = 0.0_wp + END IF + CALL CD_HFMF_Set_SegmentLength(cab, [19, 20], [0.5_wp, 0.5_wp]*((S + dl)/S), [0.5_wp, 0.5_wp]*(dldot/S), & + es, em, restored=restored) + END SUBROUTINE coupled_command + + SUBROUTINE coupled_march(cab, k0, k1, ok) + !! Steps k0 + 1 .. k1: the command, then a lateral sway of the coupled end with a parent roll + !! about the line (2 rad/s) and an imposed twist following it. + TYPE(CD_HFMF_ModuleType), INTENT(INOUT) :: cab + INTEGER, INTENT(IN) :: k0, k1 + LOGICAL, INTENT(OUT) :: ok + REAL(wp) :: t, x(3), v(3), a(3), dcm(3, 3), w(3), al(3), phi + INTEGER :: k, es + CHARACTER(300) :: em + ok = .TRUE. + DO k = k0 + 1, k1 + t = 0.01_wp*REAL(k, wp) + x = [LS, 0.05_wp*SIN(2.0_wp*t), 0.0_wp] + v = [0.0_wp, 0.1_wp*COS(2.0_wp*t), 0.0_wp] + a = [0.0_wp, -0.2_wp*SIN(2.0_wp*t), 0.0_wp] + dcm = 0.0_wp + dcm(1, 1) = 1.0_wp + dcm(2, 2) = COS(2.0_wp*t) + dcm(3, 3) = COS(2.0_wp*t) + dcm(2, 3) = SIN(2.0_wp*t) + dcm(3, 2) = -SIN(2.0_wp*t) + w = [2.0_wp, 0.0_wp, 0.0_wp] + al = 0.0_wp + phi = 1.0_wp - 2.0_wp*t + 0.3_wp*SIN(2.0_wp*t) + CALL coupled_command(cab, k, es, em) + IF (es == CD_HFMF_OK) CALL CD_HFMF_UpdateStates(cab, x, v, a, es, em, u_orientation=dcm, u_angular_velocity=w, & + u_angular_acceleration=al, u_twist=phi) + IF (es /= CD_HFMF_OK) THEN + WRITE (*, '(A,I0,A)') ' coupled step ', k, ': '//TRIM(em) + ok = .FALSE. + RETURN + END IF + END DO + END SUBROUTINE coupled_march + + SUBROUTINE check_restart() + !! R: 150 steps (mid-ramp), snapshot and mirror, 100 more; restore and redo the 100. A fresh + !! module given the command of step 150 as committed and then the mirror redoes them too. + TYPE(CD_HFMF_ModuleType), ALLOCATABLE :: cab, cab2 + REAL(wp), ALLOCATABLE :: mirror(:), qref(:), pref(:), mref(:) + INTEGER :: es + LOGICAL :: ok + CHARACTER(300) :: em + ALLOCATE (cab, cab2) + CALL build_coupled(cab, es, em) + CALL require(es == CD_HFMF_OK .AND. cab%line%tw_active, 'R: build: '//TRIM(em)) + IF (es /= CD_HFMF_OK) RETURN + CALL coupled_march(cab, 0, 150, ok) + CALL require(ok .AND. cab%line%has_ctrl, 'R: first leg under the pay-out ramp') + IF (.NOT. ok) RETURN + CALL CD_HFMF_Snapshot(cab, es, em) + CALL require(es == CD_HFMF_OK, 'R: snapshot: '//TRIM(em)) + ALLOCATE (mirror(CD_HFMF_MirrorSize(cab))) + CALL CD_HFMF_PackMirror(cab, mirror, es, em) + CALL require(es == CD_HFMF_OK, 'R: mirror pack: '//TRIM(em)) + CALL coupled_march(cab, 150, 250, ok) + CALL require(ok, 'R: second leg') + qref = cab%line%q + pref = cab%line%tw_phi + mref = cab%line%tw_mt + CALL CD_HFMF_Restore(cab, es, em) + CALL require(es == CD_HFMF_OK, 'R: restore: '//TRIM(em)) + CALL coupled_march(cab, 150, 250, ok) + CALL require(ok .AND. same_bits(cab%line%q, qref) .AND. same_bits(cab%line%tw_phi, pref) .AND. & + same_bits(cab%line%tw_mt, mref), 'R: the run restored from the snapshot continues bit-identically') + CALL build_coupled(cab2, es, em) + CALL require(es == CD_HFMF_OK, 'R: rebuild: '//TRIM(em)) + CALL coupled_command(cab2, 150, es, em, restored=.TRUE.) + CALL require(es == CD_HFMF_OK, 'R: the checkpointed command re-applied: '//TRIM(em)) + CALL CD_HFMF_UnpackMirror(cab2, mirror, 1.5_wp, es, em) + CALL require(es == CD_HFMF_OK, 'R: mirror reload: '//TRIM(em)) + CALL coupled_march(cab2, 150, 250, ok) + CALL require(ok .AND. same_bits(cab2%line%q, qref) .AND. same_bits(cab2%line%tw_phi, pref) .AND. & + same_bits(cab2%line%tw_mt, mref), 'R: the run rebuilt from the mirror continues bit-identically') + WRITE (*, '(A,F9.5,A,F9.5,A)') 'R restart mid-ramp: span ', SUM(cab%line%l0(19:20)), ' m, end twist angle ', & + pref(SIZE(pref)), ' rad; snapshot and mirror runs identical' + CALL CD_HFMF_End(cab) + CALL CD_HFMF_End(cab2) + END SUBROUTINE check_restart + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE write_deck(path) + !! The straight neutral 100 m torsion line of test_coupled_torsion (40 segments, GJ 5e4, + !! Irn 1e-9, torsional damping -zeta = -0.1), End A Coupled at (0, 0, -50) with a 30 deg + !! pretwist, End B Fixed, controlled on channel 1; outputs Torq1N1 and Twist1. + CHARACTER(*), INTENT(IN) :: path + INTEGER :: u + CHARACTER(160) :: neutral_type + WRITE (neutral_type, '(A,ES24.16,A)') 'cab 0.2 ', 1025.0_wp*0.25_wp*PI*0.04_wp, & + ' 1.0e7 0.0 1.0e6 1.0e8 5.0e4|0|-0.1 1.0 1.0e-9 0.0 0.0 0.0 0.0' + OPEN (NEWUNIT=u, FILE=path, STATUS='REPLACE', ACTION='WRITE') + WRITE (u, '(A)') 'controlled torsion line' + WRITE (u, '(A)') '--- LINE TYPES ---' + WRITE (u, '(A)') 'Name Diam Mass EA BA EI GAs GJ Irt Irn Cdn Cdt Can Cat' + WRITE (u, '(A)') '(-) (m) (kg/m) (N) (-) (Nm2) (N) (Nm2) (kgm) (kgm) (-) (-) (-) (-)' + WRITE (u, '(A)') TRIM(neutral_type) + WRITE (u, '(A)') '--- POINTS ---' + WRITE (u, '(A)') 'ID Type X Y Z Mass Vol CdA Ca' + WRITE (u, '(A)') '(-) (-) (m) (m) (m) (kg) (m3) (m2) (-)' + WRITE (u, '(A)') '1 Coupled 0.0 0.0 -50.0 0 0 0 0' + WRITE (u, '(A)') '2 Fixed 100.0 0.0 -50.0 0 0 0 0' + WRITE (u, '(A)') '--- LINES ---' + WRITE (u, '(A)') 'ID NodeA NodeB Outputs' + WRITE (u, '(A)') '(-) (-) (-) (-)' + WRITE (u, '(A)') '1 1 2 -' + WRITE (u, '(A)') '--- SECTIONS ---' + WRITE (u, '(A)') 'LineID LineType Length NumSegs' + WRITE (u, '(A)') '(-) (-) (m) (-)' + WRITE (u, '(A)') '1 cab 100.0 40' + WRITE (u, '(A)') '--- END CONNECTIONS ---' + WRITE (u, '(A)') 'LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist' + WRITE (u, '(A)') '(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg)' + WRITE (u, '(A)') '1 A Rigid 1 0 0 Rigid 0 0 1 30' + WRITE (u, '(A)') '1 B Rigid 1 0 0 Rigid 0 0 1 0' + WRITE (u, '(A)') '--- CONTROL ---' + WRITE (u, '(A)') 'ChannelID Line(s)' + WRITE (u, '(A)') '(-) (-)' + WRITE (u, '(A)') '1 1' + WRITE (u, '(A)') '--- OPTIONS ---' + WRITE (u, '(A)') '9.80665 g' + WRITE (u, '(A)') '1025.0 rhoW' + WRITE (u, '(A)') '0.05 dtM' + WRITE (u, '(A)') '--- OUTPUTS ---' + WRITE (u, '(A)') 'Torq1N1' + WRITE (u, '(A)') 'Twist1' + WRITE (u, '(A)') '--- END ---' + CLOSE (u) + END SUBROUTINE write_deck + + SUBROUTINE deck_command(step, dl, dldot) + !! A haul-in of 0.1 m on a half cosine over 1 s (20 steps of 0.05 s), then held. + INTEGER, INTENT(IN) :: step + REAL(wp), INTENT(OUT) :: dl, dldot + REAL(wp) :: t + t = 0.05_wp*REAL(step, wp) + IF (t < 1.0_wp) THEN + dl = -0.1_wp*0.5_wp*(1.0_wp - COS(PI*t)) + dldot = -0.1_wp*0.5_wp*PI*SIN(PI*t) + ELSE + dl = -0.1_wp + dldot = 0.0_wp + END IF + END SUBROUTINE deck_command + + SUBROUTINE check_deck() + !! S: reference A marches 30 steps (the ramp and a hold), Torq1N1 against GJ Twist1/L(t). + !! B is rebuilt at step 12 (mid-ramp) with the shell's recipe (torsion mirror, coupled + !! kinematics, the command re-applied as committed, full mirror) and both march 12 more. + REAL(wp), PARAMETER :: DT = 0.05_wp, GJD = 5.0e4_wp, DEG = PI/180.0_wp + TYPE(CD_AGG_ModuleType) :: a, b + REAL(wp) :: pos(3, 1), vel(3, 1), acc(3, 1), load(3, 1), orient(3, 3, 1), omega(3, 1), alpha(3, 1) + REAL(wp) :: dl, dldot, tq, tw, tqb, twb, err, lt, t + REAL(wp), ALLOCATABLE :: mirror(:) + INTEGER :: es, ni, k + LOGICAL :: cv, st, same + CHARACTER(512) :: em + CALL write_deck('ctl_torsion_deck.dat') + CALL CD_AGG_Init_From_Deck(a, 'ctl_torsion_deck.dat', DT, es, em, host_orientation=.TRUE.) + CALL require(es == CD_AGG_OK, 'S: a deck with CONTROL on a line restrained in torsion initialises: '//TRIM(em)) + IF (es /= CD_AGG_OK) RETURN + CALL require(a%ctrl_is_cable(1) .AND. a%cables(1)%line%tw_active .AND. & + a%ctrl_elem(1) + a%ctrl_nelem(1) - 1 == a%cables(1)%line%ne, & + 'S: the row controls the fairlead segment of the nodal-twist cable') + CALL require(ALLOCATED(a%cables(1)%line%torsion%bt_zeta), 'S: the deck keeps the -zeta of its torsional damping') + IF (.NOT. ALLOCATED(a%cables(1)%line%torsion%bt_zeta)) RETURN + CALL require(ALL(a%cables(1)%line%torsion%bt_zeta == 0.1_wp), 'S: zeta = 0.1 on every element') + CALL CD_AGG_GetMovingPointMesh(a, pos, vel, acc, load, es, em, orientation=orient) + omega = 0.0_wp + alpha = 0.0_wp + err = 0.0_wp + same = .TRUE. + DO k = 1, 30 + CALL deck_command(k, dl, dldot) + CALL CD_AGG_Apply_LineControl(a, [dl], [dldot], es, em) + CALL require(es == CD_AGG_OK, 'S: command: '//TRIM(em)) + CALL CD_AGG_Step_Moving(a, DT, pos, vel, acc, cv, st, ni, es, em, orientation=orient, & + angular_velocity=omega, angular_acceleration=alpha) + CALL require(es == CD_AGG_OK .AND. cv, 'S: step: '//TRIM(em)) + IF (es /= CD_AGG_OK) RETURN + CALL CD_AGG_CalcOutput(a, es, em) + CALL CD_AGG_EvalChannel(a, 1, tq, es, em) + CALL CD_AGG_EvalChannel(a, 2, tw, es, em) + IF (k == 10) THEN + ASSOCIATE (cl => a%cables(1)%line, e1 => a%ctrl_elem(1)) + CALL require(ALL(cl%torsion%bt(e1:cl%ne) == CD_HermiteTorsion_Zeta_Damping(0.1_wp, cl%l0(e1:cl%ne), GJD, & + 1.0e-9_wp)), & + 'S: the commanded elements re-resolve the deck''s -zeta at their new lengths') + END ASSOCIATE + END IF + lt = 100.0_wp + dl + err = MAX(err, ABS(tq - GJD*tw*DEG/lt)/ABS(GJD*tw*DEG/lt)) + IF (k == 12) THEN + t = DT*REAL(k, wp) + ALLOCATE (mirror(CD_HFMF_MirrorSize(a%cables(1)))) + CALL CD_HFMF_PackMirror(a%cables(1), mirror, es, em) + CALL CD_AGG_Init_From_Deck(b, 'ctl_torsion_deck.dat', DT, es, em, host_orientation=.TRUE.) + CALL require(es == CD_AGG_OK, 'S: rebuild: '//TRIM(em)) + CALL CD_HFMF_UnpackMirror(b%cables(1), mirror, t, es, em) + CALL require(es == CD_HFMF_OK, 'S: torsion mirror first: '//TRIM(em)) + CALL CD_AGG_UpdateStates_Moving(b, pos, vel, acc, es, em, orientation=orient, angular_velocity=omega, & + angular_acceleration=alpha) + CALL require(es == CD_AGG_OK, 'S: coupled kinematics: '//TRIM(em)) + CALL CD_AGG_Apply_LineControl(b, [dl], [dldot], es, em, restored=.TRUE.) + CALL require(es == CD_AGG_OK, 'S: the checkpointed command re-applied: '//TRIM(em)) + CALL CD_HFMF_UnpackMirror(b%cables(1), mirror, t, es, em) + CALL require(es == CD_HFMF_OK, 'S: full mirror: '//TRIM(em)) + ELSE IF (k > 12 .AND. k <= 24) THEN + CALL CD_AGG_Apply_LineControl(b, [dl], [dldot], es, em) + CALL CD_AGG_Step_Moving(b, DT, pos, vel, acc, cv, st, ni, es, em, orientation=orient, & + angular_velocity=omega, angular_acceleration=alpha) + CALL require(es == CD_AGG_OK .AND. cv, 'S: restarted step: '//TRIM(em)) + CALL CD_AGG_CalcOutput(b, es, em) + CALL CD_AGG_EvalChannel(b, 1, tqb, es, em) + CALL CD_AGG_EvalChannel(b, 2, twb, es, em) + same = same .AND. same_bits(a%cables(1)%line%q, b%cables(1)%line%q) .AND. & + same_bits(a%cables(1)%line%tw_phi, b%cables(1)%line%tw_phi) .AND. same_bits([tq, tw], [tqb, twb]) + END IF + END DO + WRITE (*, '(A,F9.4,A,ES15.7,A,ES10.3)') 'S deck: Twist1 ', tw, ' deg, Torq1N1 ', tq, & + '; max rel. error against GJ Twist1/L(t) ', err + CALL require(ABS(ABS(tw) - 30.0_wp) <= 1.0e-6_wp, 'S: the line keeps its 30 deg twist') + CALL require(err <= 1.0e-6_wp, 'S: Torq1N1 follows GJ Twist1/L(t) through the haul-in') + CALL require(same, 'S: the checkpoint restart mid-ramp continues bit-identically') + CALL CD_AGG_End(a, es, em) + CALL CD_AGG_End(b, es, em) + END SUBROUTINE check_deck + +END PROGRAM test_control_torsion diff --git a/tests/test_hermite_cable_control.f90 b/tests/test_hermite_cable_control.f90 index 590a74f0..edb04a18 100644 --- a/tests/test_hermite_cable_control.f90 +++ b/tests/test_hermite_cable_control.f90 @@ -7,9 +7,9 @@ PROGRAM test_hermite_cable_control !! A the update is inert when nothing changes (a rate of -0 included), rebuilds every !! length-dependent cache to what a model built with the new lengths carries (bit for !! bit), leaves the committed lengths to a re-derived acceleration, is atomic on - !! failure, refuses a torsion line, a contact line without the seabed recompute inputs - !! and the configuration blend, is taken back exactly by a saved control state, and - !! joins the snapshot/restore contract exactly; + !! failure, refuses a contact line without the seabed recompute inputs and the + !! configuration blend, is taken back exactly by a saved control state, and joins the + !! snapshot/restore contract exactly (a line restrained in torsion: test_control_torsion); !! B a hanging vertical cable whose top span is paid out settles to the top reaction !! w (L + DeltaL) and the stretched length L' + w L'**2/(2 EA); !! C a taut vertical cable whose top span is hauled in settles to the top tension @@ -209,10 +209,6 @@ SUBROUTINE check_model_contract() CALL CD_HermiteCable_Dyn_Set_SegmentLength(a, SPAN, [1.0_wp, -1.0_wp], [0.0_wp, 0.0_wp], es, em) CALL require(es /= CD_HCDYN_OK .AND. unchanged(a, ref), 'A: a non-positive length fails and writes nothing') twin = a - twin%torsion%active = .TRUE. - CALL CD_HermiteCable_Dyn_Set_SegmentLength(twin, SPAN, [1.0_wp, 1.0_wp], [0.0_wp, 0.0_wp], es, em) - CALL require(es /= CD_HCDYN_OK .AND. INDEX(em, 'torsion') > 0, 'A: a line restrained in torsion fails closed') - twin%torsion%active = .FALSE. twin%has_seabed_recompute = .FALSE. CALL CD_HermiteCable_Dyn_Set_SegmentLength(twin, SPAN, [1.0_wp, 1.0_wp], [0.0_wp, 0.0_wp], es, em) CALL require(es /= CD_HCDYN_OK .AND. INDEX(em, 'seabed recompute') > 0, & From 5e38d29f4b6a4f7b734d3a25ecda170020ec85e5 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 17:42:58 +0900 Subject: [PATCH 4/7] fix(torsion): reload the committed torque of a nodal-twist line Review follow-ups to the active line control of lines restrained in torsion. - The checkpoint mirror of a line with the nodal twist carries its committed torque (CD_HermiteCable_Dyn_Twist_Mirror_Size gains one value), so a reload brings it back as it was formed, as Restore does. A frame write or a re-derived committed state forms it as the summed twist over the compliance, which (Phi - Theta)/C reproduces only to round-off. The condensed torque is formed as (Phi - Theta)/C at every commit and frame write, so the reload keeps re-deriving it at the re-applied lengths. - test_control_torsion F runs at interior elements, at both rigid torsional ends (End A the fairlead, the element OpenFAST controls) and with coupling K/GJ = 0.5: the length-rate damping torque matches central differences of Bt l0_dot d(tau/l0)/dl0 to 1.3e-10 (the straight-line value is up to a factor 5 off), and the torque tangent a step assembles, read back at the state of its last assembly, matches central differences of the torque to 1.1e-9, where the length-rate share is 1.6e-3 to 7.6e-3 of it. - R: after a non-stepping frame write the snapshot and the mirror bring back the committed torque bit for bit; re-derived it would differ by 1.8e-15 N m. - The Set_SegmentLength header reflowed; VALIDATION T-14 gives the lag of a committed force at the new lengths as the expected alpha_f = 2/7 (0.289 measured by ablation); doc/theory.rst names the tangent DOFs a_i apart from the reference twist m_e. - test_native_model's handle-release gate collects garbage before it tracks close(): in the full Python run an unreachable model of an earlier test was finalised inside the failing constructor, through the tracker, and the gate read its close first. Full suite passes; all 53 example decks are bit-identical. Signed-off-by: Jae Hoon Seo --- CHANGELOG.md | 3 +- VALIDATION.md | 14 +- doc/theory.rst | 16 +- src/CableDyn_HermiteCableDynamic.f90 | 23 +-- src/CableDyn_OpenFAST_HermiteFMF.f90 | 9 +- tests/test_control_torsion.f90 | 217 ++++++++++++++++++++++----- 6 files changed, 221 insertions(+), 61 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c4e1e63c..ac9ee836 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -102,7 +102,8 @@ All notable changes to CableDyn are recorded in this file. The format follows `GJ Φ/L(t) + K (H − L)/L` to 1.5e-12 and its tension to 4e-6; a constant pay-out carries the Kelvin–Voigt torque to 6e-6 N m of its 0.64 N m damping share; a pay-out under a ringing twist balances the energy to 8e-5 of the work done; restarts mid-ramp (snapshot, checkpoint mirror, - a coupled deck) are bit-identical. + a coupled deck) are bit-identical. The checkpoint mirror of a line with the nodal twist gains + one value, its committed torque. - Torque–tension coupling of finite-EI cables: the 14-column LINE TYPES row's `GJ` column takes `GJ|K`, with `K` the coupling of an armoured cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`). The cable carries the axial stiffness `EA − K²/GJ` of a section free to twist. diff --git a/VALIDATION.md b/VALIDATION.md index 831ddfa8..52c73878 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -102,7 +102,7 @@ article's methods, are compared in | **T-8** | Cross-check with the Cosserat rod path | Cosserat path | shape 4.2e-4 L, torque 5.2e-5 | <1% | Pass | | **T-9** | Bordered Newton step on post-buckled states | predicted linear rate without the rank-one term | 3 iterations; rate 0.055 / 0.217 vs 0.055 / 0.218 | ≤4; within 25% | Pass | | **T-10** | Torsion dynamics, restart and body torque | quasi-static torque, energy, uninterrupted run, pendulum | torque 2.2e-16; energy band 4.9e-4; restart bit-identical; pendulum 6.4e-5 | see [Torsion](#torsion) | Pass | -| **T-14** | Active line control of a line restrained in torsion | `GJ Φ/L(t) + K (H − L)/L`; Kelvin–Voigt torque of a pay-out; finite differences; energy of a length change; `ρ∞ = 0`; uninterrupted run | torque ≤1.5e-12, tension 3.6e-6; damping 5.8e-6 N·m of 0.64 N·m; FD 1.1e-10; energy 7.8e-5; no lag (1.4e-3 of the per-step change); restart bit-identical | see [Torsion](#torsion) | Pass | +| **T-14** | Active line control of a line restrained in torsion | `GJ Φ/L(t) + K (H − L)/L`; Kelvin–Voigt torque of a pay-out; finite differences; energy of a length change; `ρ∞ = 0`; uninterrupted run | torque ≤1.5e-12, tension 3.6e-6; damping 5.8e-6 N·m of 0.64 N·m; FD 1.3e-10, tangent 1.1e-9; energy 7.8e-5; no lag (1.4e-3 of the per-step change); restart bit-identical | see [Torsion](#torsion) | Pass | | **T-13** | Nodal twist (torsional inertia and damping) | condensed torsion in the limit of no inertia; continuum torsional wave; `ζ = ω Bt/(2 GJ)`; energy; restart | ≤6e-7 against the condensed torsion; wave torque 0.07 %; decrement 6 %; energy band 4.9e-4; restart bit-identical | see [Torsion](#torsion) | Pass | | **T-12** | Torque–tension coupling | `T = EA ε + K τ`, `M = GJ τ + K ε` closed forms; kernel FD; march | ≤1e-7 against every closed form; kernel gradient 1.7e-10, Hessian 9.8e-11 | see [Torsion](#torsion) | Pass | | **T-11** | Torsion on the coupled OpenFAST / FAST.Farm route | `GJ (−roll)/L`; single coupled cable; uninterrupted run | twist ≤1.8e-15°, torque ≤1.7e-13 N·m; aggregate = single cable bit for bit; restart bit-identical (aggregate and `openfast -restart`) | see [Torsion](#torsion) | Pass | @@ -1059,7 +1059,10 @@ in parentheses). length χ and the torque is `GJ χ + Bt χ̇` to 5.8e-6 N·m of its 0.642 N·m damping share (0.646 N·m off without the length rate); - on a bowed line the length-rate share of the damping torque equals `Bt l̇0 ∂(τ/l0)/∂l0` by - central differences of the element twist to 1.1e-10 (1.7 % from the straight-line value); + central differences of the element twist to 1.3e-10 on interior elements, at both rigid + torsional ends (End A the fairlead) and with `K/GJ = 0.5` (the straight-line value is up to + a factor 5 off), and the torque tangent a step assembles matches central differences of the + torque to 1.1e-9, where its length-rate share is 1.6e-3 to 7.6e-3 of it; - the polar inertia and a `-ζ` damping a command rebuilds equal those of a model built with the new lengths bit for bit, and a committed-state evaluation, a saved control state and a snapshot take the committed lengths and terms; @@ -1067,10 +1070,13 @@ in parentheses). twist and polar kinetic energy change by the work of the length change to 7.8e-5 of it; - paid out slowly, the run at `ρ∞ = 0.4` follows the one at `ρ∞ = 0` to 1.4e-3 of the per-step torque change, also with the committed force evaluated afresh each step (taken at - the new lengths it lags by `α_f` of the change, 0.29); + the new lengths it would lag by the expected `α_f = 2/7` of the change; an ablation of the + committed lengths measured 0.289); - restarts mid-ramp from a snapshot, from the checkpoint mirror with the command re-applied, and of a `CONTROL` deck on the coupled aggregate (whose `Torq1N1` follows `GJ Twist1/L(t)` - to 6e-11) continue bit-identically. + to 6e-11) continue bit-identically; after a non-stepping frame write the snapshot and the + checkpoint mirror bring back the committed torque bit for bit (re-derived as `(Φ − Θ)/C` it + would differ by 1.8e-15 N·m). - **Backward compatibility and refusals** (`torsion_deck`, full suite). Without torsion columns, with `Free` columns (whatever their normal), or with one restrained end, every output is byte-identical to the 6-column deck, and `Rigid`, `Infinity`, `Inf` and a quoted `"Rigid"` diff --git a/doc/theory.rst b/doc/theory.rst index e32ab2b9..0f4f5c75 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -580,17 +580,19 @@ the axial damping takes the rate of the strain: \Big(\dot{\hat\tau}_e - \hat\tau_e\,\frac{\dot L_{0,e}}{L_{0,e}}\Big) . At fixed :math:`\mathbf{q}` the twist changes with :math:`L_0` through the coupling term and the -element's shape. The reference twist depends on the tangent handles only through -:math:`L_0\mathbf{m}` (the Hermite :math:`\mathbf{r}'` and :math:`\mathbf{r}''`) and -:math:`\mathbf{m}/|\mathbf{m}|`, and so does :math:`l_e`, so -:math:`L_0\,\partial(m_e + c_e l_e)/\partial L_0 = \mathbf{m}_1\cdot\partial/\partial\mathbf{m}_1 + -\mathbf{m}_2\cdot\partial/\partial\mathbf{m}_2` of the same with :math:`c_e = K_e/GJ_e`, and +element's shape. Write :math:`\mathbf{a}_1, \mathbf{a}_2` for the tangent DOFs of the element's two +nodes (the nodal :math:`\mathbf{m} = d\mathbf{r}/ds`). The reference twist :math:`m_e` depends on +them only through :math:`L_0\mathbf{a}_i` (the Hermite :math:`\mathbf{r}'` and +:math:`\mathbf{r}''`) and :math:`\mathbf{a}_i/|\mathbf{a}_i|`, and the stretched length +:math:`l_e` only through :math:`L_0\mathbf{a}_i`, so with :math:`c_e = K_e/GJ_e` +:math:`L_0\,\partial(m_e + c_e l_e)/\partial L_0 = \sum_i \mathbf{a}_i\cdot\partial(m_e + c_e +l_e)/\partial\mathbf{a}_i`, and .. math:: \dot{\hat\tau}_e = \dot\varphi_{k+1} - \dot\varphi_k + \nabla\hat\tau_e\cdot\dot{\mathbf{q}} - + \frac{\dot L_{0,e}}{L_{0,e}}\Big(\mathbf{m}_1\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{m}_1} - + \mathbf{m}_2\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{m}_2} - c_e L_{0,e}\Big) , + + \frac{\dot L_{0,e}}{L_{0,e}}\Big(\mathbf{a}_1\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{a}_1} + + \mathbf{a}_2\cdot\frac{\partial\hat\tau_e}{\partial\mathbf{a}_2} - c_e L_{0,e}\Big) , with the matching tangent terms. A segment paid out at a constant twist per length carries no damping torque. The test suite checks the quasi-static torque :math:`GJ\Phi/L(t) + K(H - L)/L` of a diff --git a/src/CableDyn_HermiteCableDynamic.f90 b/src/CableDyn_HermiteCableDynamic.f90 index b8f46e9e..d5b6ffad 100644 --- a/src/CableDyn_HermiteCableDynamic.f90 +++ b/src/CableDyn_HermiteCableDynamic.f90 @@ -1698,10 +1698,9 @@ SUBROUTINE CD_HermiteCable_Dyn_Set_SegmentLength(model, elems, l0_new, l0_dot, E !! recompute inputs is refused, as is a model on the configuration-blended generalised-alpha !! (force blend off, CD_HermiteCable_Dyn_Set_ForceBlend), whose blended state has no !! committed-length treatment, so a ramp would lag by alpha_f times the length change. - !! restored = .TRUE. (a checkpoint - !! restart re-applying the command the committed state was reached with) makes the - !! lengths and rates the committed ones at once; a committed force reloaded with the - !! state belongs to them and stays valid. + !! restored = .TRUE. (a checkpoint restart re-applying the command the committed state was + !! reached with) makes the lengths and rates the committed ones at once; a committed force + !! reloaded with the state belongs to them and stays valid. TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: model INTEGER, INTENT(IN) :: elems(:) REAL(wp), INTENT(IN) :: l0_new(:), l0_dot(:) @@ -6814,11 +6813,13 @@ END SUBROUTINE CD_HermiteCable_Dyn_Twist_Check PURE INTEGER FUNCTION CD_HermiteCable_Dyn_Twist_Mirror_Size(model) RESULT(n) !! Reals of the nodal-twist checkpoint mirror (CD_HermiteCable_Dyn_Twist_Pack): the !! committed angles, rates and accelerations, directors, reference tangents, reference - !! twists, element torques, end-frame references and rates, and the force cache's angle - !! part; 0 without the nodal twist. + !! twists, element torques, end-frame references and rates, the force cache's angle part, + !! and the committed mean torque as it was formed (the summed twist over the compliance of + !! the lengths it was reached with, which a reload does not re-derive, as Restore does not); + !! 0 without the nodal twist. TYPE(CD_HermiteCableDynType), INTENT(IN) :: model n = 0 - IF (model%tw_active) n = tw_pack_size(model) + model%nn + IF (model%tw_active) n = tw_pack_size(model) + model%nn + 1 END FUNCTION CD_HermiteCable_Dyn_Twist_Mirror_Size SUBROUTINE CD_HermiteCable_Dyn_Twist_Pack(model, buf) @@ -6830,13 +6831,14 @@ SUBROUTINE CD_HermiteCable_Dyn_Twist_Pack(model, buf) n = tw_pack_size(model) CALL tw_pack(model, buf(1:n)) buf(n + 1:n + model%nn) = model%tw_fcR + buf(n + model%nn + 1) = model%torsion%torque END SUBROUTINE CD_HermiteCable_Dyn_Twist_Pack SUBROUTINE CD_HermiteCable_Dyn_Twist_Unpack(model, buf, ErrStat, ErrMsg, check_only) !! Reload the nodal twist from a mirror of CD_HermiteCable_Dyn_Twist_Pack written by a !! model built from the same input (the caller restores q, v, a and the force cache with - !! it). Fails closed on a size mismatch, a non-finite value or a non-unit director; with - !! check_only it only checks. + !! it), the committed torque included. Fails closed on a size mismatch, a non-finite value + !! or a non-unit director; with check_only it only checks. TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: model REAL(wp), INTENT(IN) :: buf(:) INTEGER, INTENT(OUT) :: ErrStat @@ -6848,7 +6850,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Twist_Unpack(model, buf, ErrStat, ErrMsg, check_o ErrMsg = 'CD_HermiteCable_Dyn_Twist_Unpack: the model has no nodal twist'; RETURN END IF n = tw_pack_size(model) - IF (SIZE(buf) /= n + model%nn) THEN + IF (SIZE(buf) /= n + model%nn + 1) THEN ErrMsg = 'CD_HermiteCable_Dyn_Twist_Unpack: the mirror does not match this line'; RETURN END IF IF (.NOT. CD_All_Finite(buf)) THEN @@ -6867,6 +6869,7 @@ SUBROUTINE CD_HermiteCable_Dyn_Twist_Unpack(model, buf, ErrStat, ErrMsg, check_o END IF CALL tw_unpack(model, buf(1:n)) model%tw_fcR = buf(n + 1:n + model%nn) + model%torsion%torque = buf(n + model%nn + 1) ErrStat = CD_HCDYN_OK ErrMsg = '' END SUBROUTINE CD_HermiteCable_Dyn_Twist_Unpack diff --git a/src/CableDyn_OpenFAST_HermiteFMF.f90 b/src/CableDyn_OpenFAST_HermiteFMF.f90 index ee92d5d0..52e57366 100644 --- a/src/CableDyn_OpenFAST_HermiteFMF.f90 +++ b/src/CableDyn_OpenFAST_HermiteFMF.f90 @@ -1751,8 +1751,10 @@ END FUNCTION CD_HFMF_BoundaryMirrorSize INTEGER FUNCTION CD_HFMF_TorsionMirrorSize(self) RESULT(n) !! Mirror slots of the torsion, last: the accepted (unwrapped) Theta, Phi and the four - !! end-frame vectors (14 values), then the nodal twist's state - !! (CD_HermiteCable_Dyn_Twist_Mirror_Size); zero without torsion. + !! end-frame vectors (14 values), then the nodal twist's state with its committed torque + !! (CD_HermiteCable_Dyn_Twist_Mirror_Size); zero without torsion. The condensed torque is + !! re-derived on a reload, (Phi - Theta)/C at the re-applied (committed) lengths, which is + !! how every step and frame write forms it. TYPE(CD_HFMF_ModuleType), INTENT(IN) :: self n = 0 IF (.NOT. self%initialized) RETURN @@ -2007,7 +2009,8 @@ SUBROUTINE CD_HFMF_UnpackMirror(self, buf, t, ErrStat, ErrMsg) self%line%torsion%torque = (self%line%torsion%phi - self%line%torsion%theta)/ & CD_HermiteTorsion_Compliance(self%line%torsion, self%line%l0) self%line%tors_drive_set = .FALSE. - ! the nodal twist, checked above (its force-cache part rides with the cable's) + ! the nodal twist, checked above (its force-cache part rides with the cable's); it brings + ! back the committed torque as it was formed (a summed twist over the compliance) IF (self%line%tw_active) CALL CD_HermiteCable_Dyn_Twist_Unpack(self%line, buf(k + 15:SIZE(buf)), es, em) ! (a parent-attached torsion frame turns with the parent orientation, which the boundary ! block restored as committed, so a later step without u_orientation holds it) diff --git a/tests/test_control_torsion.f90 b/tests/test_control_torsion.f90 index 864e3f26..5a5ede68 100644 --- a/tests/test_control_torsion.f90 +++ b/tests/test_control_torsion.f90 @@ -16,7 +16,9 @@ PROGRAM test_control_torsion !! GJ chi + Bt chi_dot with chi = (Phi + (K/GJ) H)/L - K/GJ; without the rate it is not; !! F the length-rate share of the torsional damping on a bowed line equals Bt l0_dot !! d(tau/l0)/dl0 by central differences of the element twist at fixed q (the Euler identity - !! l0 drho/dl0 = m . drho/dm of the element shape); + !! l0 drho/dl0 = m . drho/dm of the element shape), on interior elements, at both rigid + !! torsional ends (End A the fairlead) and with coupling, and the torque tangent the step + !! assembles matches central differences of the torque; !! Z the torsion terms a length change rebuilds equal those of a model built with the new !! lengths bit for bit (the lumped polar inertia Irn l0/2, a -zeta torsional damping !! re-resolved as zeta l0 sqrt(GJ Irn), a direct Bt kept); a committed-state evaluation @@ -33,7 +35,9 @@ PROGRAM test_control_torsion !! lags by alpha_f of it), and no step jumps; !! R restart mid-ramp: a rolling, twisting, torsionally damped coupled cable under a pay-out !! ramp continues bit-identically from a snapshot and from a module rebuilt from the - !! checkpoint mirror with the command re-applied; + !! checkpoint mirror with the command re-applied; after a non-stepping frame write (whose + !! torque is the summed twist over the compliance) both bring back that committed torque + !! bit for bit, which re-deriving it as (Phi - Theta)/C would not; !! S deck: a straight torsion line with a pretwist and a CONTROL row on the coupled aggregate !! (the CompMooring = 5 route; the standalone driver takes no CONTROL) initialises, its !! Torq1N1 follows GJ Twist1/L(t) through a haul-in ramp, and the shell's checkpoint recipe @@ -41,7 +45,8 @@ PROGRAM test_control_torsion USE CableDyn_Precision, ONLY: wp USE CableDyn_EndConnection, ONLY: CD_ENDCONN_RIGID USE CableDyn_HermiteTorsion, ONLY: CD_HermiteTorsionType, CD_HermiteTorsion_Line, CD_HermiteTorsion_Unwrap, & - CD_HermiteTorsion_Zeta_Damping, CD_HTORS_OK + CD_HermiteTorsion_Zeta_Damping, CD_HermiteTorsion_Element_Stretch, & + CD_HermiteTorsion_Compliance, CD_HTORS_OK USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCableDynType, CD_HermiteCable_Dyn_Init, & CD_HermiteCable_Dyn_Step, CD_HermiteCable_Dyn_Reaction, & CD_HermiteCable_Dyn_Set_SegmentLength, & @@ -55,6 +60,7 @@ PROGRAM test_control_torsion CD_HermiteCable_Dyn_Set_ForceBlend, CD_HermiteCable_Dyn_End, CD_HCDYN_OK USE CableDyn_OpenFAST_HermiteFMF, ONLY: CD_HFMF_ModuleType, CD_HFMF_Init, CD_HFMF_Set_EndConnection, & CD_HFMF_Set_Torsion, CD_HFMF_UpdateStates, CD_HFMF_Set_SegmentLength, & + CD_HFMF_SetCoupledKinematics, & CD_HFMF_Snapshot, CD_HFMF_Restore, CD_HFMF_MirrorSize, & CD_HFMF_PackMirror, CD_HFMF_UnpackMirror, CD_HFMF_End, CD_HFMF_OK USE CableDyn_OpenFAST_Aggregate, ONLY: CD_AGG_ModuleType, CD_AGG_Init_From_Deck, CD_AGG_GetMovingPointMesh, & @@ -75,7 +81,11 @@ PROGRAM test_control_torsion CALL check_quasi_static('condensed, coupled', KTT, 0.0_wp) CALL check_quasi_static('nodal twist, coupled', KTT, 1.0e-9_wp) CALL check_damping_rate() - CALL check_rate_identity() + CALL check_rate_identity('interior', [5, 6], 0.0_wp) + CALL check_rate_identity('End B rigid', [1, 2], 0.0_wp) + CALL check_rate_identity('fairlead, End A rigid', [NE - 1, NE], 0.0_wp) + CALL check_rate_identity('interior, coupled', [5, 6], 0.5_wp) + CALL check_rate_identity('fairlead, coupled', [NE - 1, NE], 0.5_wp) CALL check_rebuild() CALL check_energy() CALL check_lag() @@ -289,19 +299,27 @@ SUBROUTINE check_damping_rate() END SUBROUTINE check_damping_rate ! ------------------------------------------------------------------------------------------ - SUBROUTINE check_rate_identity() - !! F: a bowed line at rest (transverse DOFs free, nodal twist, Bt = 30 N m2 s, no coupling), - !! elements 5 and 6 at the rate l0_dot = 0.02 m/s: the change of their committed torque is - !! Bt l0_dot d(tau/l0)/dl0 at fixed q, against central differences of the element twist over - !! l0 (+- 1e-5 m), and against the straight-line value -Bt l0_dot tau/l0^2 that leaves out - !! the shape's dependence on l0. - REAL(wp), PARAMETER :: BT = 30.0_wp, RATE = 0.02_wp, DELTA = 1.0e-5_wp - INTEGER, PARAMETER :: EL(2) = [5, 6] - TYPE(CD_HermiteCableDynType) :: m + SUBROUTINE check_rate_identity(label, el, kc) + !! F: a bowed line at rest whose tangent DOFs are neither unit nor along the chord (transverse + !! DOFs free, node 1 and the last node held, nodal twist Irn 0.05 kg m, Bt = 30 N m2 s, rigid + !! torsional ends, coupling K/GJ = kc), the elements el at the rate l0_dot = 0.02 m/s: + !! - the change of their committed torque is Bt l0_dot d(tau/l0)/dl0 at fixed q, against + !! central differences of the element twist (with the coupling term (K/GJ)(l - l0)) over + !! l0 (+- 1e-5 m), and against the straight-line value -Bt l0_dot tau/l0^2; + !! - the element torque's tangent in its 12 DOFs and in its End-2 angle as a step assembles + !! it (the last assembly of a two-iteration step, at the accepted trial iterate, whose q, v, + !! angles and rates the test reads back and checks against the torque the assembly kept), + !! against central differences of the torque at that state (+- 1e-6), and the same + !! differences without the rate, which the check must resolve. + CHARACTER(*), INTENT(IN) :: label + INTEGER, INTENT(IN) :: el(2) + REAL(wp), INTENT(IN) :: kc + REAL(wp), PARAMETER :: BT = 30.0_wp, RATE = 0.02_wp, DELTA = 1.0e-5_wp, HQ = 1.0e-6_wp + TYPE(CD_HermiteCableDynType) :: m, base, pert, at, at0 TYPE(CD_HermiteTorsionType) :: tors REAL(wp) :: l0(NE), q(NDOF), s, g(NDOF), raw, tw0(NE), twp(NE), twm(NE), mt0(NE), mt1(NE) - REAL(wp) :: fd(2), share(2), shape(2), err - INTEGER :: i, k, es + REAL(wp) :: fd(2), share(2), shape(2), err, dq(13), dfd(13), dfd0(13), terr, tres, mp, mm, mt_at, state_err + INTEGER :: i, k, j, es CHARACTER(300) :: em l0 = 1.0_wp q = 0.0_wp @@ -310,13 +328,13 @@ SUBROUTINE check_rate_identity() q(6*i - 5) = s q(6*i - 4) = 0.8_wp*SIN(PI*s/LS)**2 q(6*i - 3) = 0.4_wp*SIN(2.0_wp*PI*s/LS)**2 - q(6*i - 2) = 1.0_wp - q(6*i - 1) = 0.8_wp*(PI/LS)*SIN(2.0_wp*PI*s/LS) - q(6*i) = 0.4_wp*(2.0_wp*PI/LS)*SIN(4.0_wp*PI*s/LS) + q(6*i - 2) = 1.0_wp + 0.05_wp*s + q(6*i - 1) = 0.8_wp*(PI/LS)*SIN(2.0_wp*PI*s/LS) + 0.1_wp + q(6*i) = 0.4_wp*(2.0_wp*PI/LS)*SIN(4.0_wp*PI*s/LS) - 0.07_wp END DO CALL CD_HermiteCable_Dyn_Init(m, l0, [(EA, k=1, NE)], [(EI, k=1, NE)], [(1.0_wp, k=1, NE)], [(0.0_wp, k=1, NE)], & q, [1, 2, 3, NDOF - 5, NDOF - 4, NDOF - 3], -1.0e3_wp, 0.0_wp, 0.0_wp, es, em) - CALL require(es == CD_HCDYN_OK, 'F: init: '//TRIM(em)) + CALL require(es == CD_HCDYN_OK, 'F '//label//': init: '//TRIM(em)) IF (es /= CD_HCDYN_OK) RETURN tors%active = .TRUE. tors%phi = 1.0_wp @@ -324,45 +342,130 @@ SUBROUTINE check_rate_identity() 0.0_wp, 0.0_wp, 1.0_wp], [3, 4]) tors%end_compliance = 0.0_wp tors%gj = [(GJ, k=1, NE)] + IF (kc > 0.0_wp) tors%couple = [(kc, k=1, NE)] tors%irn = [(0.05_wp, k=1, NE)] tors%bt = [(BT, k=1, NE)] - CALL CD_HermiteTorsion_Line(q, l0, tors%ends, raw, g, es, em) + CALL CD_HermiteTorsion_Line(q, l0, tors%ends, raw, g, es, em, couple=tors%couple) tors%theta = CD_HermiteTorsion_Unwrap(raw, 0.0_wp) tors%has_theta = .TRUE. CALL CD_HermiteCable_Dyn_Set_Torsion(m, tors, es, em) - CALL require(es == CD_HCDYN_OK .AND. m%tw_active, 'F: nodal twist on the bowed line: '//TRIM(em)) + CALL require(es == CD_HCDYN_OK .AND. m%tw_active, 'F '//label//': nodal twist on the bowed line: '//TRIM(em)) IF (es /= CD_HCDYN_OK) RETURN - CALL CD_HermiteCable_Dyn_Element_Twist(m, tw0, es, em) + CALL coupled_twist(m, kc, tw0) CALL CD_HermiteCable_Dyn_Element_Torque(m, mt0, es, em) ! the element twist at l0 +- DELTA (the committed angles and q kept) - CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL) + DELTA, [0.0_wp, 0.0_wp], es, em) - CALL CD_HermiteCable_Dyn_Element_Twist(m, twp, es, em) - CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL) - DELTA, [0.0_wp, 0.0_wp], es, em) - CALL CD_HermiteCable_Dyn_Element_Twist(m, twm, es, em) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, el, l0(el) + DELTA, [0.0_wp, 0.0_wp], es, em) + CALL coupled_twist(m, kc, twp) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, el, l0(el) - DELTA, [0.0_wp, 0.0_wp], es, em) + CALL coupled_twist(m, kc, twm) ! the rate at the base lengths, committed, and the torque of that committed state - CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, EL, l0(EL), [RATE, RATE], es, em, restored=.TRUE.) - CALL require(es == CD_HCDYN_OK, 'F: the committed rate: '//TRIM(em)) + CALL CD_HermiteCable_Dyn_Set_SegmentLength(m, el, l0(el), [RATE, RATE], es, em, restored=.TRUE.) + CALL require(es == CD_HCDYN_OK, 'F '//label//': the committed rate: '//TRIM(em)) CALL CD_HermiteCable_Dyn_Recompute_Acceleration(m, es, em) - CALL require(es == CD_HCDYN_OK, 'F: the committed state with the rate: '//TRIM(em)) + CALL require(es == CD_HCDYN_OK, 'F '//label//': the committed state with the rate: '//TRIM(em)) CALL CD_HermiteCable_Dyn_Element_Torque(m, mt1, es, em) err = 0.0_wp DO k = 1, 2 - i = EL(k) + i = el(k) fd(k) = BT*RATE*(twp(i)/(l0(i) + DELTA) - twm(i)/(l0(i) - DELTA))/(2.0_wp*DELTA) shape(k) = -BT*RATE*tw0(i)/l0(i)**2 share(k) = mt1(i) - mt0(i) err = MAX(err, ABS(share(k) - fd(k))/ABS(fd(k))) END DO - WRITE (*, '(A,2ES13.5,A,2ES13.5,A,2ES13.5,A,ES9.2)') 'F length-rate damping torque ', share, & - '; by differences ', fd, '; straight-line value ', shape, '; rel. error ', err - CALL require(err <= 1.0e-6_wp, 'F: the length-rate damping is Bt l0_dot d(tau/l0)/dl0 at fixed q') + ! the tangent of the last assembly of a step (full Newton: the accepted trial of its first + ! iteration) at the state of that assembly, read back from the step's staged iterate + base = m + CALL CD_HermiteCable_Dyn_Step(m, 1.0e-4_wp, 2, 1.0e-14_wp, es, em) + at = base + at%q = m%ws_qa + at%v = m%ws_va + at%tw_phi = m%tw_pe + at%tw_w = m%tw_we + at0 = at + at0%l0_dot = 0.0_wp + at0%l0_dot_c = 0.0_wp + terr = 0.0_wp + tres = 0.0_wp + state_err = 0.0_wp + DO k = 1, 2 + i = el(k) + dq(1:12) = m%tw_ek(i)*m%tw_eg(:, i) + m%tw_ed(i)*m%tw_ehv(:, i) + dq(13) = m%tw_ek(i) + pert = at + CALL perturbed_torque(pert, i, 1, 0.0_wp, mt_at) + state_err = MAX(state_err, ABS(mt_at - m%tw_me(i))/ABS(m%tw_me(i))) + DO j = 1, 13 + pert = at + CALL perturbed_torque(pert, i, j, HQ, mp) + pert = at + CALL perturbed_torque(pert, i, j, -HQ, mm) + dfd(j) = (mp - mm)/(2.0_wp*HQ) + pert = at0 + CALL perturbed_torque(pert, i, j, HQ, mp) + pert = at0 + CALL perturbed_torque(pert, i, j, -HQ, mm) + dfd0(j) = (mp - mm)/(2.0_wp*HQ) + END DO + terr = MAX(terr, MAXVAL(ABS(dq - dfd))/MAXVAL(ABS(dfd))) + tres = MAX(tres, MAXVAL(ABS(dfd - dfd0))/MAXVAL(ABS(dfd))) + END DO + WRITE (*, '(A,A,A,2ES13.5,A,2ES13.5,A,2ES13.5,A,ES9.2,A,ES9.2,A,ES9.2,A,ES9.2)') 'F length-rate damping (', & + label, '): torque ', share, '; by differences ', fd, '; straight-line value ', shape, '; rel. error ', err, & + '; tangent against differences ', terr, ', its length-rate share ', tres, ' (state read back to ', & + state_err, ')' + CALL require(err <= 1.0e-6_wp, 'F '//label//': the length-rate damping is Bt l0_dot d(tau/l0)/dl0 at fixed q') CALL require(MAXVAL(ABS(shape - fd)) > 1.0e3_wp*err*MAXVAL(ABS(fd)), & - 'F: the element shape''s dependence on l0 is resolved by the check') - CALL require(same_bits(mt1(1:4), mt0(1:4)) .AND. same_bits(mt1(7:NE), mt0(7:NE)), & - 'F: elements without a rate keep their torque') + 'F '//label//': the element shape''s dependence on l0 is resolved by the check') + CALL require(state_err <= 1.0e-12_wp, 'F '//label//': the state of the step''s last assembly is read back') + CALL require(terr <= 1.0e-6_wp, 'F '//label//': the assembled torque tangent matches central differences') + CALL require(tres > 1.0e2_wp*terr, 'F '//label//': the tangent check resolves the length-rate share') + DO k = 1, NE + IF (ANY(el == k)) CYCLE + CALL require(same_bits(mt1(k:k), mt0(k:k)), 'F '//label//': elements without a rate keep their torque') + END DO CALL CD_HermiteCable_Dyn_End(m) + CALL CD_HermiteCable_Dyn_End(base) + CALL CD_HermiteCable_Dyn_End(pert) + CALL CD_HermiteCable_Dyn_End(at) + CALL CD_HermiteCable_Dyn_End(at0) END SUBROUTINE check_rate_identity + SUBROUTINE coupled_twist(m, kc, tw) + !! The element twists tau_e of the nodal twist: the material twist (the query) plus the + !! coupling term (K/GJ)(l_e - l0_e) of the stretched element length. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: m + REAL(wp), INTENT(IN) :: kc + REAL(wp), INTENT(OUT) :: tw(NE) + INTEGER :: e, es + CHARACTER(300) :: em + CALL CD_HermiteCable_Dyn_Element_Twist(m, tw, es, em) + IF (.NOT. kc > 0.0_wp) RETURN + DO e = 1, NE + tw(e) = tw(e) + kc*(CD_HermiteTorsion_Element_Stretch(m%q(6*e - 5:6*e + 6), m%l0(e), 4) - m%l0(e)) + END DO + END SUBROUTINE coupled_twist + + SUBROUTINE perturbed_torque(m, e, j, h, mt) + !! The committed torque of element e with its DOF j (1-12: [r1, m1, r2, m2]; 13: the End-2 + !! angle) moved by h, from a re-derived committed state. + TYPE(CD_HermiteCableDynType), INTENT(INOUT) :: m + INTEGER, INTENT(IN) :: e, j + REAL(wp), INTENT(IN) :: h + REAL(wp), INTENT(OUT) :: mt + REAL(wp) :: tq(NE) + INTEGER :: es + CHARACTER(300) :: em + IF (j <= 12) THEN + m%q(6*e - 6 + j) = m%q(6*e - 6 + j) + h + ELSE + m%tw_phi(e + 1) = m%tw_phi(e + 1) + h + END IF + CALL CD_HermiteCable_Dyn_Recompute_Acceleration(m, es, em) + CALL CD_HermiteCable_Dyn_Element_Torque(m, tq, es, em) + mt = tq(e) + IF (es /= CD_HCDYN_OK) mt = HUGE(1.0_wp) + END SUBROUTINE perturbed_torque + ! ------------------------------------------------------------------------------------------ SUBROUTINE check_rebuild() !! Z: Irn 0.5 kg m, K, a -zeta damping (zeta 0.1) on every element but element 3, which takes @@ -744,6 +847,48 @@ SUBROUTINE check_restart() same_bits(cab2%line%tw_mt, mref), 'R: the run rebuilt from the mirror continues bit-identically') WRITE (*, '(A,F9.5,A,F9.5,A)') 'R restart mid-ramp: span ', SUM(cab%line%l0(19:20)), ' m, end twist angle ', & pref(SIZE(pref)), ' rad; snapshot and mirror runs identical' + ! a non-stepping write of the coupled end at step 250 turned 0.05 rad further: the committed + ! torque is then the summed twist over the compliance, which the snapshot and the mirror + ! must bring back as it is + BLOCK + TYPE(CD_HFMF_ModuleType), ALLOCATABLE :: cab3 + REAL(wp) :: t, x(3), v(3), a(3), dcm(3, 3), tq_keep, tq_formula + LOGICAL :: ok2 + ALLOCATE (cab3) + t = 2.5_wp + x = [LS, 0.05_wp*SIN(2.0_wp*t), 0.0_wp] + v = [0.0_wp, 0.1_wp*COS(2.0_wp*t), 0.0_wp] + a = [0.0_wp, -0.2_wp*SIN(2.0_wp*t), 0.0_wp] + dcm = 0.0_wp + dcm(1, 1) = 1.0_wp + dcm(2, 2) = COS(2.0_wp*t + 0.05_wp) + dcm(3, 3) = COS(2.0_wp*t + 0.05_wp) + dcm(2, 3) = SIN(2.0_wp*t + 0.05_wp) + dcm(3, 2) = -SIN(2.0_wp*t + 0.05_wp) + CALL CD_HFMF_SetCoupledKinematics(cab, x, v, a, es, em, u_orientation=dcm, & + u_angular_velocity=[2.0_wp, 0.0_wp, 0.0_wp], & + u_angular_acceleration=[0.0_wp, 0.0_wp, 0.0_wp]) + CALL require(es == CD_HFMF_OK, 'R: the non-stepping frame write: '//TRIM(em)) + tq_keep = cab%line%torsion%torque + tq_formula = (cab%line%torsion%phi - cab%line%torsion%theta)/ & + CD_HermiteTorsion_Compliance(cab%line%torsion, cab%line%l0) + CALL CD_HFMF_PackMirror(cab, mirror, es, em) + CALL CD_HFMF_Snapshot(cab, es, em) + CALL coupled_march(cab, 250, 251, ok2) + CALL CD_HFMF_Restore(cab, es, em) + CALL require(es == CD_HFMF_OK .AND. ok2 .AND. same_bits([cab%line%torsion%torque], [tq_keep]), & + 'R: the snapshot brings back the committed torque of a frame write as it was formed') + CALL build_coupled(cab3, es, em) + CALL coupled_command(cab3, 250, es, em, restored=.TRUE.) + CALL CD_HFMF_UnpackMirror(cab3, mirror, t, es, em) + CALL require(es == CD_HFMF_OK .AND. same_bits([cab3%line%torsion%torque], [tq_keep]), & + 'R: the mirror brings back the committed torque of a frame write as it was formed') + WRITE (*, '(A,ES24.16,A,ES10.3)') 'R committed torque after a frame write ', tq_keep, & + ' N m; re-derived as (Phi - Theta)/C it would differ by ', tq_formula - tq_keep + CALL require(.NOT. same_bits([tq_formula], [tq_keep]), & + 'R: the frame write''s torque differs from (Phi - Theta)/C, so the check resolves it') + CALL CD_HFMF_End(cab3) + END BLOCK CALL CD_HFMF_End(cab) CALL CD_HFMF_End(cab2) END SUBROUTINE check_restart From fedb59774c2e6d0e79c554f77c8cf9999afd6056 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 15:54:47 +0900 Subject: [PATCH 5/7] feat(modal): modal analysis of lines restrained in torsion, with the nodal twist OPTION nModes now runs on finite-EI lines restrained in torsion. The dynamics of such a line carry a twist angle at every node (a deck's explicit GJ comes with the polar inertia Irn), so its modes do too. - CD_Modal_Hermite_Line and CD_Modal_Hermite_Line_Band assemble a line model's modal stiffness and mass on the DOFs its dynamics solves: [r, m, phi] per node (half-bandwidth 13) on a line with twist, the lumped polar inertia as the angles' mass and the second variation of the twist energy sum 1/2 (GJ/l0)(phi_{e+1} - phi_e + rho_e(q))^2 at the static torque (CD_HermiteCable_Dyn_Twist_Hessian): M_e d2rho/dq2 + (GJ/l0) g g^T on the cable, +-(GJ/l0) g against the angles, and the elastic end springs. Eliminating the angles gives back the condensed static tangent; its rank-one term is the Schur complement of the angle block. A model with the condensed torsion of no polar inertia is refused by name (no deck builds one). - The finite-EI modal route now takes the end connections (a finite spring's Hessian; a rigid end's tangent in its basis with the two transverse components held) and the attachments' masses from the model, which it ignored, and writes the positions of a line with a heading in the deck's axes. Decks without them keep their modes table byte for byte. - .modes.out adds PolarShare (the polar share of each mode's kinetic energy) and dTwist (the section rotation about the End A -> End B tangent) when a line carries twist; a torsional mode is scaled to a unit largest twist. Gates: test_modal_torsion on a 10 m clamped line: torsional modes against n pi/L sqrt(GJ/Irn) within the lumped chain's own error (2.6e-4, 1.0e-3) and the chain to 1e-16, bending and axial modes equal to the line without torsion; elastic torsional ends against the continuum (1.5e-4); torque-tension coupled axial-torsional modes (<= 8.6e-4); lateral modes under M = 4 EI/L against the clamped Greenhill-cable determinant to 3.2e-7 (-5.5 % on the first); on a bowed twisted line the Schur complement of the angles equals the condensed static tangent to 1.4e-16 and the central differences of the condensed static residual to 7.6e-10; finite end springs put the first lateral frequency between pinned and clamped (3.6e-5 from the clamp at k = 1e5 EI/L). test_modal_torsion_deck.py runs the same straight line through the driver against TorsStiffness Free and turned 30 degrees, and the lazy wave twisted two turns; on the old driver both fail with the refusal. The old modal route without the twist finds no torsional mode and puts the clamped line's first lateral frequency 41 % low. Changed results: the modes of finite-EI decks with END CONNECTIONS or ATTACHMENTS and nModes (none shipped): a clamped lazy wave's first twelve frequencies rise by 0.1 to 3.8 %, those of lazy_wave_buoyancy_modules.dat with nModes drop by 13 to 29 %. Signed-off-by: Jae Hoon Seo --- ARCHITECTURE.md | 6 +- CHANGELOG.md | 14 + CMakeLists.txt | 24 + VALIDATION.md | 26 +- doc/capabilities.rst | 11 +- doc/driver_format.md | 4 +- doc/options.rst | 6 +- doc/outputs.rst | 12 + doc/theory.rst | 30 + doc/troubleshooting.rst | 5 +- python/cabledyn/deck_file.py | 16 +- python/tests/test_deck_native_parity.py | 4 +- src/CableDyn_DeckDriver.f90 | 113 ++-- src/CableDyn_HermiteCableDynamic.f90 | 64 +- src/CableDyn_Modal.f90 | 344 +++++++++- tests/data/torsion_lazy_wave_modes.dat | 46 ++ tests/test_modal_torsion.f90 | 804 ++++++++++++++++++++++++ tests/test_modal_torsion_deck.py | 218 +++++++ tests/test_torsion_deck.f90 | 18 +- 19 files changed, 1673 insertions(+), 92 deletions(-) create mode 100644 tests/data/torsion_lazy_wave_modes.dat create mode 100644 tests/test_modal_torsion.f90 create mode 100644 tests/test_modal_torsion_deck.py diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c1acf3b6..4493aa34 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -325,7 +325,11 @@ consistent mass plus Morison added mass. `K` and `M` are assembled in symmetric band storage; LAPACK `DSBGVX` gives the eigenvalues and inverse iteration on the banded pencil gives each mode shape, so the cost grows with line length rather than with its square. Dense `DSYGV` is kept as the test reference. Both line paths -are supported (`nModes`). +are supported (`nModes`). A finite-EI line's modes (`CD_Modal_Hermite_Line`) take +its end connections and attachments from the dynamic model, and a line restrained +in torsion adds the twist angle of every node: its lumped polar inertia and the +second variation of the nodal-twist energy (`CD_HermiteCable_Dyn_Twist_Hessian`) +in a band of 7 DOFs per node. ### Outputs diff --git a/CHANGELOG.md b/CHANGELOG.md index ac9ee836..9001b2f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -104,6 +104,14 @@ All notable changes to CableDyn are recorded in this file. The format follows balances the energy to 8e-5 of the work done; restarts mid-ramp (snapshot, checkpoint mirror, a coupled deck) are bit-identical. The checkpoint mirror of a line with the nodal twist gains one value, its committed torque. +- Modal analysis (`nModes`) of finite-EI lines restrained in torsion: the modes carry the twist + angle of every node, as the dynamics do, with the lumped polar inertia and the second variation + of the twist energy at the static torque. A clamped straight line's torsional modes match + `nπ/L √(GJ/Irn)` within the lumped chain's own error (2.6e-4 on the first), elastic ends and + the torque–tension coupling their continuum solutions to 1e-3, and under a torque its lateral + modes match the clamped Greenhill cable to 3e-7; eliminating the angles reproduces the + condensed static tangent to 1e-16. `.modes.out` adds `PolarShare` and `dTwist` when a + line carries twist. - Torque–tension coupling of finite-EI cables: the 14-column LINE TYPES row's `GJ` column takes `GJ|K`, with `K` the coupling of an armoured cable or wire rope (`T = EA ε + K τ`, `M = GJ τ + K ε`). The cable carries the axial stiffness `EA − K²/GJ` of a section free to twist. @@ -251,6 +259,12 @@ All notable changes to CableDyn are recorded in this file. The format follows The static tangent takes the current's gradient along the line, so the Newton iteration also converges in a current sheared across the line. A later `current` row now discards the levels of an earlier profile row. +- The modal analysis of finite-EI lines ignored the end connections and the discrete + attachments: a clamped end was solved pinned (the first twelve frequencies of the lazy wave + of `torsion_lazy_wave_hangoff_twist.dat`, untwisted, rise by 0.1 % to 3.8 % with its clamps) + and buoyancy modules had no mass (with `nModes`, the first six frequencies of + `lazy_wave_buoyancy_modules.dat` drop by 13 % to 29 %). The positions and translations of a + line with a heading are written in the deck's axes, not the line's. - A deck with a WaterKin elevation history (`WaveKinMod 1`) at `TMax = 0`, a check of the static start, reduces the record over its own length instead of failing for want of a positive `TMax`. diff --git a/CMakeLists.txt b/CMakeLists.txt index 50fba05f..da62485d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2014,6 +2014,13 @@ add_executable(test_modal tests/test_modal.f90 tests/blas_config_probe.c) target_link_libraries(test_modal PRIVATE cabledyn_core) add_test(NAME modal COMMAND test_modal) set_tests_properties(modal PROPERTIES LABELS "fortran;unit;driver;static;validation") +# Modal analysis of a line restrained in torsion: the twist angle of every node joins the modes +# (torsional, elastic-end and torque-tension coupled modes, the lateral modes under a torque, the +# Schur complement of the angles against the condensed static tangent). +add_executable(test_modal_torsion tests/test_modal_torsion.f90) +target_link_libraries(test_modal_torsion PRIVATE cabledyn_core) +add_test(NAME modal_torsion COMMAND test_modal_torsion) +set_tests_properties(modal_torsion PROPERTIES LABELS "fortran;unit;static;validation") # The modal eigensolves through CableDyn's LAPACK layer with every argument array against a # no-access page: no read or write outside the arrays the modal code passes. if(NOT CABLEDYN_STATIC_WINDOWS_RELEASE) @@ -2402,6 +2409,13 @@ add_test(NAME driver_cli_mixed_nmodes "-DMUST_MATCH=nModes is not supported for mixed EI=0/finite-EI decks" -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake) set_tests_properties(driver_cli_mixed_nmodes PROPERTIES LABELS "fortran;driver;cli") +# A lazy wave restrained in torsion and twisted two turns writes its modes with the twist. +add_test(NAME driver_cli_torsion_nmodes + COMMAND ${CMAKE_COMMAND} -DDRIVER=$ -DEXPECT_RC=0 + "-DARGS=${CMAKE_CURRENT_SOURCE_DIR}/tests/data/torsion_lazy_wave_modes.dat|${CMAKE_CURRENT_BINARY_DIR}/driver_cli_torsion_nmodes" + "-DMUST_MATCH=torsion solved, imposed twist 7.20000E\\+02 deg;converged run written" + -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/check_driver_output.cmake) +set_tests_properties(driver_cli_torsion_nmodes PROPERTIES LABELS "fortran;driver;cli") # Non-ASCII, reserved-device, input-clobbering, and concurrently used output paths. add_test( NAME driver_cli_paths @@ -2741,6 +2755,16 @@ if(Python3_Interpreter_FOUND) --output ${CMAKE_CURRENT_BINARY_DIR}/lozon_example_equilibrium) set_tests_properties(lozon_example_equilibrium PROPERTIES LABELS "python;driver;integration;example;lozon;validation") + # Modal analysis of decks restrained in torsion: the torsional modes of a straight clamped + # line against the chain and the continuum, its other modes against TorsStiffness Free, and + # the twisted lazy wave's modes. + add_test( + NAME modal_torsion_deck + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_modal_torsion_deck.py + --exe $ + --source ${CMAKE_CURRENT_SOURCE_DIR} + --output ${CMAKE_CURRENT_BINARY_DIR}/modal_torsion_deck) + set_tests_properties(modal_torsion_deck PROPERTIES LABELS "python;driver;integration;validation") # Static-initialization robustness matrix: a deterministic sample of EI=0 mooring regimes # (catenary, semi-taut, taut, suspended, composite, slack/vertical, anchors off the seabed, # sloped seabed, fine mesh, soft seabed, current, one/two segments, Free/Connect points) diff --git a/VALIDATION.md b/VALIDATION.md index 52c73878..1ce8ef0c 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -1077,11 +1077,35 @@ in parentheses). to 6e-11) continue bit-identically; after a non-stepping frame write the snapshot and the checkpoint mirror bring back the committed torque bit for bit (re-derived as `(Φ − Θ)/C` it would differ by 1.8e-15 N·m). +- **T-15 modal analysis with torsion** (`modal_torsion`, `modal_torsion_deck`, + `driver_cli_torsion_nmodes`). The modes carry the twist angle of every node. On the 10 m line + (EI 100 N·m², GJ 80 N·m², EA 1e4 N, T 10 N, 40 elements), clamped: + - rigid torsional ends, `Irn = 0.04 kg·m`: the torsional modes are the lumped chain's to 1e-16 + and `nπ/L √(GJ/Irn)` within the chain's own `1 − sin(x)/x` (2.6e-4, 1.0e-3); the bending and + axial modes equal those of the line without torsion bit for bit, with no twist; + - elastic torsional ends `k = 2 GJ/L`: the continuum's `tan(βL) = 2kGJβ/((GJβ)² − k²)` to + 1.5e-4, the lumped chain to 4e-14; + - torque–tension coupling `K = 300 N·m`: the coupled axial–torsional modes + `ω² = (nπ/L)² eig([[EA, K], [K, GJ]], diag(m, Irn))` within the chain's error (≤ 8.6e-4); + - under a torque `M = 4 EI/L` with a negligible `Irn = 1e-6 kg·m` (100 elements), the four + lowest lateral pairs match the clamped Greenhill-cable determinant + (`EI u'''' − i M u''' − T u'' = m ω² u`) to 3.2e-7, 5.5 % to 1.2 % below the untwisted ones. + + On a bowed, twisted 12-element line (pinned and clamped bending ends, rigid and elastic + torsional ends, coupling) the Schur complement of the angles equals the condensed static + tangent to 1.4e-16 and the central differences of the condensed static residual to 7.6e-10. + The modal route without the twist finds no torsional mode, misses the torque (4e-4 to 4e-3 + of the tangent) and, ignoring the end connections, puts the clamped line's first lateral + frequency 41 % low; finite bending springs at both ends now put it between the pinned and + the clamped line's, within 3.6e-5 of the clamp at `k = 1e5 EI/L`. In the deck the same + straight line's torsional modes and its bending and axial modes against `TorsStiffness Free` + hold to the table's nine digits, turned 30° about +z it keeps its frequencies and writes its + positions in the deck's axes, and the lazy wave twisted two turns writes its modes. - **Backward compatibility and refusals** (`torsion_deck`, full suite). Without torsion columns, with `Free` columns (whatever their normal), or with one restrained end, every output is byte-identical to the 6-column deck, and `Rigid`, `Infinity`, `Inf` and a quoted `"Rigid"` give the same run. Malformed rows, a missing `GJ`, an `EI = 0` line, a rod end, a `Point3` body, - `ATTACHMENTS`, modal analysis, the configuration blend (also on the coupled entries), misuse of + `ATTACHMENTS`, the configuration blend (also on the coupled entries), misuse of the roll column, channels on an unrestrained line, a coupled caller that passes no orientation (the C API) and a standalone mixed `EI = 0` + finite-EI deck without a body stop with named errors. diff --git a/doc/capabilities.rst b/doc/capabilities.rst index 49b453e5..a1ba6767 100644 --- a/doc/capabilities.rst +++ b/doc/capabilities.rst @@ -99,9 +99,9 @@ Line and constitutive capability (``CONTROL``) of the fairlead segment on the coupled route; ``Torq``/``Twist`` channels and standalone range graphs. Stopped by name: the standalone mixed ``EI = 0`` + finite-EI aggregate and ``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by - translation only), rod ends, bodies other than Rigid6, modal analysis, and - ``False alpha_force_blend``. Not modelled: seabed friction against twist, anisotropic - sections, self-contact of a loop (see :ref:`theory-torsion`) + translation only), rod ends, bodies other than Rigid6 and ``False alpha_force_blend``. + Modal analysis carries the twist angle of every node. Not modelled: seabed friction + against twist, anisotropic sections, self-contact of a loop (see :ref:`theory-torsion`) * - Hockling loops, nonlinear cross-section laws - Not provided - the buckling onset and the post-buckled shape are computed, but a loop that closes on @@ -121,8 +121,9 @@ Line and constitutive capability * - Modal analysis (``nModes``) - Standalone only - natural frequencies and mode shapes of each line about its static equilibrium (all - ``EI = 0`` lines, or all finite-EI lines on the Hermite route; flat seabed); a deck with - torsion is rejected + ``EI = 0`` lines, or all finite-EI lines on the Hermite route with their end connections + and attachments; flat seabed); a line restrained in torsion adds the twist angle of every + node, so its torsional modes and the torque's effect on the others appear * - Cross-flow VIV (LINE TYPES ``Cl``, ``dF``, ``cF``) - Standalone and coupled - MoorDyn v2's synchronisation model on ``EI = 0`` lines and, as a distributed lift, on diff --git a/doc/driver_format.md b/doc/driver_format.md index 84306960..22872dd0 100644 --- a/doc/driver_format.md +++ b/doc/driver_format.md @@ -877,7 +877,7 @@ Scope. A torsionally restrained line needs a finite-EI line with a `Fixed` End B `Body` point; in a coupled OpenFAST or FAST.Farm run the End A frame turns with the platform (see the manual's OpenFAST page, Line torsion). Each of the following stops with a named error: torsion on an `EI = 0` line, on a rod end or on a `Point3` body, -modal analysis (`nModes`), a dynamic or coupled run with `False alpha_force_blend`, any +a dynamic or coupled run with `False alpha_force_blend`, any restrained end (one end included) in a standalone deck mixing `EI = 0` and finite-EI lines without a body or through the C API's `CableDyn_InitDeck`/`InitDeckAt`, which move the line ends by translation only (`a line restrained in torsion needs a host that turns its fairlead @@ -1205,7 +1205,7 @@ syntax form. The most frequently edited keywords are: | `WaveDirections` | direction bins of a spread train | 9 | | `WaveComponents` | frequency components per train and direction (at least 2) | 200 | | `StreamOrder` | Fourier terms of a `stream` wave: 0 (default, 20) or 2 to 60 | 0 | -| `nModes` | modal analysis: the N lowest natural frequencies and mode shapes of every line about its static equilibrium, written to `.modes.out` (EI = 0 decks, or finite-EI decks on the Hermite route; flat seabed; 0 = off) | 0 | +| `nModes` | modal analysis: the N lowest natural frequencies and mode shapes of every line about its static equilibrium, written to `.modes.out` (EI = 0 decks, or finite-EI decks on the Hermite route, where a line restrained in torsion adds the twist angle of every node; flat seabed; 0 = off) | 0 | | `WaveSeed` | integer from 1 to 2147483646; seed of the random spectral sea (the same seed gives the same sea on every platform; train *i* uses seed + 7919 (*i* − 1)) | 1 | | `rampTime` | half-cosine start-up ramp of the wave amplitudes [s]; the current is not ramped. `0` disables it | 0 | | `motionFile` | path to a prescribed-motion time series for `Coupled`/`Vessel` points, rod end rows, and prescribed Rigid6 `Body` points; `0` or `none` disables it | — | diff --git a/doc/options.rst b/doc/options.rst index 90482631..63fe7acf 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -614,9 +614,9 @@ Ambient fluid and prescribed motion dynamic deck), or all finite-EI lines on the cubic-Hermite route (dynamic deck, every End B Fixed). Other decks are rejected; a deck that mixes ``EI = 0`` and finite-EI lines stops with ``OPTION nModes is not supported for mixed EI=0/finite-EI decks; - remove it or set it to 0``; a deck with a torsional line stops with ``modal analysis - (OPTION nModes) of a line with torsion is not yet supported``. The banded solver has no - line-length limit: a + remove it or set it to 0``. A line restrained in torsion adds the twist angle of every + node to its modes (``PolarShare`` and ``dTwist`` in :doc:`outputs`). The banded solver has + no line-length limit: a 1024-element finite-EI cable takes a few seconds. See :doc:`theory` - standalone - ``10 nModes`` diff --git a/doc/outputs.rst b/doc/outputs.rst index c52645e9..6b0abc03 100644 --- a/doc/outputs.rst +++ b/doc/outputs.rst @@ -456,6 +456,18 @@ row: scaled so that the largest nodal displacement of the mode is 1. Nodes are numbered End A first, as in the other line files; the held end nodes have zero displacement. +When a line is restrained in torsion (both ends, see :doc:`driver_format`), its modes carry the +twist angle of every node (:ref:`nodal twist `) and both tables gain a +column, for every line of the file (``0`` on a line without torsion): + +* ``PolarShare`` (frequency table): the polar share of the mode's kinetic energy, + :math:`\sum_k I_k \varphi_k^2` of the mass-normalised mode with :math:`I_k` the lumped polar + inertia, 1 for a pure torsional mode and 0 for one without twist; +* ``dTwist`` [rad] (shape table): the rotation of the node's section about the line tangent, + positive right-handed about the direction from End A to End B, on the scale of the + translations; a torsional mode (``PolarShare`` above 0.5) is scaled to a unit largest + ``dTwist`` instead. + Per-rod files (``RODS`` ``Outputs`` flag) ----------------------------------------- diff --git a/doc/theory.rst b/doc/theory.rst index 0f4f5c75..408e3705 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -1829,6 +1829,36 @@ tension :math:`H`, and the symmetric in-plane modes satisfy with :math:`\lambda^2 = (wL/H)^2\,L/(H L_e/EA)` (:ref:`Irvine & Caughey, 1974 `); the modal analysis reproduces both. +A finite-EI line's modes carry what its dynamics carries: an end connection's spring adds its +Hessian on the end tangent, a rigid end keeps only the magnitude of its tangent (the two +transverse components of its basis are held), and discrete attachments add their dry and added +masses. A line restrained in torsion carries the :ref:`nodal twist ` in its +dynamics, so its modes do too: the twist angle :math:`\varphi_k` of every node joins the +degrees of freedom, :math:`[\mathbf r, \mathbf m, \varphi]` per node (half-bandwidth 13), with +the lumped polar inertia :math:`I_k` as its mass and the second variation of the twist energy +:math:`E_t = \sum_e \tfrac12 (GJ_e/L_{0,e})\,\hat\tau_e^2` (and of the elastic end springs) as +its stiffness, at the static torque :math:`M_e`: + +.. math:: + + \frac{\partial^2 E_t}{\partial\mathbf q^2} = M_e\,\frac{\partial^2 m_e}{\partial\mathbf q^2} + + \frac{GJ_e}{L_{0,e}}\,\mathbf g_e\mathbf g_e^{\mathsf T}, \qquad + \frac{\partial^2 E_t}{\partial\varphi_{k+1}\,\partial\mathbf q} + = -\frac{\partial^2 E_t}{\partial\varphi_k\,\partial\mathbf q} = \frac{GJ_e}{L_{0,e}}\,\mathbf g_e, + \qquad \mathbf g_e = \frac{\partial\hat\tau_e}{\partial\mathbf q} . + +The torque term lowers the bending frequencies of a twisted line, as on Greenhill's twisted +shaft; :math:`\mathbf g_e` couples the twist to the bending of a curved line and, under +torque–tension coupling, to the stretch. Eliminating the angles (no polar inertia) leaves the +condensed tangent of the statics, :math:`-M_t\,\partial^2\Theta/\partial\mathbf q^2 + +\nabla\Theta\,\nabla\Theta^{\mathsf T}/C`: the Schur complement of the angle block is the +rank-one term the statics carry in a bordered solve, which a band cannot hold. Damping (also +:math:`B_t`) is left out. The test suite checks the torsional modes of a clamped straight line +against :math:`\omega_n = (n\pi/L)\sqrt{GJ/I_{rn}}` and its lumped chain, elastic torsional +ends, the coupled axial–torsional modes of :math:`K`, the lateral modes of a taut line under a +torque against the clamped Greenhill-cable determinant, and the Schur complement against the +condensed static tangent (see :doc:`validation`). + Time integration ---------------- diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 96a201fc..b69874b5 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -411,9 +411,8 @@ Torsion after 6 step halvings`` - the body turns faster than one step can follow the twist; reduce ``dtM``. * - ``torsion in a dynamic run needs the force-blended generalised-alpha (OPTION - alpha_force_blend True)`` / ``modal analysis (OPTION nModes) of a line with torsion is not - yet supported`` - - remove ``False alpha_force_blend`` or ``nModes`` from a deck with torsion. + alpha_force_blend True)`` + - remove ``False alpha_force_blend`` from a deck with torsion. * - ``OUTPUT "Torq...": line is not torsionally restrained at both ends ..., so it carries no torque`` - a ``Torq``/``Twist`` channel needs a line with a torsional restraint at both ends. diff --git a/python/cabledyn/deck_file.py b/python/cabledyn/deck_file.py index 474539f4..631d1f33 100644 --- a/python/cabledyn/deck_file.py +++ b/python/cabledyn/deck_file.py @@ -4294,11 +4294,11 @@ def _check_torsion_lines( solved as without the columns. Restrained at both ends, torsion is solved: End B must be Fixed, every section type needs an explicit GJ > 0, no ATTACHMENTS, End A neither a rod end nor on a body other than Rigid6. A deck with torsion runs dynamics only with - the force-blended generalised-alpha (a coupled run is always dynamic) and takes no - modal analysis. A standalone mixed EI = 0 + finite-EI deck without bodies - (``aggregate_route``, run on the aggregate, which moves the line ends by translation - only) refuses any torsion column, one restrained end included; the coupled OpenFAST - and FAST.Farm routes turn the fairlead frame with the platform and accept it. + the force-blended generalised-alpha (a coupled run is always dynamic); its modal + analysis (nModes) carries the twist. A standalone mixed EI = 0 + finite-EI deck + without bodies (``aggregate_route``, run on the aggregate, which moves the line ends by + translation only) refuses any torsion column, one restrained end included; the coupled + OpenFAST and FAST.Farm routes turn the fairlead frame with the platform and accept it. """ # _check_attachments has already accepted every LineID as an integer torsion_lines: set[str] = set() @@ -4379,12 +4379,6 @@ def _check_torsion_lines( f"{self._label}: torsion in a dynamic run needs the force-blended " "generalised-alpha (OPTION alpha_force_blend True)" ) - modes_row = option_by_key.get("n_modes") - if modes_row is not None and round(_native_float(modes_row.values[0])) > 0: - raise DeckFormatError( - f"{self._label}: modal analysis (OPTION nModes) of a line with torsion is not " - "yet supported" - ) return torsion_lines def _line_type_fields(self, record: DeckRecord) -> tuple[str, ...]: diff --git a/python/tests/test_deck_native_parity.py b/python/tests/test_deck_native_parity.py index 1d55158f..f481cd63 100644 --- a/python/tests/test_deck_native_parity.py +++ b/python/tests/test_deck_native_parity.py @@ -996,13 +996,13 @@ def test_torsion_line_rules_follow_the_native_checks(): one_end = _edit(_TORSION, (_TORSION_ROW_A, "1 A Rigid 1 0 0 Free 0 0 1 0\n")) _rejects(one_end, "is not torsionally restrained at both ends") DeckFile.from_text(_edit(one_end, ("Torq1N1\nTwist1N41\nTwist1\n", "FairTen1\n"))) - # the dynamic run needs the force blend; modal analysis refuses torsion + # the dynamic run needs the force blend; modal analysis carries the twist dynamic = _edit(_TORSION, ("0.0 TMax\n", "10.0 TMax\n")) DeckFile.from_text(dynamic) _rejects( _options(dynamic, "False alpha_force_blend"), "needs the force-blended generalised-alpha" ) - _rejects(_options(_TORSION, "3 nModes"), "modal analysis .* with torsion is not yet supported") + DeckFile.from_text(_options(_TORSION, "3 nModes")) # the coupled OpenFAST and FAST.Farm routes turn the fairlead frame with the platform and # accept torsion, one restrained end included; a coupled run is always dynamic, so it # needs the force blend whatever the deck's TMax diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index d8bbf840..2a1f0134 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -143,7 +143,7 @@ MODULE CableDyn_DeckDriver CD_Froude_Krylov_Element_Force, CD_HYDRO_OK USE CableDyn_SeabedContact, ONLY: CD_Seabed_Normal_Law, CD_Seabed_Normal_Contact, CD_Seabed_Contact_Gate, & CD_SEABED_CONTACT_BLEND - USE CableDyn_Modal, ONLY: CD_Modal_Bar_Band, CD_Modal_Hermite_Band, CD_Modal_Solve_Band, & + USE CableDyn_Modal, ONLY: CD_Modal_Bar_Band, CD_Modal_Hermite_Line, CD_Modal_Solve_Band, & CD_Modal_Write_Header, CD_Modal_Write_Line, CD_MODAL_OK USE CableDyn_StreamWave, ONLY: CD_StreamWaveType, CD_Stream_Solve, CD_Stream_Kinematics USE CableDyn_WaveSpectra, ONLY: CD_SeaType, CD_WaveTrainType, CD_TRAIN_JONSWAP, CD_SEA_OK, & @@ -303,10 +303,11 @@ MODULE CableDyn_DeckDriver INTEGER, PARAMETER :: WAVE_SEA = 4 ! WAVE_STREAM: regular nonlinear stream-function (Dean) wave of CableDyn_StreamWave INTEGER, PARAMETER :: WAVE_STREAM = 5 - ! One line's modal result (OPTION nModes) + ! One line's modal result (OPTION nModes); polar: each mode's polar share of its kinetic + ! energy, on a line with twist angles (dof_per_node 7) TYPE :: ModalLineResult INTEGER :: n_found = 0, dof_per_node = 3 - REAL(wp), ALLOCATABLE :: omega2(:), shapes(:, :), q(:) + REAL(wp), ALLOCATABLE :: omega2(:), shapes(:, :), q(:), polar(:) END TYPE ModalLineResult REAL(wp), PARAMETER :: TWO_PI = 8.0_wp*QUARTER_PI ! Deck and auxiliary-file record buffer length. next_record reports a record whose @@ -8563,9 +8564,6 @@ SUBROUTINE run_deck_driver(deck_path, out_root, converged, ErrStat, ErrMsg) IF (opts%has_tmax .AND. opts%tmax > CD_ZERO .AND. .NOT. opts%alpha_force_blend) THEN CALL fail(ErrStat, ErrMsg, TORSION_NEEDS_FORCE_BLEND); RETURN END IF - IF (opts%n_modes > 0) THEN - CALL fail(ErrStat, ErrMsg, 'modal analysis (OPTION nModes) of a line with torsion is not yet supported'); RETURN - END IF END IF ! A FAILURE deck is inherently dynamic (the trigger fires at a committed march ! step) and runs on the point-system object graph -- the only path with the @@ -30886,7 +30884,10 @@ END SUBROUTINE write_deck_modes_ei0 SUBROUTINE write_deck_modes_hermite(out_root, lines, opts, cables, ErrStat, ErrMsg) !! .modes.out for finite-EI lines on the cubic-Hermite route, at the static - !! equilibrium the march starts from; the DOFs the march holds are held. + !! equilibrium the march starts from, on the DOFs the march solves (CD_Modal_Hermite_Line): + !! the DOFs the march holds are held, the end connections clamp or spring the end tangents, + !! and a line restrained in torsion carries the twist angle of every node. Positions and + !! translations are turned from the line's frame back to the deck's axes (its heading). CHARACTER(*), INTENT(IN) :: out_root TYPE(DeckLine), INTENT(IN) :: lines(:) TYPE(DeckOptions), INTENT(IN) :: opts @@ -30894,55 +30895,38 @@ SUBROUTINE write_deck_modes_hermite(out_root, lines, opts, cables, ErrStat, ErrM INTEGER, INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg TYPE(ModalLineResult), ALLOCATABLE :: res(:) - REAL(wp), ALLOCATABLE :: kmat(:, :), mmat(:, :), floor_z(:) - LOGICAL, ALLOCATABLE :: free(:) - INTEGER :: li, n, nm, es, kd + INTEGER :: li, nn, dpn, es, k, j, c, i0 + REAL(wp) :: v(3) CHARACTER(1024) :: em ErrStat = CD_DECKDRV_OK ErrMsg = '' ALLOCATE (res(SIZE(lines))) DO li = 1, SIZE(lines) - ASSOCIATE (c => cables(li)%line) - n = SIZE(c%q) - ALLOCATE (free(n), floor_z(c%nn)) - free = c%freemask - floor_z = c%seabed_z - IF (c%has_am .AND. c%has_contact) THEN - CALL CD_Modal_Hermite_Band(c%q, c%l0, c%EA, c%EI, c%rho_a, kd, kmat, mmat, es, em, & - axial_order=c%axial_quadrature_order, & - bending_order=c%bending_quadrature_order, am_rho=c%am_rho, & - am_waterline=c%am_wl, am_diam=c%am_diam, am_can=c%am_can, am_cat=c%am_cat, & - contact_kn=c%contact_kn, floor_z=floor_z) - ELSE IF (c%has_am) THEN - CALL CD_Modal_Hermite_Band(c%q, c%l0, c%EA, c%EI, c%rho_a, kd, kmat, mmat, es, em, & - axial_order=c%axial_quadrature_order, & - bending_order=c%bending_quadrature_order, am_rho=c%am_rho, & - am_waterline=c%am_wl, am_diam=c%am_diam, am_can=c%am_can, am_cat=c%am_cat) - ELSE IF (c%has_contact) THEN - CALL CD_Modal_Hermite_Band(c%q, c%l0, c%EA, c%EI, c%rho_a, kd, kmat, mmat, es, em, & - axial_order=c%axial_quadrature_order, & - bending_order=c%bending_quadrature_order, contact_kn=c%contact_kn, & - floor_z=floor_z) - ELSE - CALL CD_Modal_Hermite_Band(c%q, c%l0, c%EA, c%EI, c%rho_a, kd, kmat, mmat, es, em, & - axial_order=c%axial_quadrature_order, & - bending_order=c%bending_quadrature_order) - END IF - nm = MIN(opts%n_modes, COUNT(free)) - ALLOCATE (res(li)%omega2(MAX(nm, 1)), res(li)%shapes(n, MAX(nm, 1)), res(li)%q(n)) - res(li)%q = c%q - res(li)%dof_per_node = 6 - IF (es == CD_MODAL_OK .AND. nm > 0) & - CALL CD_Modal_Solve_Band(kmat, mmat, kd, free, nm, res(li)%omega2, res(li)%shapes, res(li)%n_found, & - es, em) - IF (ALLOCATED(kmat)) DEALLOCATE (kmat, mmat) - DEALLOCATE (free, floor_z) - END ASSOCIATE + CALL CD_Modal_Hermite_Line(cables(li)%line, opts%n_modes, res(li)%omega2, res(li)%shapes, res(li)%n_found, & + res(li)%dof_per_node, res(li)%polar, es, em) IF (es /= CD_MODAL_OK) THEN CALL fail(ErrStat, ErrMsg, 'line '//TRIM(int_to_str(lines(li)%id))//' modal analysis: '//TRIM(em)) RETURN END IF + dpn = res(li)%dof_per_node + nn = cables(li)%line%nn + ALLOCATE (res(li)%q(dpn*nn)) + res(li)%q = CD_ZERO + DO k = 1, nn + res(li)%q(dpn*(k - 1) + 1:dpn*(k - 1) + 6) = cables(li)%line%q(6*k - 5:6*k) + END DO + IF (cable_frame_is_identity(cables(li))) CYCLE + DO k = 1, nn + DO i0 = dpn*(k - 1), dpn*(k - 1) + 3, 3 + v = res(li)%q(i0 + 1:i0 + 3) + res(li)%q(i0 + 1:i0 + 3) = [(cable_global_component(cables(li), v, c), c=1, 3)] + DO j = 1, res(li)%n_found + v = res(li)%shapes(i0 + 1:i0 + 3, j) + res(li)%shapes(i0 + 1:i0 + 3, j) = [(cable_global_component(cables(li), v, c), c=1, 3)] + END DO + END DO + END DO END DO CALL write_modes_file(out_root, lines, res, ErrStat, ErrMsg) END SUBROUTINE write_deck_modes_hermite @@ -30950,15 +30934,19 @@ END SUBROUTINE write_deck_modes_hermite SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) !! .modes.out: a frequency table (LineID Mode Frequency Period Omega) and a !! mode-shape table (LineID Mode Node X Y Z dX dY dZ). The line models hold their nodes - !! End B first; the table numbers them End A first, like every other line output. + !! End B first; the table numbers them End A first, like every other line output. A file + !! with a line that carries twist angles adds the polar share of each mode (PolarShare) and + !! the nodal twist (dTwist, the section's rotation about the line's End A -> End B tangent, + !! so the model's angle about its own End B -> End A tangent changes sign). CHARACTER(*), INTENT(IN) :: out_root TYPE(DeckLine), INTENT(IN) :: lines(:) TYPE(ModalLineResult), INTENT(IN) :: res(:) INTEGER, INTENT(OUT) :: ErrStat CHARACTER(*), INTENT(OUT) :: ErrMsg INTEGER :: unit, ios, li, part, nn, k, dpn, src, dst - REAL(wp), ALLOCATABLE :: q_a(:), shapes_a(:, :) + REAL(wp), ALLOCATABLE :: q_a(:), shapes_a(:, :), polar(:) CHARACTER(1) :: tb + LOGICAL :: twist ErrStat = CD_DECKDRV_OK ErrMsg = '' tb = char_tab() @@ -30967,11 +30955,24 @@ SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) CALL fail(ErrStat, ErrMsg, 'cannot open modal output file: '//TRIM(out_root)//'.modes.out'); RETURN END IF CALL CD_Modal_Write_Header(unit) + twist = ANY([(res(li)%dof_per_node == 7, li=1, SIZE(res))]) DO part = 1, 2 IF (part == 1) THEN WRITE (unit, '(A)') '# Natural frequencies' - WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Frequency'//tb//'Period'//tb//'Omega' - WRITE (unit, '(A)') '(-)'//tb//'(-)'//tb//'(Hz)'//tb//'(s)'//tb//'(rad/s)' + IF (twist) THEN + WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Frequency'//tb//'Period'//tb//'Omega'//tb//'PolarShare' + WRITE (unit, '(A)') '(-)'//tb//'(-)'//tb//'(Hz)'//tb//'(s)'//tb//'(rad/s)'//tb//'(-)' + ELSE + WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Frequency'//tb//'Period'//tb//'Omega' + WRITE (unit, '(A)') '(-)'//tb//'(-)'//tb//'(Hz)'//tb//'(s)'//tb//'(rad/s)' + END IF + ELSE IF (twist) THEN + WRITE (unit, '(A)') '# Mode shapes (nodal translations and twist, unit largest nodal displacement; '// & + 'a torsional mode, PolarShare > 0.5, unit largest nodal twist)' + WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Node'//tb//'X'//tb//'Y'//tb//'Z'//tb//'dX'//tb//'dY'//tb// & + 'dZ'//tb//'dTwist' + WRITE (unit, '(A)') '(-)'//tb//'(-)'//tb//'(-)'//tb//'(m)'//tb//'(m)'//tb//'(m)'//tb//'(-)'//tb//'(-)'// & + tb//'(-)'//tb//'(rad)' ELSE WRITE (unit, '(A)') '# Mode shapes (nodal translations, unit largest nodal displacement)' WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Node'//tb//'X'//tb//'Y'//tb//'Z'//tb//'dX'//tb//'dY'//tb//'dZ' @@ -30988,8 +30989,18 @@ SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) dst = dpn*(k - 1) q_a(dst + 1:dst + dpn) = res(li)%q(src + 1:src + dpn) shapes_a(dst + 1:dst + dpn, :) = res(li)%shapes(src + 1:src + dpn, :) + IF (dpn == 7) shapes_a(dst + 7, :) = CD_ZERO - shapes_a(dst + 7, :) END DO - CALL CD_Modal_Write_Line(unit, lines(li)%id, q_a, dpn, res(li)%omega2, shapes_a, res(li)%n_found, part) + IF (twist) THEN + IF (ALLOCATED(polar)) DEALLOCATE (polar) + ALLOCATE (polar(MAX(res(li)%n_found, 1))) + polar = CD_ZERO + IF (ALLOCATED(res(li)%polar)) polar(1:res(li)%n_found) = res(li)%polar(1:res(li)%n_found) + CALL CD_Modal_Write_Line(unit, lines(li)%id, q_a, dpn, res(li)%omega2, shapes_a, res(li)%n_found, part, & + polar=polar) + ELSE + CALL CD_Modal_Write_Line(unit, lines(li)%id, q_a, dpn, res(li)%omega2, shapes_a, res(li)%n_found, part) + END IF END DO END DO CLOSE (unit) diff --git a/src/CableDyn_HermiteCableDynamic.f90 b/src/CableDyn_HermiteCableDynamic.f90 index d5b6ffad..a7ac4008 100644 --- a/src/CableDyn_HermiteCableDynamic.f90 +++ b/src/CableDyn_HermiteCableDynamic.f90 @@ -100,7 +100,7 @@ MODULE CableDyn_HermiteCableDynamic PUBLIC :: CD_HermiteCable_Dyn_Coupling_Tension PUBLIC :: CD_HermiteCable_Dyn_Element_Torque, CD_HermiteCable_Dyn_Node_Torque, CD_HermiteCable_Dyn_End_Twist PUBLIC :: CD_HermiteCable_Dyn_Twist_Mirror_Size, CD_HermiteCable_Dyn_Twist_Pack, CD_HermiteCable_Dyn_Twist_Unpack - PUBLIC :: CD_HermiteCable_Dyn_Twist_Check + PUBLIC :: CD_HermiteCable_Dyn_Twist_Check, CD_HermiteCable_Dyn_Twist_Hessian PUBLIC :: CD_HermiteCable_Dyn_Set_Torsion_Drive PUBLIC :: CD_HermiteCable_Dyn_Set_Torsion_Frames PUBLIC :: CD_HermiteCable_Dyn_EndConnection_Moment @@ -6810,6 +6810,68 @@ SUBROUTINE CD_HermiteCable_Dyn_Twist_Check(model, q_check, ends, ErrStat, ErrMsg END DO END SUBROUTINE CD_HermiteCable_Dyn_Twist_Check + SUBROUTINE CD_HermiteCable_Dyn_Twist_Hessian(model, eg, eh, ek, emt, lg, lh, lk, lmt, ErrStat, ErrMsg) + !! The second variation of the nodal-twist elastic energy at the committed state, for an + !! undamped modal analysis about it (CableDyn_Modal): the energy is + !! sum_e 1/2 (GJ/l0)_e tau_e**2 + sum_(elastic ends) 1/2 k tw**2, + !! tau_e = phi_{e+1} - phi_e + rho_e(q), tw = phi_1 - psi_1(q) (end 1), psi_2(q) + Phi - phi_N (end 2), + !! with the committed reference and end frames held. Per element: eg = d rho_e/dq and + !! eh = d2 rho_e/dq2 over its 12 DOFs, ek = GJ/l0 and emt = ek tau_e (the element torque + !! without damping), so d2E/dq2 = emt eh + ek eg eg^T, d2E/dphi_{e+1} dq = ek eg = -d2E/dphi_e dq + !! and d2E/dphi2 = ek [[1, -1], [-1, 1]]. Per end k (columns): lg = d psi/dm and lh = d2 psi/dm2 + !! in the end node's tangent handle m, lk the spring stiffness (0 at a rigid end, whose + !! angle is held) and lmt = lk tw, so d2E/dm2 = lk lg lg^T -+ lmt lh (- at end 1, + at end 2), + !! d2E/dphi dm = -lk lg and d2E/dphi2 = lk. Fails closed without the nodal twist. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + REAL(wp), INTENT(OUT) :: eg(:, :), eh(:, :, :), ek(:), emt(:), lg(3, 2), lh(3, 3, 2), lk(2), lmt(2) + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + REAL(wp) :: rho, beta, psi, tw + INTEGER :: e, iend + eg = CD_ZERO + eh = CD_ZERO + ek = CD_ZERO + emt = CD_ZERO + lg = CD_ZERO + lh = CD_ZERO + lk = CD_ZERO + lmt = CD_ZERO + ErrStat = CD_HCDYN_BADINPUT + IF (.NOT. model%tw_active) THEN + ErrMsg = 'CD_HermiteCable_Dyn_Twist_Hessian: the model has no nodal twist'; RETURN + END IF + IF (SIZE(eg, 1) /= 12 .OR. SIZE(eg, 2) /= model%ne .OR. SIZE(eh, 1) /= 12 .OR. SIZE(eh, 2) /= 12 .OR. & + SIZE(eh, 3) /= model%ne .OR. SIZE(ek) /= model%ne .OR. SIZE(emt) /= model%ne) THEN + ErrMsg = 'CD_HermiteCable_Dyn_Twist_Hessian: the element arrays must have ne columns'; RETURN + END IF + ErrStat = CD_HCDYN_OK + ErrMsg = '' + DO e = 1, model%ne + CALL twist_reference(model, e, model%q, model%torsion%ends, .TRUE., rho, beta, eg(:, e), eh(:, :, e), & + ErrStat, ErrMsg) + IF (ErrStat /= CD_HCDYN_OK) THEN + ErrMsg = 'CD_HermiteCable_Dyn_Twist_Hessian: '//TRIM(ErrMsg); RETURN + END IF + ek(e) = model%torsion%gj(e)/model%l0(e) + emt(e) = ek(e)*(model%tw_phi(e + 1) - model%tw_phi(e) + rho) + END DO + DO iend = 1, 2 + IF (model%tw_rigid(iend)) CYCLE + CALL twist_link(model, iend, model%q, model%torsion%ends, .TRUE., psi, lg(:, iend), lh(:, :, iend), & + ErrStat, ErrMsg) + IF (ErrStat /= CD_HCDYN_OK) THEN + ErrMsg = 'CD_HermiteCable_Dyn_Twist_Hessian: '//TRIM(ErrMsg); RETURN + END IF + lk(iend) = CD_ONE/model%torsion%end_compliance(iend) + IF (iend == 1) THEN + tw = model%tw_phi(1) - psi + ELSE + tw = psi + model%torsion%phi - model%tw_phi(model%nn) + END IF + lmt(iend) = lk(iend)*tw + END DO + END SUBROUTINE CD_HermiteCable_Dyn_Twist_Hessian + PURE INTEGER FUNCTION CD_HermiteCable_Dyn_Twist_Mirror_Size(model) RESULT(n) !! Reals of the nodal-twist checkpoint mirror (CD_HermiteCable_Dyn_Twist_Pack): the !! committed angles, rates and accelerations, directors, reference tangents, reference diff --git a/src/CableDyn_Modal.f90 b/src/CableDyn_Modal.f90 index 2f1f0ac8..3c15668b 100644 --- a/src/CableDyn_Modal.f90 +++ b/src/CableDyn_Modal.f90 @@ -29,11 +29,29 @@ MODULE CableDyn_Modal !! and the consistent mass (m l0/6) [[2I, I], [I, 2I]]. !! Finite-EI lines (cubic-Hermite, position and tangent per node): the element Hessian of !! CD_HermiteCable_Element and the consistent mass of CD_HermiteCable_Mass. + !! + !! A line model of the cubic-Hermite dynamics (CD_Modal_Hermite_Line) adds what its dynamics + !! carries: the end connections (a finite spring's Hessian on the end tangent; a rigid end + !! keeps only the magnitude of its tangent, in the basis [d, b1, b2] of its direction d), the + !! discrete attachments' masses and, on a line restrained in torsion, its twist. The dynamics + !! of such a line carries a twist angle phi at every node (the nodal twist, with the polar + !! inertia Irn), so the modes do too: 7 DOFs per node [r, m, phi], the lumped polar inertia + !! (half of each adjacent element's Irn l0) as the mass of phi, and the second variation of the + !! twist energy sum_e 1/2 (GJ/l0)(phi_{e+1} - phi_e + rho_e(q))**2 (+ the elastic end springs) + !! as stiffness (CD_HermiteCable_Dyn_Twist_Hessian): with M_e the element torque, + !! d2E/dq2 = M_e d2rho/dq2 + (GJ/l0) g g^T, d2E/dphi dq = +-(GJ/l0) g, g = drho_e/dq, + !! which couples the twist to the bending and, under torque-tension coupling (rho_e then holds + !! (K/GJ)(l - l0)), to the stretch. Eliminating the angles (no polar inertia) leaves the + !! condensed static tangent of the statics, M_t d2(-Theta)/dq2 + (1/C) g_T g_T^T, + !! g_T = dTheta/dq: the Schur complement of the angle block is that rank-one term. USE CableDyn_Precision, ONLY: wp, CD_ZERO, CD_ONE, CD_All_Finite USE CableDyn_SeabedContact, ONLY: CD_Seabed_Normal_Law USE CableDyn_Hydro, ONLY: CD_Cable_Added_Mass_Matrix USE CableDyn_HermiteCable, ONLY: CD_HermiteCable_Element, CD_HermiteCable_Mass - USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCable_AddedMass_Element + USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCable_AddedMass_Element, CD_HermiteCableDynType, & + CD_HermiteCable_Dyn_Twist_Hessian, CD_HCDYN_OK + USE CableDyn_EndConnection, ONLY: CD_EndConn_Spring, CD_EndConn_Basis, CD_ENDCONN_OK, CD_ENDCONN_FINITE, & + CD_ENDCONN_RIGID USE CableDyn_Linalg, ONLY: CD_Factor_Banded, CD_Solve_Factored_Banded, CD_Blas_Runtime_Check, CD_LINALG_OK, & CD_BLAS_UNAVAILABLE_INFO IMPLICIT NONE @@ -48,6 +66,7 @@ MODULE CableDyn_Modal REAL(wp), PARAMETER :: TWO_PI = 6.283185307179586476925286766559005768394_wp PUBLIC :: CD_Modal_Bar_Band, CD_Modal_Hermite_Band, CD_Modal_Solve_Band + PUBLIC :: CD_Modal_Hermite_Line, CD_Modal_Hermite_Line_Band PUBLIC :: CD_Modal_Bar_Matrices, CD_Modal_Hermite_Matrices, CD_Modal_Solve PUBLIC :: CD_Modal_Write_Header, CD_Modal_Write_Line @@ -361,6 +380,288 @@ SUBROUTINE CD_Modal_Hermite_Band(q, l0, ea, ei, rho_a, kd, K, M, ErrStat, ErrMsg END IF END SUBROUTINE CD_Modal_Hermite_Band + SUBROUTINE CD_Modal_Hermite_Line(model, n_modes, omega2, shapes, n_found, dof_per_node, polar, ErrStat, ErrMsg) + !! The n_modes lowest modes of a cubic-Hermite line model about its committed state (the + !! static equilibrium a deck starts its march from), on the DOFs its dynamics solves + !! (CD_Modal_Hermite_Line_Band). dof_per_node is 6 ([r, m] per node) or 7 ([r, m, phi]); + !! shapes(:, j) is the full-length mode vector in the model's axes and node order (zero on + !! the held DOFs), M-orthonormal; polar(j) its polar share of the modal kinetic energy, + !! sum_k I_k phi_k**2 (0 without twist, 1 for a pure torsional mode). + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + INTEGER, INTENT(IN) :: n_modes + REAL(wp), ALLOCATABLE, INTENT(OUT) :: omega2(:), shapes(:, :), polar(:) + INTEGER, INTENT(OUT) :: n_found, dof_per_node, ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + REAL(wp), ALLOCATABLE :: kb(:, :), mb(:, :) + REAL(wp) :: basis(3, 3), f3(3) + LOGICAL, ALLOCATABLE :: free(:) + INTEGER :: n, kd, iend, j, k, nm + CHARACTER(1024) :: em + + n_found = 0 + CALL CD_Modal_Hermite_Line_Band(model, kd, kb, mb, free, dof_per_node, ErrStat, ErrMsg) + IF (ErrStat /= CD_MODAL_OK) RETURN + n = SIZE(free) + nm = MIN(n_modes, COUNT(free)) + ALLOCATE (omega2(MAX(nm, 1)), shapes(n, MAX(nm, 1)), polar(MAX(nm, 1))) + omega2 = CD_ZERO + shapes = CD_ZERO + polar = CD_ZERO + IF (nm < 1) THEN + CALL fail(ErrStat, ErrMsg, 'the line has no free degree of freedom') + RETURN + END IF + CALL CD_Modal_Solve_Band(kb, mb, kd, free, nm, omega2, shapes, n_found, ErrStat, ErrMsg) + IF (ErrStat /= CD_MODAL_OK) RETURN + ! back to the model's axes: m = B [s, 0, 0] at a rigid end + IF (model%has_endconn) THEN + DO iend = 1, 2 + IF (model%endconn_mode(iend) /= CD_ENDCONN_RIGID) CYCLE + CALL CD_EndConn_Basis(model%endconn_d0(:, iend), basis, ErrStat, em) + IF (ErrStat /= CD_ENDCONN_OK) THEN + n_found = 0 + CALL fail(ErrStat, ErrMsg, 'end connection: '//TRIM(em)) + RETURN + END IF + j = dof_per_node*(MERGE(1, model%nn, iend == 1) - 1) + 3 + DO k = 1, n_found + f3 = shapes(j + 1:j + 3, k) + shapes(j + 1:j + 3, k) = MATMUL(basis, f3) + END DO + END DO + END IF + IF (dof_per_node == 7) THEN + DO k = 1, n_found + polar(k) = SUM(model%tw_mass*shapes(7:n:7, k)**2) + END DO + END IF + END SUBROUTINE CD_Modal_Hermite_Line + + SUBROUTINE CD_Modal_Hermite_Line_Band(model, kd, K, M, free, dof_per_node, ErrStat, ErrMsg) + !! Stiffness and mass of a cubic-Hermite line model at its committed state, as their + !! symmetric parts in upper band storage of half-bandwidth kd, with the free-DOF mask, on + !! the DOFs its dynamics solves: the element stiffness and mass with the Morison added mass + !! and the seabed normal contact of CD_Modal_Hermite_Band, the attachments' masses, the end + !! connections and, with the nodal twist, the twist angles (see the module note; 7 DOFs per + !! node, kd = 13, else 6 and kd = 11). The tangent handle of a rigid end is in the basis + !! [d, b1, b2] of its direction (CD_EndConn_Basis), b1 and b2 held. A line with the + !! condensed torsion of the quasi-static dynamics (no polar inertia) is refused. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + INTEGER, INTENT(OUT) :: kd, dof_per_node, ErrStat + REAL(wp), ALLOCATABLE, INTENT(OUT) :: K(:, :), M(:, :) + LOGICAL, ALLOCATABLE, INTENT(OUT) :: free(:) + CHARACTER(*), INTENT(OUT) :: ErrMsg + REAL(wp), ALLOCATABLE :: k6(:, :), m6(:, :), floor_z(:), eg(:, :), eh(:, :, :), ek(:), emt(:) + REAL(wp) :: lg(3, 2), lh(3, 3, 2), lk(2), lmt(2), f3(3), k3(3, 3), ke(14, 14), kl(4, 4), basis(3, 3, 2) + LOGICAL :: twist, rigid(2) + INTEGER :: nn, ne, n6, n, kd6, i, j, i6, j6, e, a, b, ia, ib, iend, node, p + INTEGER :: gd(14), gl4(4) + CHARACTER(1024) :: em + + ErrStat = CD_MODAL_OK + ErrMsg = '' + kd = 0 + dof_per_node = 6 + nn = model%nn + ne = model%ne + n6 = model%ndof + twist = model%tw_active + IF (model%torsion%active .AND. .NOT. twist) THEN + CALL fail(ErrStat, ErrMsg, 'a line with condensed torsion (no polar inertia Irn) has no torsional '// & + 'modes; give its torsion the polar inertia') + RETURN + END IF + ALLOCATE (floor_z(nn)) + floor_z = model%seabed_z + IF (model%has_am .AND. model%has_contact) THEN + CALL CD_Modal_Hermite_Band(model%q, model%l0, model%EA, model%EI, model%rho_a, kd6, k6, m6, ErrStat, em, & + axial_order=model%axial_quadrature_order, & + bending_order=model%bending_quadrature_order, am_rho=model%am_rho, & + am_waterline=model%am_wl, am_diam=model%am_diam, am_can=model%am_can, & + am_cat=model%am_cat, contact_kn=model%contact_kn, floor_z=floor_z) + ELSE IF (model%has_am) THEN + CALL CD_Modal_Hermite_Band(model%q, model%l0, model%EA, model%EI, model%rho_a, kd6, k6, m6, ErrStat, em, & + axial_order=model%axial_quadrature_order, & + bending_order=model%bending_quadrature_order, am_rho=model%am_rho, & + am_waterline=model%am_wl, am_diam=model%am_diam, am_can=model%am_can, & + am_cat=model%am_cat) + ELSE IF (model%has_contact) THEN + CALL CD_Modal_Hermite_Band(model%q, model%l0, model%EA, model%EI, model%rho_a, kd6, k6, m6, ErrStat, em, & + axial_order=model%axial_quadrature_order, & + bending_order=model%bending_quadrature_order, contact_kn=model%contact_kn, & + floor_z=floor_z) + ELSE + CALL CD_Modal_Hermite_Band(model%q, model%l0, model%EA, model%EI, model%rho_a, kd6, k6, m6, ErrStat, em, & + axial_order=model%axial_quadrature_order, & + bending_order=model%bending_quadrature_order) + END IF + IF (ErrStat /= CD_MODAL_OK) THEN + ErrMsg = em + RETURN + END IF + ! discrete attachments: dry mass m and added mass Ca rho V on the node's translations + IF (model%has_attach) THEN + DO p = 1, SIZE(model%att_node) + DO i = 1, 3 + j = 6*(model%att_node(p) - 1) + i + CALL add_entry(m6, kd6, j, j, model%att_mass(p) + model%att_madd(p)) + END DO + END DO + END IF + ! end connections: a finite spring adds d2U/dm2 on its end tangent; a rigid end is + ! rotated into its basis below + rigid = .FALSE. + IF (model%has_endconn) THEN + DO iend = 1, 2 + node = MERGE(1, nn, iend == 1) + j = 6*(node - 1) + 3 + IF (model%endconn_mode(iend) == CD_ENDCONN_FINITE) THEN + CALL CD_EndConn_Spring(model%q(j + 1:j + 3), model%endconn_d0(:, iend), model%endconn_k(iend), f3, k3, & + ErrStat, em) + IF (ErrStat /= CD_ENDCONN_OK) THEN + CALL fail(ErrStat, ErrMsg, 'end connection: '//TRIM(em)) + RETURN + END IF + CALL add_block(k6, kd6, [j + 1, j + 2, j + 3], k3) + ELSE IF (model%endconn_mode(iend) == CD_ENDCONN_RIGID) THEN + rigid(iend) = .TRUE. + CALL CD_EndConn_Basis(model%endconn_d0(:, iend), basis(:, :, iend), ErrStat, em) + IF (ErrStat /= CD_ENDCONN_OK) THEN + CALL fail(ErrStat, ErrMsg, 'end connection: '//TRIM(em)) + RETURN + END IF + END IF + END DO + END IF + + IF (.NOT. twist) THEN + n = n6 + kd = kd6 + CALL MOVE_ALLOC(k6, K) + CALL MOVE_ALLOC(m6, M) + ALLOCATE (free(n)) + free = model%freemask + ELSE + ! [r, m] of node p at 7(p - 1) + 1..6, its angle at 7 p: DOF i6 of the cable is + ! i6 + (i6 - 1)/6; one element spans 14 DOFs (half-bandwidth 13) + dof_per_node = 7 + n = 7*nn + kd = 13 + ALLOCATE (K(kd + 1, n), M(kd + 1, n), free(n)) + K = CD_ZERO + M = CD_ZERO + DO j6 = 1, n6 + DO i6 = MAX(1, j6 - kd6), j6 + K(kd + 1 + (i6 + (i6 - 1)/6) - (j6 + (j6 - 1)/6), j6 + (j6 - 1)/6) = k6(kd6 + 1 + i6 - j6, j6) + M(kd + 1 + (i6 + (i6 - 1)/6) - (j6 + (j6 - 1)/6), j6 + (j6 - 1)/6) = m6(kd6 + 1 + i6 - j6, j6) + END DO + free(j6 + (j6 - 1)/6) = model%freemask(j6) + END DO + DEALLOCATE (k6, m6) + ALLOCATE (eg(12, ne), eh(12, 12, ne), ek(ne), emt(ne)) + CALL CD_HermiteCable_Dyn_Twist_Hessian(model, eg, eh, ek, emt, lg, lh, lk, lmt, ErrStat, em) + IF (ErrStat /= CD_HCDYN_OK) THEN + CALL fail(ErrStat, ErrMsg, TRIM(em)) + RETURN + END IF + DO e = 1, ne + ! element DOFs [r_e, m_e, phi_e, r_e+1, m_e+1, phi_e+1]; the cable's 12 at 1..6, 8..13 + DO i = 1, 14 + gd(i) = 7*(e - 1) + i + END DO + ke = CD_ZERO + DO b = 1, 12 + ib = b + (b - 1)/6 + DO a = 1, 12 + ia = a + (a - 1)/6 + ke(ia, ib) = emt(e)*eh(a, b, e) + ek(e)*eg(a, e)*eg(b, e) + END DO + ke(ib, 14) = ek(e)*eg(b, e) + ke(14, ib) = ke(ib, 14) + ke(ib, 7) = -ek(e)*eg(b, e) + ke(7, ib) = ke(ib, 7) + END DO + ke(7, 7) = ek(e) + ke(14, 14) = ek(e) + ke(7, 14) = -ek(e) + ke(14, 7) = -ek(e) + CALL add_block(K, kd, gd, ke) + END DO + DO iend = 1, 2 + IF (.NOT. lk(iend) > CD_ZERO) CYCLE + ! the elastic end's spring on [m, phi] of its node, d2psi/dm2 signed by its torque + node = MERGE(1, nn, iend == 1) + gl4 = [7*(node - 1) + 4, 7*(node - 1) + 5, 7*(node - 1) + 6, 7*node] + DO b = 1, 3 + DO a = 1, 3 + kl(a, b) = lk(iend)*lg(a, iend)*lg(b, iend) + MERGE(-lmt(iend), lmt(iend), iend == 1)*lh(a, b, iend) + END DO + kl(b, 4) = -lk(iend)*lg(b, iend) + kl(4, b) = kl(b, 4) + END DO + kl(4, 4) = lk(iend) + CALL add_block(K, kd, gl4, kl) + END DO + DO p = 1, nn + CALL add_entry(M, kd, 7*p, 7*p, model%tw_mass(p)) + free(7*p) = model%tw_free(p) + END DO + END IF + ! a rigid end: its tangent handle in the basis [d, b1, b2], b1 and b2 held + DO iend = 1, 2 + IF (.NOT. rigid(iend)) CYCLE + node = MERGE(1, nn, iend == 1) + j = dof_per_node*(node - 1) + 3 + CALL rotate_band_block(K, kd, j, basis(:, :, iend), ErrStat, em) + IF (ErrStat == CD_MODAL_OK) CALL rotate_band_block(M, kd, j, basis(:, :, iend), ErrStat, em) + IF (ErrStat /= CD_MODAL_OK) THEN + ErrMsg = em + RETURN + END IF + free(j + 2:j + 3) = .FALSE. + END DO + END SUBROUTINE CD_Modal_Hermite_Line_Band + + SUBROUTINE rotate_band_block(ab, kd, j0, b, ErrStat, ErrMsg) + !! A <- T^T A T for a symmetric A in upper band storage, T the identity but for the block b + !! on the DOFs j0 + 1..j0 + 3 (the tangent handle of a node in a rigid end's basis). The + !! block's couplings reach only the DOFs of its node's two elements, all within kd of every + !! DOF of the block, so the band does not widen; an entry that would fails closed. + REAL(wp), INTENT(INOUT) :: ab(:, :) + INTEGER, INTENT(IN) :: kd, j0 + REAL(wp), INTENT(IN) :: b(3, 3) + INTEGER, INTENT(OUT) :: ErrStat + CHARACTER(*), INTENT(OUT) :: ErrMsg + REAL(wp), ALLOCATABLE :: w(:, :) + INTEGER :: n, lo, hi, i, j + ErrStat = CD_MODAL_OK + ErrMsg = '' + n = SIZE(ab, 2) + lo = MAX(1, j0 + 1 - kd) + hi = MIN(n, j0 + 3 + kd) + ALLOCATE (w(lo:hi, lo:hi)) + w = CD_ZERO + DO j = lo, hi + DO i = MAX(lo, j - kd), j + w(i, j) = ab(kd + 1 + i - j, j) + w(j, i) = w(i, j) + END DO + END DO + w(j0 + 1:j0 + 3, :) = MATMUL(TRANSPOSE(b), w(j0 + 1:j0 + 3, :)) + w(:, j0 + 1:j0 + 3) = MATMUL(w(:, j0 + 1:j0 + 3), b) + DO j = lo, hi + DO i = lo, j + IF (.NOT. ((i > j0 .AND. i <= j0 + 3) .OR. (j > j0 .AND. j <= j0 + 3))) CYCLE + IF (j - i <= kd) THEN + ab(kd + 1 + i - j, j) = w(i, j) + ELSE IF (ABS(w(i, j)) > CD_ZERO) THEN + CALL fail(ErrStat, ErrMsg, 'a rigid end basis would widen the band') + RETURN + END IF + END DO + END DO + END SUBROUTINE rotate_band_block + SUBROUTINE CD_Modal_Bar_Matrices(q, elem_conn, l0, ea, rho_a, tension_only, K, M, ErrStat, ErrMsg, & am_rho, am_waterline, am_diam, am_can, am_cat, seabed_kn, floor_z) !! Dense form of CD_Modal_Bar_Band (the symmetric parts), for the dense reference solver. @@ -742,15 +1043,20 @@ SUBROUTINE CD_Modal_Write_Header(unit) '(static tangent, structural + added mass, fixed and prescribed ends held)' END SUBROUTINE CD_Modal_Write_Header - SUBROUTINE CD_Modal_Write_Line(unit, line_id, q, dof_per_node, omega2, shapes, n_found, part) + SUBROUTINE CD_Modal_Write_Line(unit, line_id, q, dof_per_node, omega2, shapes, n_found, part, polar) !! part = 1: the frequency rows "LineID Mode Frequency Period Omega"; part = 2: the !! shape rows "LineID Mode Node X Y Z dX dY dZ", the nodal translations of each mode !! scaled to a unit largest nodal displacement (the static position X Y Z beside it). - !! A negative omega^2 is written with a negative frequency and period 0. + !! A negative omega^2 is written with a negative frequency and period 0. With polar (the + !! twist columns of a file holding a line with twist): the frequency rows add the polar + !! share of each mode, the shape rows the nodal twist dTwist (the 7th DOF of a node when + !! dof_per_node = 7, else 0) on the same scale; a mode whose kinetic energy is mostly polar + !! (share above 1/2, a torsional mode) is scaled to a unit largest nodal twist instead. INTEGER, INTENT(IN) :: unit, line_id, dof_per_node, n_found, part REAL(wp), INTENT(IN) :: q(:), omega2(:), shapes(:, :) + REAL(wp), INTENT(IN), OPTIONAL :: polar(:) INTEGER :: j, i, nn, i0 - REAL(wp) :: om, fr, per, scl, dmax + REAL(wp) :: om, fr, per, scl, dmax, tw CHARACTER(1), PARAMETER :: TB = ACHAR(9) nn = SIZE(q)/dof_per_node DO j = 1, n_found @@ -759,19 +1065,35 @@ SUBROUTINE CD_Modal_Write_Line(unit, line_id, q, dof_per_node, omega2, shapes, n fr = om/TWO_PI per = CD_ZERO IF (om > CD_ZERO) per = CD_ONE/fr - WRITE (unit, '(I0,A,I0,3(A,ES16.8E3))') line_id, TB, j, TB, fr, TB, per, TB, om + IF (PRESENT(polar)) THEN + WRITE (unit, '(I0,A,I0,4(A,ES16.8E3))') line_id, TB, j, TB, fr, TB, per, TB, om, TB, polar(j) + ELSE + WRITE (unit, '(I0,A,I0,3(A,ES16.8E3))') line_id, TB, j, TB, fr, TB, per, TB, om + END IF ELSE dmax = CD_ZERO - DO i = 1, nn - i0 = dof_per_node*(i - 1) - dmax = MAX(dmax, SQRT(SUM(shapes(i0 + 1:i0 + 3, j)**2))) - END DO + IF (PRESENT(polar) .AND. dof_per_node == 7) THEN + IF (polar(j) > 0.5_wp) dmax = MAXVAL(ABS(shapes(7:7*nn:7, j))) + END IF + IF (.NOT. dmax > CD_ZERO) THEN + DO i = 1, nn + i0 = dof_per_node*(i - 1) + dmax = MAX(dmax, SQRT(SUM(shapes(i0 + 1:i0 + 3, j)**2))) + END DO + END IF scl = CD_ONE IF (dmax > CD_ZERO) scl = CD_ONE/dmax DO i = 1, nn i0 = dof_per_node*(i - 1) - WRITE (unit, '(I0,A,I0,A,I0,6(A,ES16.8E3))') line_id, TB, j, TB, i, TB, q(i0 + 1), TB, q(i0 + 2), TB, & - q(i0 + 3), TB, scl*shapes(i0 + 1, j), TB, scl*shapes(i0 + 2, j), TB, scl*shapes(i0 + 3, j) + IF (PRESENT(polar)) THEN + tw = CD_ZERO + IF (dof_per_node == 7) tw = scl*shapes(i0 + 7, j) + WRITE (unit, '(I0,A,I0,A,I0,7(A,ES16.8E3))') line_id, TB, j, TB, i, TB, q(i0 + 1), TB, q(i0 + 2), & + TB, q(i0 + 3), TB, scl*shapes(i0 + 1, j), TB, scl*shapes(i0 + 2, j), TB, scl*shapes(i0 + 3, j), TB, tw + ELSE + WRITE (unit, '(I0,A,I0,A,I0,6(A,ES16.8E3))') line_id, TB, j, TB, i, TB, q(i0 + 1), TB, q(i0 + 2), & + TB, q(i0 + 3), TB, scl*shapes(i0 + 1, j), TB, scl*shapes(i0 + 2, j), TB, scl*shapes(i0 + 3, j) + END IF END DO END IF END DO diff --git a/tests/data/torsion_lazy_wave_modes.dat b/tests/data/torsion_lazy_wave_modes.dat new file mode 100644 index 00000000..f525bc61 --- /dev/null +++ b/tests/data/torsion_lazy_wave_modes.dat @@ -0,0 +1,46 @@ +--------------------- CableDyn Input File ------------------------------------ +Modal analysis (nModes) of the Gulf of Mexico 80 m lazy-wave cable twisted two turns +-- Driver regression: the cable, clamped and restrained in torsion at both ends, of +-- examples/torsion_lazy_wave_hangoff_twist.dat (illustrative GJ = 50 kN.m^2), with the two turns +-- imposed as the End B pretwist instead of the hang-off roll. The static solve twists the cable +-- by +720 deg; the modes about that twisted equilibrium carry the twist angle of every node +-- (the polar inertia Irn of LINE TYPES), so the table adds PolarShare and dTwist. One 0.1 s step. +--------------------- LINE TYPES --------------------------------------------- +TypeName Diam MassDenInAir EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t +(-) (m) (kg/m) (N) (-) (N-m2) (N) (N-m2) (kg-m) (kg-m) (-) (-) (-) (-) +bare 0.160 36.70 4.69e8 0.0 1.99e4 9.02e7 5.0e4 0.0587 0.1174 1.2 0.1 1.0 0.0 +buoy 0.290 59.53 4.69e8 0.0 1.99e4 9.02e7 5.0e4 0.3129 0.6258 1.2 0.1 1.0 0.0 +--------------------- POINTS ------------------------------------------------ +ID Type X Y Z +(-) (-) (m) (m) (m) +1 Coupled 5.0 0.0 -14.0 +2 Fixed 125.0 0.0 -80.0 +--------------------- LINES ------------------------------------------------- +ID NodeA NodeB Outputs +(-) (-) (-) (-) +1 1 2 - +--------------------- SECTIONS ---------------------------------------------- +LineID LineType Length NumSegs +(-) (-) (m) (-) +1 bare 68.114 56 +1 buoy 50.000 40 +1 bare 52.101 32 +--------------------- END CONNECTIONS --------------------------------------- +LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist +(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg) +1 A Rigid 0.14641 0.0 -0.98922 Rigid 0.0 1.0 0.0 0.0 +1 B Rigid 0.99999 0.0 0.00503 Rigid 0.0 1.0 0.0 720.0 +--------------------- OPTIONS ----------------------------------------------- +9.80665 g - Gravitational acceleration (m/s^2) +1025.0 rhoW - Water density (kg/m^3) +80.0 WtrDpth - Water depth for the flat seabed (m) +1.0e5 kBot - Seabed penalty stiffness base (Pa/m) +1.0e4 cBot - Seabed normal damping base (Pa-s/m) +0.1 dtM - CableDyn internal time step (s) +0.1 TMax - Standalone simulation duration (s) +12 nModes - Modal analysis: number of lowest natural modes per line +--------------------- OUTPUTS ----------------------------------------------- +"FairTen1" +"Torq1N1" +"Twist1" +--------------------- need this line ---------------------------------------- diff --git a/tests/test_modal_torsion.f90 b/tests/test_modal_torsion.f90 new file mode 100644 index 00000000..b1e6f94e --- /dev/null +++ b/tests/test_modal_torsion.f90 @@ -0,0 +1,804 @@ +! File: tests/test_modal_torsion.f90 +! SPDX-License-Identifier: Apache-2.0 +! Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +PROGRAM test_modal_torsion + !! Modal analysis of a cubic-Hermite line restrained in torsion (CD_Modal_Hermite_Line: the + !! twist angle of every node joins the modes, with the lumped polar inertia Irn l0 as its mass + !! and the second variation of the twist energy as its stiffness), on a 10 m line along +x: + !! T torsional modes of a straight taut line clamped at both ends (bending Rigid): + !! T1 rigid torsional ends: omega_n = n pi/L0 sqrt(GJ/Irn) (continuum; the lumped chain's + !! error 1 - sin(x)/x, x = n pi/(2 NE), bounds it) and the chain's own + !! 2 sqrt(GJ/Irn)/l0 sin(n pi/(2 NE)) to 1e-9; every other mode (bending, axial) equal to + !! the same line without torsion to 1e-9 and free of twist; + !! T2 elastic torsional ends k: the continuum's ((GJ b)^2 - k^2) sin(b L0) = 2 k GJ b cos(b L0), + !! omega = b sqrt(GJ/Irn), and the lumped chain with the end springs (dense solve); + !! T3 torque-tension coupling K (energy 1/2 EA e^2 + K e tau + 1/2 GJ tau^2): the coupled + !! axial-torsional modes omega^2 = (n pi/L0)^2 eig([[EA, K], [K, GJ]], diag(m, Irn)); + !! C the condensed limit (negligible Irn) of a line under a torque M: + !! C1 the lateral modes of the straight taut clamped line under the torque M. Linearised + !! about the straight state, u = y + i z (s0 the unstretched arc length, stretch lambda), + !! (EI/lambda^4) u'''' - i (M/lambda^2) u''' - (T/lambda) u'' = m omega^2 u + !! (the shaft under torque of Greenhill, Proc. Inst. Mech. Eng., 1883, and Ziegler, + !! Principles of Structural Stability, 1968, with the tension of a taut cable; the twist + !! energy -M Theta, Theta = 1/2 int (y'z'' - z'y'')/lambda^2 the parallel-transport + !! holonomy of the centreline). u = sum c_j + !! exp(i k_j s0) with EIe k^4 - Me k^3 + Te k^2 = m omega^2, clamped (u = u' = 0) at both + !! ends: the 4 x 4 determinant, times exp(-i L0 sum k_j/2) purely imaginary, vanishes + !! at the frequencies (each a pair of real modes, a helix and its mirror). With + !! 9 Me^2 < 32 EIe Te the quartic has no double root at omega > 0. The torque lowers + !! every lateral frequency (M = 4 EI/L0: -5.5 % on the first); + !! C2 the Schur complement of the twist angles in the modal stiffness, K_qq - + !! K_qphi K_phiphi^-1 K_phiq, is the condensed static tangent of the statics at the same + !! state, the element Hessians + M_t d2(-Theta)/dq2 + (1/C) g g^T (CD_HermiteTorsion_Line, + !! M_t = (Phi - Theta)/C), and the central difference of the condensed static residual + !! sum f_int - M_t dTheta/dq: on a bowed, twisted line with bending-pinned ends (rigid + !! and elastic torsional ends), clamped ends, and torque-tension coupling. + !! E the end connections the modes take from the model: a finite bending spring k at both + !! ends of the straight taut line (no torsion) puts its first lateral frequency between the + !! pinned (k = 0) and the clamped (Rigid) line's, rising with k and within 1e-4 of the + !! clamped one at k = 1e5 EI/L0. + !! The modal analysis without the twist (the old route: CD_Modal_Hermite_Band, no twist + !! DOFs, the end connections ignored) is reported beside each gate for comparison. + USE CableDyn_Precision, ONLY: wp + USE CableDyn_Modal, ONLY: CD_Modal_Hermite_Line, CD_Modal_Hermite_Line_Band, CD_Modal_Hermite_Band, & + CD_Modal_Solve_Band, CD_Modal_Solve, CD_MODAL_OK + USE CableDyn_EndConnection, ONLY: CD_ENDCONN_RIGID, CD_ENDCONN_FINITE, CD_EndConn_Basis + USE CableDyn_HermiteCable, ONLY: CD_HermiteCable_Element + USE CableDyn_HermiteTorsion, ONLY: CD_HermiteTorsionType, CD_HermiteTorsion_Line, CD_HermiteTorsion_Unwrap, & + CD_HermiteTorsion_Compliance, CD_HTORS_OK, CD_HTORS_KBAND + USE CableDyn_HermiteCableDynamic, ONLY: CD_HermiteCableDynType, CD_HermiteCable_Dyn_Init, & + CD_HermiteCable_Dyn_Set_EndConnection, CD_HermiteCable_Dyn_Set_Torsion, & + CD_HermiteCable_Dyn_End, CD_HCDYN_OK + IMPLICIT NONE + + REAL(wp), PARAMETER :: PI = 3.141592653589793238462643383279502884197_wp + REAL(wp), PARAMETER :: L0 = 10.0_wp, EI = 100.0_wp, GJ = 80.0_wp, RHOA = 1.0_wp, TENSION = 10.0_wp + INTEGER :: nfail = 0 + + CALL gate_t1() + CALL gate_t2() + CALL gate_t3() + CALL gate_c1() + CALL gate_c2('pinned, rigid torsion', .FALSE., 0.0_wp, 0.0_wp) + CALL gate_c2('pinned, elastic torsion', .FALSE., 0.05_wp, 0.0_wp) + CALL gate_c2('clamped, rigid torsion', .TRUE., 0.0_wp, 0.0_wp) + CALL gate_c2('clamped, elastic torsion, coupling K', .TRUE., 0.02_wp, 300.0_wp) + CALL gate_e() + + IF (nfail > 0) THEN + WRITE (*, '(A,I0,A)') 'FAIL: ', nfail, ' assertion(s) failed' + ERROR STOP 1 + END IF + WRITE (*, '(A)') 'PASS: modal analysis with torsion' + +CONTAINS + + INCLUDE 'nan_max_abs.inc' + + SUBROUTINE require(cond, label) + LOGICAL, INTENT(IN) :: cond + CHARACTER(*), INTENT(IN) :: label + IF (cond) RETURN + nfail = nfail + 1 + WRITE (*, '(A)') 'FAIL: '//TRIM(label) + END SUBROUTINE require + + SUBROUTINE straight(ne, stretch, q) + !! Straight line along +x of ne elements, unstretched length L0 stretched by lambda. + INTEGER, INTENT(IN) :: ne + REAL(wp), INTENT(IN) :: stretch + REAL(wp), INTENT(OUT) :: q(:) + INTEGER :: k + q = 0.0_wp + DO k = 1, ne + 1 + q(6*k - 5) = stretch*L0*REAL(k - 1, wp)/REAL(ne, wp) + q(6*k - 2) = stretch + END DO + END SUBROUTINE straight + + SUBROUTINE bowed(ne, q) + !! A line along +x bowed by y = 0.3 sin^2(pi s/L0), z = 0.1 sin^2(2 pi s/L0) (end tangents + !! along +x) and stretched by 1 %. + INTEGER, INTENT(IN) :: ne + REAL(wp), INTENT(OUT) :: q(:) + INTEGER :: k + REAL(wp) :: s + q = 0.0_wp + DO k = 1, ne + 1 + s = L0*REAL(k - 1, wp)/REAL(ne, wp) + q(6*k - 5) = 1.01_wp*s + q(6*k - 4) = 0.3_wp*SIN(PI*s/L0)**2 + q(6*k - 3) = 0.1_wp*SIN(2.0_wp*PI*s/L0)**2 + q(6*k - 2) = 1.01_wp + q(6*k - 1) = 0.3_wp*(PI/L0)*SIN(2.0_wp*PI*s/L0) + q(6*k) = 0.1_wp*(2.0_wp*PI/L0)*SIN(4.0_wp*PI*s/L0) + END DO + END SUBROUTINE bowed + + SUBROUTINE build(model, ne, q, ea, clamped, torsion, phi, irn, compliance, ktt) + !! Dynamic line model on q, both end positions held; Rigid bending connections along +x at both + !! ends when clamped; with torsion, both ends restrained (frames +x / +z, imposed twist phi, + !! end compliance, polar inertia irn, torque-tension coupling ktt with EA - ktt^2/GJ as the + !! line's own axial stiffness). + TYPE(CD_HermiteCableDynType), INTENT(OUT) :: model + INTEGER, INTENT(IN) :: ne + REAL(wp), INTENT(IN) :: q(:), ea, phi, irn, compliance, ktt + LOGICAL, INTENT(IN) :: clamped, torsion + TYPE(CD_HermiteTorsionType) :: tors + REAL(wp) :: le(ne), g(SIZE(q)), raw, ea_line + INTEGER :: es, ndof + CHARACTER(512) :: em + ndof = SIZE(q) + le = L0/REAL(ne, wp) + ea_line = ea + IF (torsion) ea_line = ea - ktt**2/GJ + CALL CD_HermiteCable_Dyn_Init(model, le, [(ea_line, es=1, ne)], [(EI, es=1, ne)], [(RHOA, es=1, ne)], & + [(0.0_wp, es=1, ne)], q, [1, 2, 3, ndof - 5, ndof - 4, ndof - 3], -1.0e3_wp, & + 0.0_wp, 0.8_wp, es, em) + CALL require(es == CD_HCDYN_OK, 'model init: '//TRIM(em)) + IF (clamped) THEN + CALL CD_HermiteCable_Dyn_Set_EndConnection(model, [0.0_wp, 0.0_wp], & + RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp], [3, 2]), & + es, em, connection_mode=[CD_ENDCONN_RIGID, CD_ENDCONN_RIGID]) + CALL require(es == CD_HCDYN_OK, 'end connections: '//TRIM(em)) + END IF + IF (.NOT. torsion) RETURN + tors%active = .TRUE. + tors%phi = phi + tors%ends = RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 1.0_wp, 0.0_wp, 0.0_wp, & + 0.0_wp, 0.0_wp, 1.0_wp], [3, 4]) + tors%end_compliance = compliance + ALLOCATE (tors%gj(ne), tors%irn(ne)) + tors%gj = GJ + tors%irn = irn + IF (ABS(ktt) > 0.0_wp) THEN + ALLOCATE (tors%couple(ne)) + tors%couple = ktt/GJ + CALL CD_HermiteTorsion_Line(q, le, tors%ends, raw, g, es, em, couple=tors%couple) + ELSE + CALL CD_HermiteTorsion_Line(q, le, tors%ends, raw, g, es, em) + END IF + CALL require(es == CD_HTORS_OK, 'seed twist: '//TRIM(em)) + tors%theta = CD_HermiteTorsion_Unwrap(raw, 0.0_wp) + tors%has_theta = .TRUE. + CALL CD_HermiteCable_Dyn_Set_Torsion(model, tors, es, em) + CALL require(es == CD_HCDYN_OK .AND. model%tw_active, 'torsion: '//TRIM(em)) + END SUBROUTINE build + + SUBROUTINE modes(model, nm, om, polar, nf, label) + !! The nm lowest modes of model: omega (rad/s) and polar share. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + INTEGER, INTENT(IN) :: nm + REAL(wp), ALLOCATABLE, INTENT(OUT) :: om(:), polar(:) + INTEGER, INTENT(OUT) :: nf + CHARACTER(*), INTENT(IN) :: label + REAL(wp), ALLOCATABLE :: om2(:), sh(:, :) + INTEGER :: es, dpn + CHARACTER(1024) :: em + CALL CD_Modal_Hermite_Line(model, nm, om2, sh, nf, dpn, polar, es, em) + CALL require(es == CD_MODAL_OK .AND. nf == nm, label//': modal solve: '//TRIM(em)) + ALLOCATE (om(MAX(nf, 1))) + om = SQRT(MAX(om2, 0.0_wp)) + END SUBROUTINE modes + + SUBROUTINE old_modes(model, nm, om) + !! The modal route without the twist: CD_Modal_Hermite_Band, the cable's freemask (the end + !! connections ignored), no twist DOFs. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + INTEGER, INTENT(IN) :: nm + REAL(wp), INTENT(OUT) :: om(nm) + REAL(wp), ALLOCATABLE :: kb(:, :), mb(:, :), om2(:), sh(:, :) + INTEGER :: kd, es, nf + CHARACTER(1024) :: em + om = 0.0_wp + CALL CD_Modal_Hermite_Band(model%q, model%l0, model%EA, model%EI, model%rho_a, kd, kb, mb, es, em) + ALLOCATE (om2(nm), sh(model%ndof, nm)) + IF (es == CD_MODAL_OK) CALL CD_Modal_Solve_Band(kb, mb, kd, model%freemask, nm, om2, sh, nf, es, em) + IF (es == CD_MODAL_OK) om = SQRT(MAX(om2, 0.0_wp)) + END SUBROUTINE old_modes + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE gate_t1() + !! T1: rigid torsional ends, Phi = 0, Irn = 0.04 (torsional modes at 14.05 and 28.10 rad/s, + !! between the bending pairs; EA = 1e4 puts the first axial mode at 31.4 rad/s). + INTEGER, PARAMETER :: NE = 40, NM = 13 + REAL(wp), PARAMETER :: IRN = 0.04_wp, EA = 1.0e4_wp + TYPE(CD_HermiteCableDynType) :: mt, mf + REAL(wp), ALLOCATABLE :: om(:), pol(:), omf(:), polf(:) + REAL(wp) :: q(6*(NE + 1)), cont, chain, err_c, err_d, bound, err_nt, mix, oold(NM) + INTEGER :: nf, nff, j, n, jn + CALL straight(NE, 1.0_wp + TENSION/EA, q) + CALL build(mt, NE, q, EA, .TRUE., .TRUE., 0.0_wp, IRN, 0.0_wp, 0.0_wp) + CALL build(mf, NE, q, EA, .TRUE., .FALSE., 0.0_wp, IRN, 0.0_wp, 0.0_wp) + CALL modes(mt, NM, om, pol, nf, 'T1 torsion') + CALL modes(mf, NM, omf, polf, nff, 'T1 free') + IF (nf /= NM .OR. nff /= NM) RETURN + n = 0 + jn = 0 + err_nt = 0.0_wp + mix = 0.0_wp + DO j = 1, NM + IF (pol(j) > 0.5_wp) THEN + n = n + 1 + cont = REAL(n, wp)*PI/L0*SQRT(GJ/IRN) + chain = 2.0_wp*SQRT(GJ/IRN)/(L0/REAL(NE, wp))*SIN(REAL(n, wp)*PI/(2.0_wp*REAL(NE, wp))) + err_c = ABS(om(j)/cont - 1.0_wp) + err_d = ABS(om(j)/chain - 1.0_wp) + bound = 1.0_wp - SIN(REAL(n, wp)*PI/(2.0_wp*REAL(NE, wp)))/(REAL(n, wp)*PI/(2.0_wp*REAL(NE, wp))) + WRITE (*, '(A,I0,A,F10.5,A,F10.5,A,ES9.2,A,ES9.2,A,ES9.2,A,ES9.2)') ' T1 torsional mode ', n, & + ': omega ', om(j), ' continuum ', cont, ' error ', err_c, ' (bound ', 1.01_wp*bound, '), chain error ', & + err_d, ', polar share 1 - ', 1.0_wp - pol(j) + CALL require(err_c <= 1.01_wp*bound + 1.0e-9_wp, 'T1: torsional mode against the continuum') + CALL require(err_d <= 1.0e-9_wp, 'T1: torsional mode against the lumped chain') + CALL require(1.0_wp - pol(j) <= 1.0e-9_wp, 'T1: a torsional mode carries no translation') + ELSE + jn = jn + 1 + IF (jn > nff) CYCLE + err_nt = MAX(err_nt, ABS(om(j)/omf(jn) - 1.0_wp)) + mix = MAX(mix, pol(j)) + END IF + END DO + WRITE (*, '(A,I0,A,ES9.2,A,ES9.2)') ' T1 ', jn, ' bending/axial modes against the line without torsion: ', & + err_nt, ', largest polar share ', mix + CALL require(n == 2, 'T1: two torsional modes among the 13 lowest') + CALL require(err_nt <= 1.0e-9_wp, 'T1: the bending and axial modes are those of the line without torsion') + CALL require(mix <= 1.0e-9_wp, 'T1: the bending and axial modes carry no twist') + CALL old_modes(mt, NM, oold) + WRITE (*, '(A,F10.5,A,F10.5,A)') ' T1 old route: no torsional mode; its first mode ', oold(1), & + ' rad/s against ', omf(1), ' rad/s of the clamped line (end connections ignored)' + CALL CD_HermiteCable_Dyn_End(mt) + CALL CD_HermiteCable_Dyn_End(mf) + END SUBROUTINE gate_t1 + + SUBROUTINE gate_t2() + !! T2: elastic torsional ends k = 2 GJ/L0 at both ends (Phi = 0, Irn = 0.04). + INTEGER, PARAMETER :: NE = 40, NM = 16, NT = 2 + REAL(wp), PARAMETER :: IRN = 0.04_wp, EA = 1.0e4_wp, KT = 2.0_wp*GJ/L0 + TYPE(CD_HermiteCableDynType) :: mt + REAL(wp), ALLOCATABLE :: om(:), pol(:) + REAL(wp) :: q(6*(NE + 1)), cont(NT), chain(NT), err_c, err_d, h + REAL(wp) :: kc(NE + 1, NE + 1), mc(NE + 1, NE + 1), w2(NE + 1), sh(NE + 1, NE + 1) + LOGICAL :: fr(NE + 1) + INTEGER :: nf, j, n, e, es + CHARACTER(512) :: em + CALL straight(NE, 1.0_wp + TENSION/EA, q) + CALL build(mt, NE, q, EA, .TRUE., .TRUE., 0.0_wp, IRN, 1.0_wp/KT, 0.0_wp) + CALL modes(mt, NM, om, pol, nf, 'T2') + IF (nf /= NM) RETURN + ! continuum: ((GJ b)^2 - k^2) sin(b L0) - 2 k GJ b cos(b L0) = 0, bracketed on a fine grid + CALL elastic_roots(KT, IRN, cont) + ! the lumped chain with its end springs (dense reference solve) + h = L0/REAL(NE, wp) + kc = 0.0_wp + mc = 0.0_wp + DO e = 1, NE + kc(e, e) = kc(e, e) + GJ/h + kc(e + 1, e + 1) = kc(e + 1, e + 1) + GJ/h + kc(e, e + 1) = kc(e, e + 1) - GJ/h + kc(e + 1, e) = kc(e + 1, e) - GJ/h + mc(e, e) = mc(e, e) + 0.5_wp*IRN*h + mc(e + 1, e + 1) = mc(e + 1, e + 1) + 0.5_wp*IRN*h + END DO + kc(1, 1) = kc(1, 1) + KT + kc(NE + 1, NE + 1) = kc(NE + 1, NE + 1) + KT + fr = .TRUE. + CALL CD_Modal_Solve(kc, mc, fr, NE + 1, w2, sh, n, es, em) + CALL require(es == CD_MODAL_OK, 'T2: chain reference solve: '//TRIM(em)) + chain = SQRT(w2(1:NT)) + n = 0 + DO j = 1, NM + IF (pol(j) <= 0.5_wp .OR. n >= NT) CYCLE + n = n + 1 + err_c = ABS(om(j)/cont(n) - 1.0_wp) + err_d = ABS(om(j)/chain(n) - 1.0_wp) + WRITE (*, '(A,I0,A,F10.5,A,F10.5,A,ES9.2,A,ES9.2)') ' T2 elastic-end torsional mode ', n, ': omega ', & + om(j), ' continuum ', cont(n), ' error ', err_c, ', lumped chain error ', err_d + CALL require(err_c <= 1.0e-3_wp, 'T2: elastic-end torsional mode against the continuum') + CALL require(err_d <= 1.0e-9_wp, 'T2: elastic-end torsional mode against the lumped chain') + END DO + CALL require(n == NT, 'T2: two torsional modes found') + CALL CD_HermiteCable_Dyn_End(mt) + END SUBROUTINE gate_t2 + + SUBROUTINE elastic_roots(kt, irn, roots) + !! The lowest roots b of ((GJ b)^2 - k^2) sin(b L0) - 2 k GJ b cos(b L0), as omega. + REAL(wp), INTENT(IN) :: kt, irn + REAL(wp), INTENT(OUT) :: roots(:) + INTEGER, PARAMETER :: NGRID = 20000 + REAL(wp) :: b0, b1, f0, f1, bm, fm + INTEGER :: i, n, it + n = 0 + b0 = 1.0e-6_wp + f0 = elastic_char(kt, b0) + DO i = 1, NGRID + b1 = REAL(i, wp)*(REAL(SIZE(roots) + 1, wp)*PI/L0)/REAL(NGRID, wp) + f1 = elastic_char(kt, b1) + IF (f0*f1 < 0.0_wp) THEN + DO it = 1, 200 + bm = 0.5_wp*(b0 + b1) + fm = elastic_char(kt, bm) + IF (fm*f0 > 0.0_wp) THEN + b0 = bm + f0 = fm + ELSE + b1 = bm + END IF + END DO + n = n + 1 + roots(n) = 0.5_wp*(b0 + b1)*SQRT(GJ/irn) + IF (n == SIZE(roots)) RETURN + b1 = REAL(i, wp)*(REAL(SIZE(roots) + 1, wp)*PI/L0)/REAL(NGRID, wp) + f1 = elastic_char(kt, b1) + END IF + b0 = b1 + f0 = f1 + END DO + END SUBROUTINE elastic_roots + + REAL(wp) FUNCTION elastic_char(kt, b) RESULT(f) + !! ((GJ b)^2 - k^2) sin(b L0) - 2 k GJ b cos(b L0): zero at a torsional mode with end springs k. + REAL(wp), INTENT(IN) :: kt, b + f = ((GJ*b)**2 - kt**2)*SIN(b*L0) - 2.0_wp*kt*GJ*b*COS(b*L0) + END FUNCTION elastic_char + + SUBROUTINE gate_t3() + !! T3: torque-tension coupling K = 300 N m (K^2 < EA GJ), Phi = 0, Irn = 0.04: the coupled + !! axial-torsional modes of the clamped (axially and torsionally held) bar. + INTEGER, PARAMETER :: NE = 60, NM = 24, NT = 4 + REAL(wp), PARAMETER :: IRN = 0.04_wp, EA = 1.0e4_wp, KTT = 300.0_wp + TYPE(CD_HermiteCableDynType) :: mt + REAL(wp), ALLOCATABLE :: om(:), pol(:) + REAL(wp) :: q(6*(NE + 1)), tr, det, c2(2), ref(2*NT), err, bound, x + INTEGER :: nf, j, n, i + CALL straight(NE, 1.0_wp + TENSION/EA, q) + CALL build(mt, NE, q, EA, .TRUE., .TRUE., 0.0_wp, IRN, 0.0_wp, KTT) + CALL modes(mt, NM, om, pol, nf, 'T3') + IF (nf /= NM) RETURN + ! eig(diag(m, Irn)^-1 [[EA, K], [K, GJ]]): the two wave speeds squared + tr = EA/RHOA + GJ/IRN + det = (EA*GJ - KTT**2)/(RHOA*IRN) + c2(1) = 0.5_wp*(tr - SQRT(tr*tr - 4.0_wp*det)) + c2(2) = 0.5_wp*(tr + SQRT(tr*tr - 4.0_wp*det)) + DO i = 1, NT + ref(2*i - 1) = REAL(i, wp)*PI/L0*SQRT(c2(1)) + ref(2*i) = REAL(i, wp)*PI/L0*SQRT(c2(2)) + END DO + CALL sort(ref) + n = 0 + DO j = 1, NM + IF (pol(j) <= 1.0e-6_wp) CYCLE + n = n + 1 + IF (n > NT) EXIT + err = ABS(om(j)/ref(n) - 1.0_wp) + ! the lumped twist's error 1 - sin(x)/x, x = n pi/(2 NE), at the mode's larger wavenumber + ! (the slow family's, n omega/c_slow) bounds the coupled one + x = REAL(CEILING(ref(n)/SQRT(c2(1))*L0/PI - 1.0e-9_wp), wp)*PI/(2.0_wp*REAL(NE, wp)) + bound = 1.0_wp - SIN(x)/x + WRITE (*, '(A,I0,A,F10.5,A,F10.5,A,ES9.2,A,ES9.2,A,F6.3)') ' T3 coupled axial-torsional mode ', n, & + ': omega ', om(j), ' continuum ', ref(n), ' error ', err, ' (bound ', bound, '), polar share ', pol(j) + CALL require(err <= bound + 1.0e-6_wp, 'T3: coupled axial-torsional mode against the continuum') + CALL require(pol(j) > 0.01_wp .AND. pol(j) < 0.99_wp, 'T3: the coupling mixes stretch and twist') + END DO + CALL require(n >= NT, 'T3: four coupled modes found') + CALL CD_HermiteCable_Dyn_End(mt) + END SUBROUTINE gate_t3 + + SUBROUTINE sort(x) + REAL(wp), INTENT(INOUT) :: x(:) + INTEGER :: i, j + REAL(wp) :: t + DO i = 2, SIZE(x) + DO j = i, 2, -1 + IF (x(j) >= x(j - 1)) EXIT + t = x(j) + x(j) = x(j - 1) + x(j - 1) = t + END DO + END DO + END SUBROUTINE sort + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE gate_c1() + !! C1: the straight taut clamped line (T = 10 N, EA = 1e4) under M = 4 EI/L0 = 40 N m with a + !! negligible Irn = 1e-6 (torsional modes above 2800 rad/s), against the Greenhill-cable + !! determinant; the untwisted line (Phi = 0) against the same determinant at M = 0. + INTEGER, PARAMETER :: NE = 100, NROOT = 4, NM = 2*NROOT + REAL(wp), PARAMETER :: EA = 1.0e4_wp, MT = 40.0_wp, IRN = 1.0e-6_wp + TYPE(CD_HermiteCableDynType) :: m1, m0 + REAL(wp), ALLOCATABLE :: om(:), pol(:), om0(:), pol0(:) + REAL(wp) :: q(6*(NE + 1)), lam, ref(NROOT), ref0(NROOT), err, err0, pair, shift_fe, shift_th, oold(NM), mt_model + INTEGER :: nf, nf0, j + lam = 1.0_wp + TENSION/EA + CALL straight(NE, lam, q) + CALL build(m1, NE, q, EA, .TRUE., .TRUE., MT*L0/GJ, IRN, 0.0_wp, 0.0_wp) + CALL build(m0, NE, q, EA, .TRUE., .TRUE., 0.0_wp, IRN, 0.0_wp, 0.0_wp) + mt_model = m1%torsion%torque + WRITE (*, '(A,F12.8,A)') ' C1 torque of the twisted state ', mt_model, ' N m' + CALL require(ABS(mt_model - MT) <= 1.0e-9_wp*MT, 'C1: the twisted state carries M = Phi GJ/L0') + CALL modes(m1, NM, om, pol, nf, 'C1 twisted') + CALL modes(m0, NM, om0, pol0, nf0, 'C1 untwisted') + IF (nf /= NM .OR. nf0 /= NM) RETURN + CALL greenhill_roots(EI/lam**4, MT/lam**2, TENSION/lam, NROOT, ref) + CALL greenhill_roots(EI/lam**4, 0.0_wp, TENSION/lam, NROOT, ref0) + DO j = 1, NROOT + err = MAX(ABS(om(2*j - 1)/ref(j) - 1.0_wp), ABS(om(2*j)/ref(j) - 1.0_wp)) + err0 = MAX(ABS(om0(2*j - 1)/ref0(j) - 1.0_wp), ABS(om0(2*j)/ref0(j) - 1.0_wp)) + pair = ABS(om(2*j)/om(2*j - 1) - 1.0_wp) + shift_th = ref(j)/ref0(j) - 1.0_wp + shift_fe = 0.5_wp*(om(2*j - 1) + om(2*j))/(0.5_wp*(om0(2*j - 1) + om0(2*j))) - 1.0_wp + WRITE (*, '(A,I0,A,F10.6,A,F10.6,A,ES9.2,A,ES9.2,A,F8.4,A,F8.4,A)') ' C1 lateral pair ', j, ': omega ', & + om(2*j - 1), ' Greenhill cable ', ref(j), ' error ', err, ' (untwisted ', err0, '), shift ', & + 100.0_wp*shift_fe, ' % (theory ', 100.0_wp*shift_th, ' %)' + CALL require(err <= 1.0e-6_wp, 'C1: lateral frequency under torque against the Greenhill cable') + CALL require(err0 <= 1.0e-6_wp, 'C1: untwisted lateral frequency against the clamped tensioned beam') + CALL require(pair <= 1.0e-8_wp, 'C1: the lateral modes under torque come in pairs') + CALL require(shift_th < 0.0_wp .AND. ABS(shift_fe - shift_th) <= 1.0e-4_wp*ABS(shift_th), & + 'C1: the torque lowers the frequency by the shift theory gives') + CALL require(MAXVAL(pol(2*j - 1:2*j)) <= 1.0e-9_wp, 'C1: the lateral modes carry no twist') + END DO + CALL old_modes(m1, NM, oold) + WRITE (*, '(A,ES9.2,A)') ' C1 old route (pinned, untwisted): first lateral pair error ', & + ABS(oold(1)/ref(1) - 1.0_wp), ' against the Greenhill cable' + CALL CD_HermiteCable_Dyn_End(m1) + CALL CD_HermiteCable_Dyn_End(m0) + END SUBROUTINE gate_c1 + + SUBROUTINE greenhill_roots(eie, me, te, nroot, om) + !! The nroot lowest omega of the clamped Greenhill cable eie u'''' - i me u''' - te u'' = m omega^2 u + !! on [0, L0]: sign changes of Im(D exp(-i L0 sum k/2)) over omega^2, refined by bisection. + REAL(wp), INTENT(IN) :: eie, me, te + INTEGER, INTENT(IN) :: nroot + REAL(wp), INTENT(OUT) :: om(nroot) + INTEGER, PARAMETER :: NGRID = 40000 + REAL(wp) :: lmax, l0g, l1g, f0, f1, lm, fm, re_max, im_max + COMPLEX(wp) :: d + INTEGER :: i, n, it + ! an upper bound of the nroot-th root: the clamped beam's (n + 1/2) pi/L0 wavenumber with + ! tension, enlarged + lmax = 2.0_wp*(eie*((REAL(nroot, wp) + 0.5_wp)*PI/L0)**4 + te*((REAL(nroot, wp) + 0.5_wp)*PI/L0)**2)/RHOA + re_max = 0.0_wp + im_max = 0.0_wp + n = 0 + om = 0.0_wp + l0g = 1.0e-9_wp*lmax + d = det_norm(eie, me, te, RHOA*l0g) + f0 = AIMAG(d) + DO i = 1, NGRID + l1g = lmax*REAL(i, wp)/REAL(NGRID, wp) + d = det_norm(eie, me, te, RHOA*l1g) + re_max = MAX(re_max, ABS(REAL(d, wp))) + im_max = MAX(im_max, ABS(AIMAG(d))) + f1 = AIMAG(d) + IF (f0*f1 < 0.0_wp .AND. n < nroot) THEN + DO it = 1, 200 + lm = 0.5_wp*(l0g + l1g) + fm = AIMAG(det_norm(eie, me, te, RHOA*lm)) + IF (fm*f0 > 0.0_wp) THEN + l0g = lm + f0 = fm + ELSE + l1g = lm + END IF + END DO + n = n + 1 + om(n) = SQRT(0.5_wp*(l0g + l1g)) + l1g = lmax*REAL(i, wp)/REAL(NGRID, wp) + f1 = AIMAG(det_norm(eie, me, te, RHOA*l1g)) + END IF + l0g = l1g + f0 = f1 + END DO + CALL require(n == nroot, 'C1: the Greenhill determinant has the expected roots') + ! the normalised determinant is purely imaginary (the oracle's own consistency) + CALL require(re_max <= 1.0e-8_wp*im_max, 'C1: the normalised Greenhill determinant is imaginary') + END SUBROUTINE greenhill_roots + + COMPLEX(wp) FUNCTION det_norm(eie, me, te, lambda) RESULT(dn) + !! The clamped-clamped determinant of the Greenhill cable at m omega^2 = lambda, times + !! exp(-i L0 sum k_j/2): rows u(0), u'(0)/i, u(L0), u'(L0)/i of the four exp(i k_j s0). + REAL(wp), INTENT(IN) :: eie, me, te, lambda + COMPLEX(wp) :: k(4), a(4, 4) + INTEGER :: j + CALL quartic_roots([CMPLX(-lambda/eie, 0.0_wp, wp), (0.0_wp, 0.0_wp), CMPLX(te/eie, 0.0_wp, wp), & + CMPLX(-me/eie, 0.0_wp, wp)], k) + DO j = 1, 4 + a(1, j) = (1.0_wp, 0.0_wp) + a(2, j) = k(j) + a(3, j) = EXP((0.0_wp, 1.0_wp)*k(j)*L0) + a(4, j) = k(j)*a(3, j) + END DO + dn = det4(a)*EXP(-(0.0_wp, 0.5_wp)*L0*SUM(k)) + END FUNCTION det_norm + + SUBROUTINE quartic_roots(c, z) + !! Roots of z^4 + c(4) z^3 + c(3) z^2 + c(2) z + c(1) (Durand-Kerner, then Newton polish). + COMPLEX(wp), INTENT(IN) :: c(4) + COMPLEX(wp), INTENT(OUT) :: z(4) + COMPLEX(wp) :: den, dz, p, dp + REAL(wp) :: r + INTEGER :: it, i, j + r = 1.0_wp + MAXVAL(ABS(c)) + DO i = 1, 4 + z(i) = r*(0.4_wp, 0.9_wp)**i + END DO + DO it = 1, 2000 + dz = (0.0_wp, 0.0_wp) + DO i = 1, 4 + den = (1.0_wp, 0.0_wp) + DO j = 1, 4 + IF (j /= i) den = den*(z(i) - z(j)) + END DO + p = (((z(i) + c(4))*z(i) + c(3))*z(i) + c(2))*z(i) + c(1) + z(i) = z(i) - p/den + dz = dz + ABS(p/den) + END DO + IF (ABS(dz) <= 1.0e-15_wp*r) EXIT + END DO + DO i = 1, 4 + DO it = 1, 3 + p = (((z(i) + c(4))*z(i) + c(3))*z(i) + c(2))*z(i) + c(1) + dp = ((4.0_wp*z(i) + 3.0_wp*c(4))*z(i) + 2.0_wp*c(3))*z(i) + c(2) + IF (ABS(dp) > 0.0_wp) z(i) = z(i) - p/dp + END DO + END DO + END SUBROUTINE quartic_roots + + COMPLEX(wp) FUNCTION det4(a0) RESULT(d) + !! Determinant of a complex 4 x 4 matrix (Gaussian elimination, partial pivoting). + COMPLEX(wp), INTENT(IN) :: a0(4, 4) + COMPLEX(wp) :: a(4, 4), t(4), f + INTEGER :: i, j, p + a = a0 + d = (1.0_wp, 0.0_wp) + DO j = 1, 4 + p = j - 1 + MAXLOC(ABS(a(j:4, j)), 1) + IF (p /= j) THEN + t = a(j, :) + a(j, :) = a(p, :) + a(p, :) = t + d = -d + END IF + d = d*a(j, j) + IF (.NOT. ABS(a(j, j)) > 0.0_wp) RETURN + DO i = j + 1, 4 + f = a(i, j)/a(j, j) + a(i, j:4) = a(i, j:4) - f*a(j, j:4) + END DO + END DO + END FUNCTION det4 + + ! ------------------------------------------------------------------------------------------ + SUBROUTINE gate_c2(label, clamped, compliance, ktt) + !! C2: Schur complement of the twist angles against the condensed static tangent, analytic + !! and by central differences of the condensed static residual, on the bowed line (NE = 12, + !! Phi = 1 rad, Irn = 1). + CHARACTER(*), INTENT(IN) :: label + LOGICAL, INTENT(IN) :: clamped + REAL(wp), INTENT(IN) :: compliance, ktt + INTEGER, PARAMETER :: NE = 12, NN = NE + 1, N6 = 6*NN, N7 = 7*NN + REAL(wp), PARAMETER :: EA = 1.0e4_wp, PHI = 1.0_wp + TYPE(CD_HermiteCableDynType) :: model + REAL(wp), ALLOCATABLE :: kb(:, :), mb(:, :) + LOGICAL, ALLOCATABLE :: free(:) + REAL(wp) :: q(N6), k7(N7, N7), kc(N6, N6), kel(N6, N6), tr(N6, N6), s(N6, N6), dq(N6), dl(N6), gp(N6) + REAL(wp) :: gm(N6), fd(N6) + REAL(wp) :: sd(N6), kpp(NN, NN), kpq(NN, N6), x(NN, N6), basis(3, 3), h, err_a, err_f, scale, old_err, g0 + INTEGER, ALLOCATABLE :: iq(:), ip(:) + LOGICAL :: qfree(N6) + INTEGER :: kd, dpn, es, i, j, nq, np, i6, iend, b0, seed + CHARACTER(1024) :: em + CALL bowed(NE, q) + CALL build(model, NE, q, EA, clamped, .TRUE., PHI, 1.0_wp, compliance, ktt) + IF (.NOT. model%tw_active) RETURN + CALL CD_Modal_Hermite_Line_Band(model, kd, kb, mb, free, dpn, es, em) + CALL require(es == CD_MODAL_OK .AND. dpn == 7, 'C2 '//label//': band: '//TRIM(em)) + IF (es /= CD_MODAL_OK) RETURN + k7 = 0.0_wp + DO j = 1, N7 + DO i = MAX(1, j - kd), j + k7(i, j) = kb(kd + 1 + i - j, j) + k7(j, i) = k7(i, j) + END DO + END DO + ! free q DOFs (cable numbering) and free angles + DO i6 = 1, N6 + qfree(i6) = free(i6 + (i6 - 1)/6) + END DO + nq = COUNT(qfree) + np = COUNT(free(7:N7:7)) + ALLOCATE (iq(nq), ip(np)) + iq = PACK([(i6, i6=1, N6)], qfree) + ip = PACK([(i, i=1, NN)], free(7:N7:7)) + ! Schur complement on the free set: S = K_qq - K_qp K_pp^-1 K_pq + DO j = 1, np + DO i = 1, np + kpp(i, j) = k7(7*ip(i), 7*ip(j)) + END DO + DO i = 1, nq + kpq(j, i) = k7(7*ip(j), iq(i) + (iq(i) - 1)/6) + END DO + END DO + x(1:np, 1:nq) = kpq(1:np, 1:nq) + CALL spd_solve(kpp(1:np, 1:np), x(1:np, 1:nq)) + s = 0.0_wp + DO j = 1, nq + DO i = 1, nq + s(iq(i), iq(j)) = k7(iq(i) + (iq(i) - 1)/6, iq(j) + (iq(j) - 1)/6) - DOT_PRODUCT(kpq(1:np, i), x(1:np, j)) + END DO + END DO + ! the rigid ends' basis (identity elsewhere) + tr = 0.0_wp + DO i = 1, N6 + tr(i, i) = 1.0_wp + END DO + IF (clamped) THEN + DO iend = 1, 2 + CALL CD_EndConn_Basis(model%endconn_d0(:, iend), basis, es, em) + b0 = 6*(MERGE(1, NN, iend == 1) - 1) + 3 + tr(b0 + 1:b0 + 3, b0 + 1:b0 + 3) = basis + END DO + END IF + ! the condensed static tangent in the same coordinates + CALL condensed(model, q, kc, g0, kel) + kc = MATMUL(TRANSPOSE(tr), MATMUL(kc, tr)) + kel = MATMUL(TRANSPOSE(tr), MATMUL(kel, tr)) + scale = 0.0_wp + err_a = 0.0_wp + old_err = 0.0_wp + DO j = 1, nq + DO i = 1, nq + scale = MAX(scale, ABS(kc(iq(i), iq(j)))) + err_a = MAX(err_a, ABS(s(iq(i), iq(j)) - kc(iq(i), iq(j)))) + old_err = MAX(old_err, ABS(kel(iq(i), iq(j)) - kc(iq(i), iq(j)))) + END DO + END DO + err_a = err_a/scale + ! central differences of the condensed residual along a pseudo-random free direction + seed = 4242 + dl = 0.0_wp + DO i = 1, nq + seed = MOD(69069*seed + 1, 2147483647) + dl(iq(i)) = REAL(MOD(seed, 2001) - 1000, wp)/1000.0_wp + END DO + dq = MATMUL(tr, dl) + h = 1.0e-6_wp + CALL condensed_residual(model, q + h*dq, gp) + CALL condensed_residual(model, q - h*dq, gm) + fd = MATMUL(TRANSPOSE(tr), (gp - gm)/(2.0_wp*h)) + sd = MATMUL(s, dl) + err_f = 0.0_wp + DO i = 1, nq + err_f = MAX(err_f, ABS(fd(iq(i)) - sd(iq(i)))) + END DO + err_f = err_f/MAX(nan_max_abs(sd), TINY(1.0_wp)) + WRITE (*, '(A,A,A,F9.4,A,ES9.2,A,ES9.2,A,ES9.2)') ' C2 ', label, ': torque ', model%torsion%torque, & + ' N m; Schur complement against the condensed tangent ', err_a, ', against central differences ', err_f, & + '; old route (no twist) ', old_err/scale + CALL require(err_a <= 1.0e-9_wp, 'C2 '//label//': Schur complement against the condensed static tangent') + CALL require(err_f <= 1.0e-6_wp, 'C2 '//label//': Schur complement against the condensed residual') + CALL CD_HermiteCable_Dyn_End(model) + END SUBROUTINE gate_c2 + + SUBROUTINE gate_e() + !! E: finite bending springs k at both ends, between pinned and clamped. + INTEGER, PARAMETER :: NE = 40, NK = 4 + REAL(wp), PARAMETER :: EA = 1.0e4_wp + REAL(wp), PARAMETER :: KS(NK) = [1.0e-1_wp, 1.0e1_wp, 1.0e3_wp, 1.0e5_wp]*EI/L0 + TYPE(CD_HermiteCableDynType) :: mp, mc, mk + REAL(wp), ALLOCATABLE :: om(:), pol(:) + REAL(wp) :: q(6*(NE + 1)), w_pin, w_clamp, w_prev + INTEGER :: nf, i, es + CHARACTER(512) :: em + LOGICAL :: ordered + CALL straight(NE, 1.0_wp + TENSION/EA, q) + CALL build(mp, NE, q, EA, .FALSE., .FALSE., 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp) + CALL build(mc, NE, q, EA, .TRUE., .FALSE., 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp) + CALL modes(mp, 2, om, pol, nf, 'E pinned') + w_pin = om(1) + CALL modes(mc, 2, om, pol, nf, 'E clamped') + w_clamp = om(1) + w_prev = w_pin + ordered = .TRUE. + DO i = 1, NK + CALL build(mk, NE, q, EA, .FALSE., .FALSE., 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp) + CALL CD_HermiteCable_Dyn_Set_EndConnection(mk, [KS(i), KS(i)], & + RESHAPE([1.0_wp, 0.0_wp, 0.0_wp, 1.0_wp, 0.0_wp, 0.0_wp], [3, 2]), & + es, em, connection_mode=[CD_ENDCONN_FINITE, CD_ENDCONN_FINITE]) + CALL require(es == CD_HCDYN_OK, 'E: finite end connections: '//TRIM(em)) + CALL modes(mk, 2, om, pol, nf, 'E finite') + WRITE (*, '(A,ES9.2,A,F10.6,A,F10.6,A,F10.6,A)') ' E end springs k L0/EI = ', KS(i)*L0/EI, ': omega_1 ', & + om(1), ' (pinned ', w_pin, ', clamped ', w_clamp, ')' + ordered = ordered .AND. om(1) > w_prev .AND. om(1) < w_clamp + w_prev = om(1) + CALL CD_HermiteCable_Dyn_End(mk) + END DO + CALL require(ordered, 'E: the end springs put the frequency between pinned and clamped, rising with k') + CALL require(ABS(w_prev/w_clamp - 1.0_wp) <= 1.0e-4_wp, 'E: a stiff end spring approaches the clamp') + CALL CD_HermiteCable_Dyn_End(mp) + CALL CD_HermiteCable_Dyn_End(mc) + END SUBROUTINE gate_e + + SUBROUTINE condensed(model, qc, kc, mt, kel) + !! The condensed static tangent at qc: the element Hessians (kel) + M_t d2(-Theta)/dq2 + + !! (1/C) g g^T, M_t = (Phi - Theta)/C (Theta unwrapped against the model's accepted value). + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + REAL(wp), INTENT(IN) :: qc(:) + REAL(wp), INTENT(OUT) :: kc(:, :), mt, kel(:, :) + REAL(wp) :: ee, fe(12), ke(12, 12), raw, th, c, g(SIZE(qc)), hb(2*CD_HTORS_KBAND + 1, SIZE(qc)) + INTEGER :: e, es, i, j, n + CHARACTER(512) :: em + n = SIZE(qc) + kc = 0.0_wp + DO e = 1, model%ne + CALL CD_HermiteCable_Element(qc(6*e - 5:6*e + 6), model%l0(e), model%EA(e), model%EI(e), ee, fe, ke, es, em) + kc(6*e - 5:6*e + 6, 6*e - 5:6*e + 6) = kc(6*e - 5:6*e + 6, 6*e - 5:6*e + 6) + ke + END DO + hb = 0.0_wp + IF (ALLOCATED(model%torsion%couple)) THEN + CALL CD_HermiteTorsion_Line(qc, model%l0, model%torsion%ends, raw, g, es, em, hband=hb, & + couple=model%torsion%couple) + ELSE + CALL CD_HermiteTorsion_Line(qc, model%l0, model%torsion%ends, raw, g, es, em, hband=hb) + END IF + CALL require(es == CD_HTORS_OK, 'C2: condensed twist: '//TRIM(em)) + kel = kc + th = CD_HermiteTorsion_Unwrap(raw, model%torsion%theta) + c = CD_HermiteTorsion_Compliance(model%torsion, model%l0) + mt = (model%torsion%phi - th)/c + DO j = 1, n + DO i = MAX(1, j - CD_HTORS_KBAND), MIN(n, j + CD_HTORS_KBAND) + kc(i, j) = kc(i, j) - mt*hb(CD_HTORS_KBAND + 1 + i - j, j) + END DO + kc(:, j) = kc(:, j) + g*g(j)/c + END DO + END SUBROUTINE condensed + + SUBROUTINE condensed_residual(model, qc, r) + !! The condensed static residual (no external load): sum_e f_int - M_t dTheta/dq. + TYPE(CD_HermiteCableDynType), INTENT(IN) :: model + REAL(wp), INTENT(IN) :: qc(:) + REAL(wp), INTENT(OUT) :: r(:) + REAL(wp) :: ee, fe(12), raw, th, c, g(SIZE(qc)) + INTEGER :: e, es + CHARACTER(512) :: em + r = 0.0_wp + DO e = 1, model%ne + CALL CD_HermiteCable_Element(qc(6*e - 5:6*e + 6), model%l0(e), model%EA(e), model%EI(e), ee, fe, & + ErrStat=es, ErrMsg=em) + r(6*e - 5:6*e + 6) = r(6*e - 5:6*e + 6) + fe + END DO + IF (ALLOCATED(model%torsion%couple)) THEN + CALL CD_HermiteTorsion_Line(qc, model%l0, model%torsion%ends, raw, g, es, em, couple=model%torsion%couple) + ELSE + CALL CD_HermiteTorsion_Line(qc, model%l0, model%torsion%ends, raw, g, es, em) + END IF + th = CD_HermiteTorsion_Unwrap(raw, model%torsion%theta) + c = CD_HermiteTorsion_Compliance(model%torsion, model%l0) + r = r - (model%torsion%phi - th)/c*g + END SUBROUTINE condensed_residual + + SUBROUTINE spd_solve(a, b) + !! b <- a^-1 b for a small symmetric positive definite a (Cholesky). + REAL(wp), INTENT(IN) :: a(:, :) + REAL(wp), INTENT(INOUT) :: b(:, :) + REAL(wp) :: l(SIZE(a, 1), SIZE(a, 1)) + INTEGER :: n, i, j + n = SIZE(a, 1) + l = 0.0_wp + DO j = 1, n + l(j, j) = SQRT(a(j, j) - DOT_PRODUCT(l(j, 1:j - 1), l(j, 1:j - 1))) + DO i = j + 1, n + l(i, j) = (a(i, j) - DOT_PRODUCT(l(i, 1:j - 1), l(j, 1:j - 1)))/l(j, j) + END DO + END DO + DO j = 1, SIZE(b, 2) + DO i = 1, n + b(i, j) = (b(i, j) - DOT_PRODUCT(l(i, 1:i - 1), b(1:i - 1, j)))/l(i, i) + END DO + DO i = n, 1, -1 + b(i, j) = (b(i, j) - DOT_PRODUCT(l(i + 1:n, i), b(i + 1:n, j)))/l(i, i) + END DO + END DO + END SUBROUTINE spd_solve + +END PROGRAM test_modal_torsion diff --git a/tests/test_modal_torsion_deck.py b/tests/test_modal_torsion_deck.py new file mode 100644 index 00000000..092ac0fd --- /dev/null +++ b/tests/test_modal_torsion_deck.py @@ -0,0 +1,218 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +# Copyright (c) 2026 Jae Hoon Seo, SMI Lab, Inha University +"""Driver gates of the modal analysis (OPTION nModes) of finite-EI lines restrained in torsion. + +1. A straight taut 10 m line (neutrally buoyant, no added mass), clamped (bending Rigid) and + rigid in torsion at both ends, 40 elements: its four torsional modes among the 24 lowest + (PolarShare > 0.5) are the lumped chain's 2 sqrt(GJ/Irn)/l0 sin(n pi/(2 NE)) and the + continuum's n pi/L0 sqrt(GJ/Irn) within the chain's own error 1 - sin(x)/x, + x = n pi/(2 NE); the first one's dTwist is sin(pi s/L0) with no translation; every other + mode (bending, axial) has the frequency of the same deck with TorsStiffness Free and no + twist. "Exact" comparisons allow 2e-8, the rounding of the table's nine digits. Turned 30 + degrees about +z, the line has the same frequencies, and the table its positions in the + deck's axes. +2. tests/data/torsion_lazy_wave_modes.dat, the lazy wave twisted two turns, runs its modes: + 12 ascending, finite frequencies with PolarShare in [0, 1] and a dTwist column. +Both fail closed on a driver that refuses nModes with torsion. +""" + +from __future__ import annotations + +import argparse +import math +import subprocess +from pathlib import Path + +L0, NE, EA, EI, GJ, IRN, TENSION = 10.0, 40, 1.0e6, 100.0, 80.0, 0.04, 1000.0 +RHO_W, DIAM = 1025.0, 0.1 +N_MODES = 24 +# the table writes nine significant digits +REL_EXACT = 2.0e-8 + + +def straight_deck(torsion: str, heading_deg: float = 0.0) -> str: + mass = RHO_W * math.pi * DIAM**2 / 4.0 # neutrally buoyant: the line stays straight + span = L0 * (1.0 + TENSION / EA) + c, s = math.cos(math.radians(heading_deg)), math.sin(math.radians(heading_deg)) + bar = "-" * 21 + return f"""{bar} CableDyn Input File {bar} +straight taut line clamped and restrained in torsion ({torsion}) at both ends +{bar} LINE TYPES {bar} +Name Diam Mass EA BA EI GAs GJ Irt Irn Cdn Cdt Can Cat +cab {DIAM!r} {mass!r} {EA!r} 0.0 {EI!r} 1.0e8 {GJ!r} 1.0 {IRN!r} 1.2 0.0 0.0 0.0 +{bar} POINTS {bar} +ID Type X Y Z +1 Coupled 0.0 0.0 -100.0 +2 Fixed {span * c!r} {span * s!r} -100.0 +{bar} LINES {bar} +ID NodeA NodeB Outputs +1 1 2 - +{bar} SECTIONS {bar} +LineID LineType Length NumSegs +1 cab {L0!r} {NE} +{bar} END CONNECTIONS {bar} +LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist +1 A Rigid {c!r} {s!r} 0 {torsion} 0 0 1 0 +1 B Rigid {c!r} {s!r} 0 {torsion} 0 0 1 0 +{bar} OPTIONS {bar} +9.80665 g +{RHO_W!r} rhoW +500.0 WtrDpth +0.01 dtM +0.01 TMax +{N_MODES} nModes +{bar} OUTPUTS {bar} +FairTen1 +{bar} need this line {bar} +""" + + +def read_modes(path: Path) -> tuple[list[str], list[list[float]], list[str], list[list[float]]]: + """The frequency and mode-shape tables of a .modes.out file: (header, rows) for each.""" + lines = path.read_text(encoding="utf-8").splitlines() + tables: list[tuple[list[str], list[list[float]]]] = [] + i = 0 + while i < len(lines): + if lines[i].startswith("# Natural frequencies") or lines[i].startswith("# Mode shapes"): + header = lines[i + 1].split("\t") + rows = [] + j = i + 3 + while j < len(lines) and not lines[j].startswith("#"): + rows.append([float(x) for x in lines[j].split("\t")]) + j += 1 + tables.append((header, rows)) + i = j + else: + i += 1 + if len(tables) != 2: + raise AssertionError(f"{path}: expected two tables, found {len(tables)}") + return tables[0][0], tables[0][1], tables[1][0], tables[1][1] + + +def run(exe: str, deck: Path, root: Path) -> Path: + proc = subprocess.run([exe, str(deck), str(root)], capture_output=True, text=True, check=False) + if proc.returncode != 0: + raise AssertionError(f"{deck.name}: driver exit {proc.returncode}\n{proc.stdout}\n{proc.stderr}") + return root.with_name(root.name + ".modes.out") + + +def check_straight(exe: str, out: Path) -> list[str]: + failures: list[str] = [] + files = {} + for torsion in ("Rigid", "Free"): + deck = out / f"straight_{torsion.lower()}.dat" + deck.write_text(straight_deck(torsion), encoding="utf-8") + files[torsion] = run(exe, deck, out / f"straight_{torsion.lower()}") + fh, freq, sh, shapes = read_modes(files["Rigid"]) + fh0, freq0, _, _ = read_modes(files["Free"]) + if fh[-1] != "PolarShare" or sh[-1] != "dTwist": + failures.append(f"torsion deck: no PolarShare/dTwist columns ({fh}, {sh})") + return failures + if "PolarShare" in fh0: + failures.append("the TorsStiffness Free deck writes twist columns") + omega = [row[4] for row in freq] + polar = [row[5] for row in freq] + omega0 = [row[4] for row in freq0] + l0 = L0 / NE + n = 0 + other = [] + for j, (om, share) in enumerate(zip(omega, polar), start=1): + if share > 0.5: + n += 1 + x = n * math.pi / (2.0 * NE) + chain = 2.0 * math.sqrt(GJ / IRN) / l0 * math.sin(x) + cont = n * math.pi / L0 * math.sqrt(GJ / IRN) + err_d, err_c = abs(om / chain - 1.0), abs(om / cont - 1.0) + bound = 1.0 - math.sin(x) / x + print( + f" torsional mode {n} (mode {j}): omega {om:.6f} rad/s, continuum {cont:.6f}, error " + f"{err_c:.2e} (bound {1.01 * bound:.2e}), chain error {err_d:.2e}, polar share 1 - {1 - share:.1e}" + ) + if err_d > REL_EXACT or err_c > 1.01 * bound + REL_EXACT or 1.0 - share > REL_EXACT: + failures.append(f"torsional mode {n}: omega {om} against chain {chain}, continuum {cont}") + if n == 1: + rows = [r for r in shapes if int(r[1]) == j] + twist = [r[9] for r in rows] + trans = max(abs(v) for r in rows for v in r[6:9]) + ref = [math.sin(math.pi * k / NE) for k in range(NE + 1)] + sign = 1.0 if twist[NE // 2] > 0.0 else -1.0 + err_s = max(abs(sign * t - r) for t, r in zip(twist, ref)) + print(f" torsional mode 1 shape: dTwist against sin(pi s/L0) {err_s:.2e}, translations {trans:.1e}") + if err_s > 1.0e-6 or trans > REL_EXACT: + failures.append(f"torsional mode 1 shape: {err_s}, translations {trans}") + else: + other.append((om, share)) + err_o = max(abs(om / om0 - 1.0) for (om, _), om0 in zip(other, omega0)) + mix = max(share for _, share in other) + print( + f" {len(other)} bending/axial modes against TorsStiffness Free: {err_o:.2e}, largest polar share {mix:.1e}" + ) + if n != 4: + failures.append(f"expected 4 torsional modes among the {N_MODES} lowest, found {n}") + if err_o > REL_EXACT or mix > REL_EXACT: + failures.append(f"bending/axial modes differ from the Free deck by {err_o} (polar share {mix})") + # the same line turned 30 degrees about +z: the same frequencies, positions in the deck's axes + deck = out / "straight_heading.dat" + deck.write_text(straight_deck("Rigid", 30.0), encoding="utf-8") + _, freq_h, _, shapes_h = read_modes(run(exe, deck, out / "straight_heading")) + err_h = max(abs(a[4] / b[4] - 1.0) for a, b in zip(freq_h, freq)) + c, s = math.cos(math.radians(30.0)), math.sin(math.radians(30.0)) + span = L0 * (1.0 + TENSION / EA) + rows = [r for r in shapes_h if int(r[1]) == 1] + err_x = max( + abs(r[3] - span * c * k / NE) + abs(r[4] - span * s * k / NE) for k, r in enumerate(rows) + ) + # the first mode is lateral: its translation is normal to the line's axis + along = max(abs(r[6] * c + r[7] * s) for r in rows) + print(f" heading 30 deg: frequencies {err_h:.2e}, node positions {err_x:.1e} m, mode 1 axial " + f"translation {along:.1e}") + if err_h > REL_EXACT or err_x > 1.0e-6 or along > 1.0e-6: + failures.append(f"heading 30 deg: frequencies {err_h}, positions {err_x}, axial {along}") + return failures + + +def check_lazy_wave(exe: str, source: Path, out: Path) -> list[str]: + failures: list[str] = [] + path = run(exe, source / "tests" / "data" / "torsion_lazy_wave_modes.dat", out / "torsion_lazy_wave_modes") + fh, freq, sh, shapes = read_modes(path) + omega = [row[4] for row in freq] + polar = [row[5] for row in freq] + print(f" twisted lazy wave: {len(omega)} modes, {omega[0]:.5f} to {omega[-1]:.5f} rad/s, polar share <= " + f"{max(polar):.1e}") + if fh[-1] != "PolarShare" or sh[-1] != "dTwist": + failures.append("twisted lazy wave: no twist columns") + if len(omega) != 12 or any(not math.isfinite(x) or x <= 0.0 for x in omega): + failures.append(f"twisted lazy wave: frequencies {omega}") + if any(b < a for a, b in zip(omega, omega[1:])): + failures.append("twisted lazy wave: frequencies not ascending") + if any(not 0.0 <= p <= 1.0 for p in polar): + failures.append(f"twisted lazy wave: polar shares {polar}") + if any(not math.isfinite(v) for r in shapes for v in r): + failures.append("twisted lazy wave: non-finite mode shape") + return failures + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--exe", required=True) + parser.add_argument("--source", required=True, type=Path) + parser.add_argument("--output", required=True, type=Path) + args = parser.parse_args() + args.output.mkdir(parents=True, exist_ok=True) + failures: list[str] = [] + try: + failures += check_straight(args.exe, args.output) + failures += check_lazy_wave(args.exe, args.source, args.output) + except AssertionError as exc: + failures.append(str(exc)) + for failure in failures: + print(f"FAIL: {failure}") + if failures: + return 1 + print("PASS: modal analysis of decks with torsion") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_torsion_deck.f90 b/tests/test_torsion_deck.f90 index e82e29d8..c20f5ceb 100644 --- a/tests/test_torsion_deck.f90 +++ b/tests/test_torsion_deck.f90 @@ -945,7 +945,23 @@ SUBROUTINE check_errors() [CHARACTER(16) :: '1 1 2 -'], [CHARACTER(24) :: '1 cab 100.0 40'], & [CHARACTER(96) :: '1 A Rigid 1 0 0 Rigid 0 0 1 0', '1 B Rigid 1 0 0 Rigid 0 0 1 90'], & [CHARACTER(24) :: '0.1 dtM', '0.0 TMax', '3 nModes'], OUTS) - CALL expect_error('modal analysis with torsion is refused', 'tdeck_e11.dat', 'tdeck_e11', 'modal analysis') + ! modal analysis of a line restrained in torsion carries the twist (test_modal_torsion) + BLOCK + LOGICAL :: ok_m + CHARACTER(512) :: em_m, header + INTEGER :: u_m, ios_m + CALL run_deck('tdeck_e11.dat', 'tdeck_e11', ok_m, em_m) + CALL require(ok_m, 'modal analysis with torsion runs (got: '//TRIM(em_m)//')') + header = '' + OPEN (NEWUNIT=u_m, FILE='tdeck_e11.modes.out', STATUS='OLD', ACTION='READ', IOSTAT=ios_m) + IF (ios_m == 0) THEN + READ (u_m, '(A)', IOSTAT=ios_m) header + READ (u_m, '(A)', IOSTAT=ios_m) header + READ (u_m, '(A)', IOSTAT=ios_m) header + CLOSE (u_m) + END IF + CALL require(INDEX(header, 'PolarShare') > 0, 'the modes of a line with torsion carry the twist columns') + END BLOCK ! coupled entries CALL write_deck('tdeck_e12.dat', [neutral_type], no_rows, & [CHARACTER(48) :: '1 Coupled 0.0 0.0 -50.0 0 0 0 0', '2 Fixed 100.0 0.0 -50.0 0 0 0 0'], & From 519e47fecfa4e9bf7552d374822a7f59765ee6dc Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Fri, 30 Oct 2026 17:07:56 +0900 Subject: [PATCH 6/7] docs(modal): the twist Hessian with the full element twist; dTwist units - doc/theory.rst: the modal stiffness of the nodal twist is written with the full element twist rho_e (the reference twist and the coupling's (K/GJ)(l_e - L0)), summed over the elements, so M_e (K/GJ) d2l_e/dq2 under GJ|K appears as the code assembles it; the cross term names the element's nodes consistently. - modes.out: dTwist is a normalised shape value like dX dY dZ, now marked (-); doc/outputs.rst says what the normalisation means for a bending and for a torsional mode, and that End A is the reader's End A (the fairlead of a deck written anchor-first). - examples/torsion_lazy_wave_hangoff_twist.dat: the comment no longer calls the torsion quasi-static. Comment lines only: the example's outputs are byte identical to the reference driver's. Signed-off-by: Jae Hoon Seo --- doc/outputs.rst | 11 +++++++---- doc/theory.rst | 18 ++++++++++++------ examples/torsion_lazy_wave_hangoff_twist.dat | 5 +++-- src/CableDyn_DeckDriver.f90 | 2 +- 4 files changed, 23 insertions(+), 13 deletions(-) diff --git a/doc/outputs.rst b/doc/outputs.rst index 6b0abc03..eda174c4 100644 --- a/doc/outputs.rst +++ b/doc/outputs.rst @@ -463,10 +463,13 @@ column, for every line of the file (``0`` on a line without torsion): * ``PolarShare`` (frequency table): the polar share of the mode's kinetic energy, :math:`\sum_k I_k \varphi_k^2` of the mass-normalised mode with :math:`I_k` the lumped polar inertia, 1 for a pure torsional mode and 0 for one without twist; -* ``dTwist`` [rad] (shape table): the rotation of the node's section about the line tangent, - positive right-handed about the direction from End A to End B, on the scale of the - translations; a torsional mode (``PolarShare`` above 0.5) is scaled to a unit largest - ``dTwist`` instead. +* ``dTwist`` (shape table): the rotation of the node's section about the line tangent, + positive right-handed about the direction from End A to End B, End A being the reader's + (the fairlead on a deck written anchor-first, as in the other line files). Like ``dX dY dZ`` + it is a normalised shape value, marked ``(-)``: the mode is scaled so that its largest nodal + displacement is 1, and ``dTwist`` is then in rad per metre of that displacement; a torsional + 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. Per-rod files (``RODS`` ``Outputs`` flag) ----------------------------------------- diff --git a/doc/theory.rst b/doc/theory.rst index 408e3705..fd9f148b 100644 --- a/doc/theory.rst +++ b/doc/theory.rst @@ -1837,15 +1837,21 @@ dynamics, so its modes do too: the twist angle :math:`\varphi_k` of every node j degrees of freedom, :math:`[\mathbf r, \mathbf m, \varphi]` per node (half-bandwidth 13), with the lumped polar inertia :math:`I_k` as its mass and the second variation of the twist energy :math:`E_t = \sum_e \tfrac12 (GJ_e/L_{0,e})\,\hat\tau_e^2` (and of the elastic end springs) as -its stiffness, at the static torque :math:`M_e`: +its stiffness, at the static element torques :math:`M_e = (GJ_e/L_{0,e})\,\hat\tau_e`. With +element :math:`e` between nodes :math:`k` and :math:`k+1` and its full twist +:math:`\hat\tau_e = \varphi_{k+1} - \varphi_k + \rho_e(\mathbf q)`, +:math:`\rho_e = m_e + (K_e/GJ_e)(l_e - L_{0,e})`, .. math:: - \frac{\partial^2 E_t}{\partial\mathbf q^2} = M_e\,\frac{\partial^2 m_e}{\partial\mathbf q^2} - + \frac{GJ_e}{L_{0,e}}\,\mathbf g_e\mathbf g_e^{\mathsf T}, \qquad - \frac{\partial^2 E_t}{\partial\varphi_{k+1}\,\partial\mathbf q} - = -\frac{\partial^2 E_t}{\partial\varphi_k\,\partial\mathbf q} = \frac{GJ_e}{L_{0,e}}\,\mathbf g_e, - \qquad \mathbf g_e = \frac{\partial\hat\tau_e}{\partial\mathbf q} . + \frac{\partial^2 E_t}{\partial\mathbf q^2} = \sum_e \Big( M_e\,\frac{\partial^2 \rho_e}{\partial\mathbf q^2} + + \frac{GJ_e}{L_{0,e}}\,\mathbf g_e\mathbf g_e^{\mathsf T} \Big), \qquad + \frac{\partial^2 E_t}{\partial\varphi_{k+1}\,\partial\mathbf q}\Big|_e + = -\frac{\partial^2 E_t}{\partial\varphi_k\,\partial\mathbf q}\Big|_e = \frac{GJ_e}{L_{0,e}}\,\mathbf g_e, + \qquad \mathbf g_e = \frac{\partial\rho_e}{\partial\mathbf q} , + +the second term summed over the two elements that share a node; under torque–tension coupling +:math:`\partial^2\rho_e/\partial\mathbf q^2` holds :math:`(K_e/GJ_e)\,\partial^2 l_e/\partial\mathbf q^2`. The torque term lowers the bending frequencies of a twisted line, as on Greenhill's twisted shaft; :math:`\mathbf g_e` couples the twist to the bending of a curved line and, under diff --git a/examples/torsion_lazy_wave_hangoff_twist.dat b/examples/torsion_lazy_wave_hangoff_twist.dat index b2046ccf..0d505f71 100644 --- a/examples/torsion_lazy_wave_hangoff_twist.dat +++ b/examples/torsion_lazy_wave_hangoff_twist.dat @@ -7,8 +7,9 @@ Lozon Gulf of Mexico 80 m lazy-wave power cable twisted two turns at the hang-of -- carries no torque. The motionFile holds the hang-off in place and rolls its frame about the line from 0 -- to -720 deg over 60 s (roll column, smooth start), which imposes two turns of twist -- (Phi = Pretwist B - Pretwist A - roll = +720 deg); the cable then holds the twist for 30 s. --- Torsion is quasi-static (no torsional inertia): Torq1N1 follows the imposed twist, less the --- part the cable absorbs by writhing out of its plane (Twist1 = Phi - Theta). +-- The dynamics carry a twist angle at every node with the polar inertia Irn; the roll is slow +-- against the torsional modes, so Torq1N1 follows the imposed twist, less the part the cable +-- absorbs by writhing out of its plane (Twist1 = Phi - Theta). --------------------- LINE TYPES --------------------------------------------- TypeName Diam MassDenInAir EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t (-) (m) (kg/m) (N) (-) (N-m2) (N) (N-m2) (kg-m) (kg-m) (-) (-) (-) (-) diff --git a/src/CableDyn_DeckDriver.f90 b/src/CableDyn_DeckDriver.f90 index 2a1f0134..57a4214e 100644 --- a/src/CableDyn_DeckDriver.f90 +++ b/src/CableDyn_DeckDriver.f90 @@ -30972,7 +30972,7 @@ SUBROUTINE write_modes_file(out_root, lines, res, ErrStat, ErrMsg) WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Node'//tb//'X'//tb//'Y'//tb//'Z'//tb//'dX'//tb//'dY'//tb// & 'dZ'//tb//'dTwist' WRITE (unit, '(A)') '(-)'//tb//'(-)'//tb//'(-)'//tb//'(m)'//tb//'(m)'//tb//'(m)'//tb//'(-)'//tb//'(-)'// & - tb//'(-)'//tb//'(rad)' + tb//'(-)'//tb//'(-)' ELSE WRITE (unit, '(A)') '# Mode shapes (nodal translations, unit largest nodal displacement)' WRITE (unit, '(A)') 'LineID'//tb//'Mode'//tb//'Node'//tb//'X'//tb//'Y'//tb//'Z'//tb//'dX'//tb//'dY'//tb//'dZ' From fc840bfa69d0f817d394fb1e306a8ebc10922346 Mon Sep 17 00:00:00 2001 From: Jae Hoon Seo Date: Sat, 31 Oct 2026 04:33:43 +0900 Subject: [PATCH 7/7] test(torsion): the frame-write torque check resolves on every build Check R of control_torsion requires the snapshot and the mirror to bring back the committed torque of a non-stepping frame write bit for bit, which re-deriving it as (Phi - Theta)/C would not. The two values differ only by the round-off of Phi - (Phi - summed twist), and the Linux Release build makes that exact, so the "check resolves" requirement failed there although the restore was right. Where the two values are equal, the committed torque is now set one ulp off the re-derived value before the snapshot and the mirror pack, so a re-derivation can never reproduce it on any build. Forcing that branch on Windows passes; the natural difference there stays 1.8e-15 N m. Signed-off-by: Jae Hoon Seo --- tests/test_control_torsion.f90 | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/tests/test_control_torsion.f90 b/tests/test_control_torsion.f90 index 5a5ede68..e63a3ec6 100644 --- a/tests/test_control_torsion.f90 +++ b/tests/test_control_torsion.f90 @@ -37,7 +37,8 @@ PROGRAM test_control_torsion !! ramp continues bit-identically from a snapshot and from a module rebuilt from the !! checkpoint mirror with the command re-applied; after a non-stepping frame write (whose !! torque is the summed twist over the compliance) both bring back that committed torque - !! bit for bit, which re-deriving it as (Phi - Theta)/C would not; + !! bit for bit, which re-deriving it as (Phi - Theta)/C would not (where a build makes the + !! two equal, the torque is set one ulp off the re-derived value so the check resolves); !! S deck: a straight torsion line with a pretwist and a CONTROL row on the coupled aggregate !! (the CompMooring = 5 route; the standalone driver takes no CONTROL) initialises, its !! Torq1N1 follows GJ Twist1/L(t) through a haul-in ramp, and the shell's checkpoint recipe @@ -872,6 +873,14 @@ SUBROUTINE check_restart() tq_keep = cab%line%torsion%torque tq_formula = (cab%line%torsion%phi - cab%line%torsion%theta)/ & CD_HermiteTorsion_Compliance(cab%line%torsion, cab%line%l0) + WRITE (*, '(A,ES24.16,A,ES10.3)') 'R committed torque after a frame write ', tq_keep, & + ' N m; re-derived as (Phi - Theta)/C it would differ by ', tq_formula - tq_keep + ! the two differ only by the round-off of Phi - (Phi - summed twist), which some builds + ! happen to make exact: one ulp off the re-derived value keeps the check resolving + IF (same_bits([tq_formula], [tq_keep])) THEN + tq_keep = NEAREST(tq_formula, 1.0_wp) + cab%line%torsion%torque = tq_keep + END IF CALL CD_HFMF_PackMirror(cab, mirror, es, em) CALL CD_HFMF_Snapshot(cab, es, em) CALL coupled_march(cab, 250, 251, ok2) @@ -883,10 +892,6 @@ SUBROUTINE check_restart() CALL CD_HFMF_UnpackMirror(cab3, mirror, t, es, em) CALL require(es == CD_HFMF_OK .AND. same_bits([cab3%line%torsion%torque], [tq_keep]), & 'R: the mirror brings back the committed torque of a frame write as it was formed') - WRITE (*, '(A,ES24.16,A,ES10.3)') 'R committed torque after a frame write ', tq_keep, & - ' N m; re-derived as (Phi - Theta)/C it would differ by ', tq_formula - tq_keep - CALL require(.NOT. same_bits([tq_formula], [tq_keep]), & - 'R: the frame write''s torque differs from (Phi - Theta)/C, so the check resolves it') CALL CD_HFMF_End(cab3) END BLOCK CALL CD_HFMF_End(cab)