Boom¶

class py_crane.boom.Boom(model: py_crane.crane.Crane, name: str, description: str = '', anchor0: Boom | None = None, mass: float | str = 1.0, mass_center: float | tuple[float, float, float] = 0.5, boom: tuple[float, float, float] | list[float] = (1.0, 0.0, 0.0), q_factor: float = 0.0, limits: tuple[float, float, float] | None = None, tolerance: float = 1e-5, **kwargs: Any)¶

Bases: object

Basic Boom model object, representing one element of a crane, modelled as stiff rod with length, mass and mass-center.

Assumption

All booms of the crane are completely stiff, excluding bending, stretching and vibration modes of motion. This includes also loose conncetions, i.e. the wire is assumed straight and without stretch.

Assumption

Per default, the mass center of a boom is located at the geometric center of the boom. This can be changed using the tuple form of the mass_center parameter.

Limitation

The degrees of freedom for the boom (possible ranges in which changes of parameters are allowed) cannot be directly defined within the basic Boom object. These can be defined as part of the Variable definitions when packaging a crane as FMU, see py_crane.crane_fmu and py_crane.boom_fmu. Alternatively the control module from the package component-model can be used to define control goals, which also includes limits on value, change of value and acceleration of value.

Assumption

All units are assumed as basic units (meter, radian, kg). Additional display units can be defined when packaging a crane as FMU.

Alternative to instantiating a Boom as Boom (…), Crane.add_boom() of the related crane can be called (recommended). In this case the parameters model and anchor0 to Boom shall not be included (are automatically added).

There are two fundamentally different types of booms

stiff connection boom (q_factor =0):: The spherical angles with respect to the previous boom can only be changed through new settings.
loose connection boom(q_factor >0):: The joint to the previous boom is loose and the boom can move freely in all spherical directions, i.e. it represents a wire, exhibiting pendulum movement with respect to the local center of mass. q_factor serves at the same time as a definition of the pendulum damping.

Basic boom movements are

length change, i.e. boom_setter() ( (new-length, None, None)): instantaneously sets a new length to the boom and updates all children booms so that they are properly connected.
rotation, i.e. .boom_setter ( (None, new-polar, new-azimuth)): instantaneously rotates the boom around its origin. The reference direction is the direction of the parent boom (i.e. as if the parent boom was in z-direction). Successively all child booms are updated (i.e. rotated accordingly) to obey the stiffness of the crane. Note that loose connection booms are not allowed to rotate actively, since that would interfere with pendulum movement.
mass change, i.e. .mass:: instantanteous mass change of boom (e.g. add or remove load). Note that instantaneous changes make sense in this case, since loads are changed instantaneously and since wire bending is not modelled.

After any movement

the internal variables (center of mass, positions, etc.) are re-calculated using calc_statics_dynamics(). If dt=None instantaneous changes are assumed.
the attached booms are moved in accordance
and the center of mass of the sub-system (the boom with attached booms) is re-calculated.
Finally the parent booms are informed about the change of the sub-system center of mass, leading to re-calculation of their internal variables.

Note

initialization variables are designed for easy management of parameters, while derived internal variables are more complex (often 3D vectors)

Parameters:

model (py_crane.crane.Crane) – The model object owning the boom
name (str) – The short name of the boom (unique within crane)
description (str) – An optional description of the boom
anchor0 (Boom) – the boom object to which this Boom is attached. There is exactly one boom where this is set to None, which is the crane fixation and which is automatically provided by the crane, i.e. for real booms this is never None.
mass (float) – Parameter denoting the mass of the boom in kg. For most booms this is fixed, but when modelling loads as part of the (last) boom this can change.
mass_center (float,tuple) – Parameter denoting the position of the center of mass of the boom, provided as portion of the length (as float). Optionally the absolute displacements in x- and y-direction (assuming the boom in z-direction) can be added e.g. (0.5,-0.5, 1): (in m) halfway down the boom displaced 0.5m in the -x direction and 1m in the y direction
boom (tuple) –
A tuple defining the boom relative to its parent in spherical (ISO 80000) coordinates.
From the parent boom the following attributes are automatically inferred:
- origin: end of the parent boom => cartesian coordinate of the base point of the boom
- pole axis: direction vector of the parent boom => local cartesian z-axis
- reference direction in equator plane: crane x-direction or azimuth angle of connecting boom => local cartesian x-axis
The boom is then defined in local polar coordinates:
- length: the length of the boom (in m)
- polar: a rotation angle for a rotation around the negative y-axis (away from z-axis) against the clock.
- azimuth: a rotation angle for a rotation around the positive z-axis (away from the x-axis) against the clock.
:: note..: The boom is used to keep length and local coordinate system up-to-date,
while the active work variables are the cartesian origin, direction and length
q_factor (float) –
optional possibility to implement a loose connection between booms.
- if q_factor=0.0, the connection to the parent boom is stiff according to the boom angle setting
- if q_factor > 0, the crane boom (the wire) is implemented as a stiff rod with a loose connection hanging from the parent boom.
- The q_factor denotes the dimensionless quality factor (energy stored/energy lost per radian), which is also equal to \(2 \ln( A_i/A_{i+1}) = \tau \sqrt{\omega_0^2 - \gamma^2}\), \(\gamma = 1/(2 \tau)\), with \(\tau > 1/(2\omega_0)\) and A: Amplitude, \(\omega_0=\sqrt{g/L}\): natural angular frequency of pendulum, \(\tau\): characteristic damping time \(\gamma\): pendulum damping. This does not cover critically and over-damped systems, which are in any case not realistic for crane wires). In general the q_factor is a fixed parameter, but for testing purposes damping() is included, which allows changing of related parameters in a consistent way.
limits (tuple) – Optional tuple of control limits for active boom control. See ControlLimits
tolerance (float) – Accuracy during pendulum calculations

Note

This offers basic functionality. Variable changes and related updates are performed directly on the variables

Assumption

Center of mass: _c_m is the local mass-center measured relative to origin. _c_m_sub is a global quantity

__init__(model: py_crane.crane.Crane, name: str, description: str = '', anchor0: Boom | None = None, mass: float | str = 1.0, mass_center: float | tuple[float, float, float] = 0.5, boom: tuple[float, float, float] | list[float] = (1.0, 0.0, 0.0), q_factor: float = 0.0, limits: tuple[float, float, float] | None = None, tolerance: float = 1e-5, **kwargs: Any)¶

Methods

`__init__`(model, name[, description, ...])
`boom_setter`(val[, ch])	Set length and angles of boom (if allowed) and ensure consistency with other booms.
`calc_statics_dynamics`([dt])	After any movement the local c_m and the c_m of connected booms have changed.
`damping`([q_factor, damping_time])	Change/set the damping properties of a flexible boom.
`pendulum`(dt)	For a non-stiff connection, if the _c_m is not exactly below origin, the _c_m acts as a damped pendulum.
`pendulum_relax`()	Relax the pendulum movement, leading to the CoM strictly downward.
`rot`([newval])	Access the rotation object from outside the boom.
`update_child`([change])	Update this boom after the parent boom has changed length, angles, position or rotation.

Attributes

`c_m`	Updates and returns the local center of mass point relative to self.origin.
`c_m_sub`	Return the system center of mass as absolute position The _c_m_sub needs to be calculated/updated using calc_statics_dynamics.
`end`	Calculate the cartesian coordinates of the end of the boom from .origin, .length and .direction.
`force`	Calculate the force resulting from linear acceleration.
`length`	Extract the length parameter from .boom.
`model`	Get the Crane object which this boom is connected to.
`name`	Get the unique (within the crane) name of the boom.
`torque`	Calculate the torque from the CoM of this boom with respect to the fixation.

boom_setter(val: tuple[float | None, ...] | list[float | None], ch: int = 0)¶

Set length and angles of boom (if allowed) and ensure consistency with other booms. This is called from the general setter function after the units and range are checked and before the variable value itself is changed within the model.

Note: boom_setter initiates an internal change in the crane, which then affects ._rot, .direction, .length: External changes (parent booms) do not affect .boom.

Parameters:

val (array-like) – new value of boom. Elements of the array can be set to None (keep value)
ch (int) – track change type or set it initially to force a type of change,

calc_statics_dynamics(dt: float | None = None)¶

After any movement the local c_m and the c_m of connected booms have changed. Thus, after the movement has been transmitted to connected booms, the _c_m_sub of all booms can be updated in reverse order. The local _c_m_sub is updated by calling this function, assuming that child booms are updated.

Since there might happen multiple movements within a time interval, the function is called explicitly, i.e. from crane. Note that c_m_sub includes all child booms, but the wire (as this can swing). For the wire, the function .update_child() is not run, so that neither .origin nor .rot or .direction is updated.

Parameters:: dt (float) – for dynamic calculations, the time for the movement must be provided and is then used to calculate torque and force

damping(q_factor: float | None = None, damping_time: float | None = None)¶: Change/set the damping properties of a flexible boom. Ensure that _damping_time and _new_len is set correctly.

pendulum(dt: float)¶

For a non-stiff connection, if the _c_m is not exactly below origin, the _c_m acts as a damped pendulum.

More detailed information on Spherical pendulum and Q-factor: * Sphärisches Pendel (the English article is not as good) for detailed formulas * q_factor:

Limitation

Falling movements (i.e. wire acceleration larger than g) are not allowed (raise error).

Assumption

The center of mass is on the boom line at mass_center[0] relative distance from origin.

Limitation

Damping implemented as reduction on speed, which is accurate only over whole period, since potential enery is not included. Note also that damping_time is defined as damping on energy, not on amplitude!

The following differential equation is used for pendulum movement

\[\ddot{\vec{r}} = -\frac{\vec{r} \times (\vec{r} \times \vec{g})}{R^2} - \frac{\dot{\vec{r}}^2}{R^2} \vec{r}\]

covering general spherical pendulum movement. For the crane we get the additional complications, that the pendulum origin may be moving (because the parent boom is moving) or that the length of the pendulum may be changing. To accomodate for that within a time interval \(\tau t\) the origin is initially left unchanged and is over the time interval \(\tau t\) moved to the target position (end point of the parent boom). The same strategy is applied to the length of the wire, adapting it to the target length over the time interval \(\tau t\).

Pendulum movements are integrated into .calc_statics_dynamics(dt) if the connection is non-stiff (q_factor!=0).

Parameters:: dt (float) – The time interval for which the pendulum movement is calculated
Return type:: updated velocity and acceleration (of c_m)

pendulum_relax()¶: Relax the pendulum movement, leading to the CoM strictly downward. Since no time is used this action is strictly unphysical and should only be used for testing purposes.

rot(newval: Rotation | None = None) → Rotation¶: Access the rotation object from outside the boom. Since this is a function for the model, we make it a function also here.

update_child(change: Change = Change.ALL)¶

Update this boom after the parent boom has changed length, angles, position or rotation.

change(Change) = Change.ALL: Possibility to specify which type of change is performed. Default: ALL

property c_m: ndarray[tuple[int, ...], dtype[float64]]¶: Updates and returns the local center of mass point relative to self.origin.

property c_m_sub¶: Return the system center of mass as absolute position The _c_m_sub needs to be calculated/updated using calc_statics_dynamics.

property end: ndarray[tuple[int, ...], dtype[float64]]¶: Calculate the cartesian coordinates of the end of the boom from .origin, .length and .direction.

property force¶: Calculate the force resulting from linear acceleration.

property length: floating¶: Extract the length parameter from .boom.

property model¶: Get the Crane object which this boom is connected to.

property name¶: Get the unique (within the crane) name of the boom.

property torque¶: Calculate the torque from the CoM of this boom with respect to the fixation. Note that this is in practice only calculated for the load and the rest of the crane. These two are calculated separately, since the load exhibits a pendulum action. The Torque is always calculated relative to the crane position.