Crane¶

class py_crane.crane.Crane(to_crane_angle: Callable[[ndarray[tuple[int], dtype[float64]]], ndarray[tuple[int], dtype[float64]]] | None = None)¶

Bases: object

A basic crane model object for mounting on fixed or movable structures.

The crane consists of stiff booms (see boom.py), which are connected to each other through

stiff connection (q_factor=0):: The angles with respect to the previous boom can only be changed through new settings.
loose connection (damping>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.

The basic boom fixation is automatically added and accessible through .boom0. Initially the direction of the fixation is set to ‘up’ (z-axis). The fixation direction can be changed through the d_orientation 3d angular velocity variable of the crane. orientation represents the current 3d angle (roll, pitch, yaw, according to ISO 1151–2) vector of the crane with respect to its initial orientation.

The crane should first be instantiated and then the booms added, using .add_boom() . Added booms can be accessed through the .booms() iterator from fixation to last boom or in reverse direction (.booms(reverse=True). In addition the function .boom_by_name(boom-name) is available to get access to a Boom object of the crane.

The position and the orientation of the crane with respect to the fixation can be changed. For cranes mounted on clompletely fixed platforms, these settings never change, but for cranes mounted on moveable structures (e.g. vessels) they the following effects:

linear acceleration of the structure, i.e d_velocity: The acceleration leads to a force on the fixation and the pendulum movement of loosely connected booms is affected. The .position and .velocity getter and setter functions, together with the property .d_velocity provide access to current values. Note that a constant velocity has no effect on the crane.
angular direction, i.e. .angular: The angular direction creates a torque on the fixation. The property getter and setter functions .angular facilitate instantaneous setting of the Euler angle of the fixation with respect to the structure. The initial angle is (roll=0,pitch=0,yaw=0). The function .rotate(euler-angle) is recommended to be used to
angular acceleration, i.e. .d_angular: Angular direction changes cause both torques and pendulum action. The property getter and setter functions .d_angular facilitate instantaneous changes of the Euler angle of the fixation with respect to the structure.

Instantaneous changes are in general non-physical. In reality changes happen more or less smooth, which implies that changes should be ramped up/down (in principle using infinite orders of derivatives). In practice we limit ourselves to usage of up to second order derivatives, i.e. the assumption that acceleration changes happen instantaneously, or that forces can be applied instantaneously. Since cranes are often driven electrically and since electric motors can deliver high torques rather instantaneously, the approximation seems reasonable.

The introduction of derivatives introduces the notion of time. The function .calc_statics_dynamics( dt) updates all changes (forces, torque, pendulum movement) over the next time interval given the current settings. In simulations this function shall be called as part of every simulation step.

Assumption

The dynamics of changes is simulated to second order, accepting instantaneous acceleration changes.

Other things to note:

The booms use polar coordinates for their direction, defined with respect to the direction of the previous boom. This implies that the third direction variable is missing for booms, with the consequence that internal boom torsion cannot be addressed. For fixed booms that is a good approximation, but for the load (i.e. the center of mass of the loose connection) it implies the limitation that the load cannot turn.
all angles inside the crane are in radians, lengths are in meters and masses are in kg. Only when the interface to the outside world is defined as FMU, the possibility exists that parameters, inputs and outputs can be defined in other display units, e.g. degrees.
forces and torque are only calculated in relation to the fixation (the whole crane), not in relation to moving joints.

Parameters:: to_crane_angle (Callable) – Optional possibility to specify a non-default transformation from vessel Euler angles to crane coordinate system. Default: (north-east-down as r-p-y + north-west-up) Should be a function of an Euler angle, corresponding also to the choice of ‘degrees’.

__init__(to_crane_angle: Callable[[ndarray[tuple[int], dtype[float64]]], ndarray[tuple[int], dtype[float64]]] | None = None)¶: Initialize the crane object.

Methods

`__init__`([to_crane_angle])	Initialize the crane object.
`add_boom`(args, *kwargs)	Add a boom to the crane.
`boom_by_name`(name)	Retrieve a boom object by name.
`booms`(*[, reverse])	Iterate through the booms.
`calc_statics_dynamics`([dt])	Run calc_statics_dynamics() on all booms in reverse order, to get all Boom._c_m_sub and dynamics updated.
`do_step`(current_time, step_size)	Do a simulation step of size dt at time .
`rot`([rpy])	Get/Set a new absolute rotation through an Euler angle.
`rotate`(rpy[, absolute])	Set the orientation to a new value according to ISO 1151–2 (roll,pitch,yaw) - rotations.
`to_crane_angle_default`(rpy)	Transform the given extrinsic euler angles into the the coordinate system used by the crane.

Attributes

`angular`	Get the current euler angle of the crane (internally stored as Rot).
`boom0`
`d_angular`	Get the current angular velocity (euler angles).
`position`
`velocity`
`to_crane_angle`

add_boom(*args: Any, **kwargs: Any) → Boom¶

Add a boom to the crane.

This method represents the recommended way to contruct a crane and then add the booms. The model and anchor0 parameters are automatically added to the boom when it is instantiated. args and kwargs thus include all Boom parameters, but the model and the anchor0

boom_by_name(name: str) → Boom | None¶: Retrieve a boom object by name. None if not found.

booms(*, reverse: bool = False) → Generator[Boom, None, None]¶: Iterate through the booms. If reverse=True, the last element is first found and the iteration produces the booms from end to start.

calc_statics_dynamics(dt: float | None = None)¶: Run calc_statics_dynamics() on all booms in reverse order, to get all Boom._c_m_sub and dynamics updated.

do_step(current_time: float, step_size: float) → bool¶: Do a simulation step of size dt at time .

rot(rpy: Sequence[float] | ndarray[tuple[int], dtype[float64]] | None = None)¶: Get/Set a new absolute rotation through an Euler angle.

rotate(rpy: Sequence[float] | ndarray[tuple[int], dtype[float64]] | Rotation, absolute: bool = False)¶

Set the orientation to a new value according to ISO 1151–2 (roll,pitch,yaw) - rotations.

Parameters:

rpy (Sequence) – Sequence of roll, pitch and yaw angles or a rotation object
absolute (bool) – euler rotation as absolute angle or relative to current self._rot

The current orientation is maintained as scipy rotation object based on euler angles (roll,pitch,yaw) with x in vessel direction, y to starboard, z down

to_crane_angle_default(rpy: ndarray[tuple[int], dtype[float64]]) → ndarray[tuple[int], dtype[float64]]¶

Transform the given extrinsic euler angles into the the coordinate system used by the crane.

Note: In maritime applications, the North-East-Down is often used,: while crane uses naturally a North-West-Up system. Both are right handed.

property angular: ndarray¶: Get the current euler angle of the crane (internally stored as Rot).

property boom0: Boom¶

property d_angular: ndarray¶: Get the current angular velocity (euler angles).

property position: ndarray¶

to_crane_angle: Callable[[ndarray[tuple[int], dtype[float64]]], ndarray[tuple[int], dtype[float64]]]¶

property velocity: ndarray¶