<!-- GENERATED by tools/generators/itemDocsEmitter.py from definitions/ - do not edit -->
```{raw} latex
\clearpage
```

(sec-item-objectancfcable)=
# ObjectANCFCable

A 3D cable finite element using 2 nodes of type NodePointSlope1. The localPosition of the beam with length $L$=length and height $h$ ranges in $X$-direction in range $[0, L]$ and in $Y$-direction in range $[-h/2,h/2]$ (which is in fact not needed in the {ref}`EOM <EOM>`). For description see ObjectANCFCable2D, which is almost identical to 3D case. NOTE: this element does not include torsion, therfore a torque cannot be applied along the local x-axis.

## Interface

- Python names: `ObjectANCFCable` or `Cable`, and `VCable` for its visualization
- Nodes it takes: [](#sec-item-nodepointslope1)
- Body markers that can be placed on it: [](#sec-item-markerbodymass), [](#sec-item-markerbodyposition)

## Parameters

The parameters of the item; in a dictionary, its type is 'ANCFCable':

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | objects's unique name |
| **length** | UReal |  | 0. | (symbol: $L$) [SI:m] reference length of beam; such that the total volume (e.g. for volume load) gives $\rho A L$; must be positive |
| **massPerLength** | UReal |  | 0. | (symbol: $\rho A$) [SI:kg/m] mass per length of beam |
| **bendingStiffness** | UReal |  | 0. | (symbol: $EI$) [SI:Nm$^2$] bending stiffness of beam; the bending moment is $m = EI (\kappa - \kappa_0)$, in which $\kappa$ is the material measure of curvature |
| **axialStiffness** | UReal |  | 0. | (symbol: $EA$) [SI:N] axial stiffness of beam; the axial force is $f_{ax} = EA (\varepsilon -\varepsilon_0)$, in which $\varepsilon = \vert \rv^\prime\vert -1$ is the axial strain |
| **bendingDamping** | UReal |  | 0. | (symbol: $d_{K}$) [SI:Nm$^2$/s] bending damping of beam ; the additional virtual work due to damping is $\delta W_{\dot \kappa} = \int_0^L \dot \kappa \delta \kappa dx$ |
| **axialDamping** | UReal |  | 0. | (symbol: $d_{\varepsilon}$) [SI:N/s] axial damping of beam; the additional virtual work due to damping is $\delta W_{\dot\varepsilon} = \int_0^L \dot \varepsilon \delta \varepsilon dx$ |
| **referenceAxialStrain** | Real |  | 0. | (symbol: $\varepsilon_0$) [SI:1] reference axial strain of beam (pre-deformation) of beam; without external loading the beam will statically keep the reference axial strain value |
| **strainIsRelativeToReference** | Real |  | 0. | (symbol: $f\cRef$) if set to 1., a pre-deformed reference configuration is considered as the stressless state; if set to 0., the straight configuration plus the values of $\varepsilon_0$ and $\kappa_0$ serve as a reference geometry; allows also values between 0. and 1. |
| **nodeNumbers** | NodeIndex2 | 2 | [invalid (-1), invalid (-1)] | two node numbers ANCF cable element |
| **useReducedOrderIntegration** | Index |  | 0 | 0/false: use Gauss order 9 integration for virtual work of axial forces, order 5 for virtual work of bending moments; 1/true: use Gauss order 7 integration for virtual work of axial forces, order 3 for virtual work of bending moments |
| **visualization** | VObjectANCFCable |  |  | parameters for visualization of item |


Renamed parameters, still taken with a `DeprecationWarning`: `physicsLength` (deprecated since 1.12.258, removed in 2031): use `length`; `physicsMassPerLength` (deprecated since 1.12.258, removed in 2031): use `massPerLength`; `physicsBendingStiffness` (deprecated since 1.12.258, removed in 2031): use `bendingStiffness`; `physicsAxialStiffness` (deprecated since 1.12.258, removed in 2031): use `axialStiffness`; `physicsBendingDamping` (deprecated since 1.12.258, removed in 2031): use `bendingDamping`; `physicsAxialDamping` (deprecated since 1.12.258, removed in 2031): use `axialDamping`; `physicsReferenceAxialStrain` (deprecated since 1.12.258, removed in 2031): use `referenceAxialStrain`.

## Visualization parameters

The parameters of `VObjectANCFCable`, given as `visualization`:

| name | type | size | default | description |
|---|---|---|---|---|
| **show** | Bool |  | True | set true, if item is shown in visualization and false if it is not shown; note that all quantities are computed at the beam centerline, even if drawn on surface of cylinder of beam; this effects, e.g., Displacement or Velocity, which is drawn constant over cross section |
| **radius** | float |  | 0. | if radius==0, only the centerline is drawn; else, a cylinder with radius is drawn; circumferential tiling follows general.cylinderTiling and beam axis tiling follows bodies.beams.axialTiling |
| **color** | Float4 | 4 | [-1.,-1.,-1.,-1.] | RGBA color of the object; if R==-1, use default color |

## Drawing

Drawn as [all finite elements](#sec-drawing-objectsfiniteelement); a tube of radius `radius` along the axis, of `bodies.beams.axialTiling` segments and `general.cylinderTiling` around, or a line if the radius is 0.

Settings beyond those of all finite elements: [`bodies.beams.axialTiling`](#sec-vsettingsbeams), [`bodies.beams.crossSectionFilled`](#sec-vsettingsbeams), [`bodies.beams.reducedAxialInterploation`](#sec-vsettingsbeams), [`general.cylinderTiling`](#sec-vsettingsgeneral).

## Output variables

Available as `OutputVariableType` in sensors, `Get...Output()` and other functions:

```{tabularcolumns} \Y{0.25}\Y{0.25}\Y{0.5}
```

| output variable | symbol | description |
|---|---|---|
| Position | $\LU{0}{\pv\cConfig(x,0,0)} = \rv\cConfig(x) + y\cdot \nv\cConfig(x)$ | global position vector of local position $[x,0,0]$ |
| Displacement | $\LU{0}{\uv\cConfig(x,0,0)} = \LU{0}{\pv\cConfig(x,0,0)} - \LU{0}{\pv\cRef(x,0,0)}$ | global displacement vector of local position |
| Velocity | $\LU{0}{\vv(x,0,0)} = \LU{0}{\dot \rv(x)}$ | global velocity vector of local position |
| Director1 | $\rv'(x)$ | (axial) slope vector of local axis position (at $y$=0) |
| StrainLocal | $\varepsilon$ | axial strain (scalar) of local axis position (at Y=Z=0) |
| CurvatureLocal | $[K_x, K_y, K_z]\tp$ | local curvature vector |
| ForceLocal | $N$ | (local) section normal force (scalar, including reference strains) (at $y$=$z$=0); note that strains are highly inaccurate when coupled to bending, thus consider useReducedOrderIntegration=2 and evaluate axial strain at nodes or at midpoint |
| TorqueLocal | $M$ | (local) bending moment (scalar) (at $y$=$z$=0), which are bending moments as there is no torque |
| Acceleration | $\LU{0}{\av(x,0,0)} = \LU{0}{\ddot \rv(x)}$ | global acceleration vector of local position |
| KineticEnergy | $T = \frac{1}{2} \dot\qv\tp \Mm\, \dot\qv$ | kinetic energy from the mass matrix of the current state and the velocities of the nodes; current configuration only; localPosition must be $[0,0,0]$ |
| PotentialEnergy | $V = \frac{1}{2}\int_0^L EA\,(\varepsilon - \varepsilon_\mathrm{ref})^2 + EI\,\vert \tkappa - \tkappa_\mathrm{ref}\vert ^2\, dx$ | elastic energy, integrated with the rules of the elastic forces (useReducedOrderIntegration); localPosition must be $[0,0,0]$ |

(description-objectancfcable)=
## Detailed description

### Nodes and coordinates

Two nodes of type `NodePointSlope1`, each with a position $\rv_i$ and a slope $\rv'_i$; the element
coordinates are

$$
\qv = \left[\, \rv_0\tp\;\; \rv_0^{\prime T}\;\; \rv_1\tp\;\; \rv_1^{\prime T}\, \right]\tp \in \Rcal^{12} ,
$$

taken as the sum of reference and current coordinates, as for `ObjectANCFCable2D`.

### Kinematics and interpolation

The element is the spatial version of `ObjectANCFCable2D`: the position and slope of the axis at
the axial coordinate $x \in [0,\,L]$ are interpolated with the same cubic shape functions
{eq}`eq-cable2d-shapefunctions`, now for three components,

$$
\rv(x) = \Sm(x)\, \qv , \quad \Sm(x) = \left[\, S_1(x)\,\ImThree\;\; S_2(x)\,\ImThree\;\; S_3(x)\,\ImThree\;\; S_4(x)\,\ImThree\, \right] .
$$

### Strains

The axial strain is $\varepsilon = \Vert \rv' \Vert - 1$, as in 2D. The bending strain is the vector
of the material measure of curvature,

$$
\kv = \frac{\rv' \times \rv''}{\Vert \rv' \Vert^2} ,
$$

and the virtual work of the elastic forces is

$$
\delta W_e = \int_0^L \left( EA\, (\varepsilon - \varepsilon_0)\, \delta\varepsilon + EI\, \kv\tp \delta\kv \right) dx
$$

with the damping terms $d_\varepsilon \dot\varepsilon$ and $d_K \dot\kv$ added in the same way. The
bending stiffness is the same in all directions, and there is **no torsion**: a single slope
vector carries no rotation of the cross section about the axis. With `strainIsRelativeToReference`
$f\cRef$, the strain and curvature of the reference configuration, times $f\cRef$, are subtracted,
so that a curved reference can be stress-free; a reference curvature parameter, which the 2D
element has, does not exist.

### Mass matrix

Constant, $\Mm = \int_0^L \rho A\, \Sm\tp \Sm\, dx$, computed once, as in 2D.

### Elastic forces and integration

As in `ObjectANCFCable2D`, with the same three choices of `useReducedOrderIntegration` for the axial
and the bending terms.

### Marker interfaces

Markers act on the **axis only**: a local position must have $y = z = 0$, which the element checks.
The position Jacobian is the shape function matrix, $\LU{0}{\Jm_{pos}}(x) = \Sm(x)$, and the
mass-weighted Jacobian its integral $\int_0^L \rho A\, \Sm\, dx$. There is no rotation Jacobian and
no orientation, so `MarkerBodyRigid` does not fit and no torque can be applied.

### Limitations

No torsion and no orientation of the cross section; loads and constraints only on the axis.

(miniexample-objectancfcable)=
## Mini example


```python
from exudyn.beams import GenerateBeamElementsAlongLine
rhoA = 78.
EA = 1000000.
EI = 833.3333333333333
cable = Cable(massPerLength=rhoA, 
              bendingStiffness=EI, 
              axialStiffness=EA, 
              )

ancf=GenerateBeamElementsAlongLine(mbs=mbs,
              positionStart=[0,0,0], positionEnd=[2,0,0],
              numberOfElements=32, #converged to 4 digits
              beamTemplate=cable, #this defines the beam element properties
              gravity = [0,-9.81,0],
              groundConstraintsStart = [1,1,1, 0,1,1], #add constraints for pos and rot (r'_y,r'_z)
              )
lastNode = ancf['nodes'][-1]

#assemble and solve system for default parameters
mbs.Assemble()
mbs.SolveStatic()

#check result
exu.sys['testResult'] = mbs.GetNodeOutput(lastNode, exu.OutputVariableType.Displacement)[0]
#ux=-0.5013058140308901
```


Relevant Examples (Ex) and TestModels (TM) with weblink to github: [`accessFunctionsTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/accessFunctionsTest.py) (TM), [`energiesFlexibleBodiesTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/energiesFlexibleBodiesTest.py) (TM)