udaan.flatness.quadrotor_cspayload module

Differential flatness for a quadrotor with a cable-suspended point-mass payload.

Flat output:

y = (x_L, ψ)

where x_L ∈ R^3 is the payload position and ψ ∈ R is the quadrotor yaw.

Derivative orders required:

x_L through pop  (x_L, ẋ_L, ẍ_L, x_L^(3), x_L^(4), x_L^(5), x_L^(6))
ψ   through ψ̈    (ψ, ψ̇, ψ̈)

The map recovers the full state (x_L, ẋ_L, q, ω, x_Q, ẋ_Q, R, Ω) plus the feedforward thrust and moment (f, M).

The cable unit vector q points from the quadrotor to the payload — codebase convention; matches QuadrotorCsPayloadState.cable_attitude, whose default [0, 0, -1] places the payload directly below the quadrotor at rest.

Reference:

K. Sreenath, N. Michael, V. Kumar, “Trajectory Generation and Control of a Quadrotor with a Cable-Suspended Load — A Differentially-Flat Hybrid System”, IEEE ICRA, 2013. (Companion: K. Sreenath, T. Lee, V. Kumar, “Geometric Control and Differential Flatness of a Quadrotor UAV with a Cable-Suspended Load”, 52nd IEEE CDC, 2013.)

class udaan.flatness.quadrotor_cspayload.QuadrotorCsPayload

Bases: Flat2State

Differential-flatness recovery for a quadrotor with a cable-suspended, point-mass payload (taut cable, single rigid-body quadrotor).

Flats

alias of QuadrotorCsPayloadFlats

Inputs

alias of QuadrotorCsPayloadInputs

RefState

alias of QuadrotorCsPayloadRefState

__init__(*, mass_q=0.9, mass_l=0.2, inertia=array([[0.0023, 0., 0.], [0., 0.0023, 0.], [0., 0., 0.004]]), cable_length=1.0, gravity=9.81)

classmethod from_model(model)

Build from a udaan.models.quadrotor_cspayload.QuadrotorCsPayloadBase-like model.

Return type:

QuadrotorCsPayload

recover(flats)

Map flat-output derivatives to (reference state, feedforward inputs).

Subclasses must override.

Return type:

tuple[QuadrotorCsPayloadRefState, QuadrotorCsPayloadInputs]

class udaan.flatness.quadrotor_cspayload.QuadrotorCsPayloadFlats

Bases: object

Flat output of a quadrotor with cable-suspended payload: payload-position jet (order ≥ 6) and yaw-angle jet (order ≥ 2).

x_L

dim-3 Jet of the payload position, with derivatives through pop (order ≥ 6) — q^(4) and hence the moment feedforward consume the 6th derivative of x_L.

psi

scalar Jet of the yaw angle, with derivatives through yaw acceleration (order ≥ 2).

__init__(x_L, psi)

psi: Jet

x_L: Jet

class udaan.flatness.quadrotor_cspayload.QuadrotorCsPayloadInputs

Bases: object

Feedforward inputs recovered from the flat output.

thrust

collective thrust magnitude f.

moment

body-frame moment M.

tension

cable tension T = m_L ‖ẍ_L + g e_3‖. Falls out of the Newton–Euler form of Step 1 in the recovery; useful as a slack-cable diagnostic (T → 0 marks the hybrid-mode boundary at which the cable goes slack).

__init__(thrust=0.0, moment=<factory>, tension=0.0)

moment: NDArray[floating]

tension: float = 0.0

thrust: float = 0.0

class udaan.flatness.quadrotor_cspayload.QuadrotorCsPayloadRefState

Bases: object

Recovered kinematic reference state for a quadrotor with cable-suspended payload.

Field naming mirrors udaan.models.quadrotor_cspayload.base.QuadrotorCsPayloadState where the two overlap; acceleration, payload_acceleration, and angular_acceleration are extras that the flatness map also produces.

__init__(payload_position=<factory>, payload_velocity=<factory>, payload_acceleration=<factory>, position=<factory>, velocity=<factory>, acceleration=<factory>, cable_attitude=<factory>, cable_angular_velocity=<factory>, cable_angular_acceleration=<factory>, orientation=<factory>, angular_velocity=<factory>, angular_acceleration=<factory>)

acceleration: NDArray[floating]

angular_acceleration: NDArray[floating]

angular_velocity: TSO3

as_state()

Project onto the model’s QuadrotorCsPayloadState shape (drops all *_acceleration extras; wraps cable fields as S2/TS2).

cable_angular_acceleration: NDArray[floating]

cable_angular_velocity: NDArray[floating]

cable_attitude: NDArray[floating]

orientation: SO3

payload_acceleration: NDArray[floating]

payload_position: NDArray[floating]

payload_velocity: NDArray[floating]

position: NDArray[floating]

velocity: NDArray[floating]

udaan.flatness.quadrotor_cspayload.cable_direction_jet(payload_accel, mass_l, gravity=9.81)

Cable tension and unit-direction jets from the payload-acceleration jet.

Newton’s law on the point-mass payload gives the cable force T q = -m_L (a_L + g e3), where q is the unit cable direction (quadrotor → payload). Given payload_accel = [a_L, ȧ_L, …, a_L^(K)], return (T, q) where T[k] = (d/dt)^k T is the k-th derivative of the scalar cable tension and q[k] = (d/dt)^k q for k = 0…K, via the Leibniz _normalize_derivatives() chain.

Raises ValueError if the payload is in free fall (a_L + g e3 ≈ 0): the cable goes slack and q is undefined.

Return type:

tuple[list[float], list[ndarray]]