Dynamics Models

The UKF sigma point integration step includes calls out to a selectable dynamics model, which can be used to provide estimates of the acceleration and angular acceleration at that time step. The output of the dynamics model is used by the kinematics model, which determines the state at time t+1 based on the state at time t.

Available models

Centripetal

The centripetal model simply predicts an angular acceleration of zero, and predicts a linear acceleration equal to the cross product of the vehicle's angular velocity and the body-frame velocity vector.

This model is suitable for vehicles that generally travel in the direction they're pointing (forwards or backwards) — perhaps cars or planes.

To use this model in Python, set ukf.model = ukf.UKF_MODEL_CENTRIPETAL; in C, call ukf_choose_dynamics(UKF_MODEL_CENTRIPETAL);.

X8 flight dynamics

The X8 flight dynamics model incorporates experimentally-derived functions based on our X8 flying wing configuration. The throttle setting (in RPM) is via control input 0; control input 1 is the left elevon, and control input 2 is the right elevon. Unlike the fixed-wing flight dynamics model, which only provides reasonable results within aerodynamically feasible states, the X8 model tries very hard to provide reasonable/sane values through the entire state space. This simplifies use of the model in NMPC algorithms.

To use this model in Python, set ukf.model = ukf.UKF_MODEL_X8; in C, call ukf_choose_dynamics(UKF_MODEL_X8);.

Custom dynamics

The custom dynamics model calls a function you specify to return linear and angular accelerations based on the current state and control vector.

To use this model in Python, set ukf.model = ukf.UKF_MODEL_CUSTOM and ukf.custom_model = custom_model_func, where custom_model_func is whatever name you've given your model function. Model functions are defined as follows:

def example_model(state, control): 
    acceleration = [0, 0, 0]
    angular_acceleration = [0, 0, 0]
    
    # Model goes here: access control[0:3], state.position[0:2],
    # state.velocity[0:2] etc.

    return acceleration + angular_acceleration

In C, the function is defined as:

void example_model(const real_t *state, const real_t *control, 
real_t *output) {
    output[0] = 0.0; /* acceleration.x */
    output[1] = 0.0; /* acceleration.y */
    output[2] = 0.0; /* acceleration.z */
    output[3] = 0.0; /* angular_acceleration.x */
    output[4] = 0.0; /* angular_acceleration.y */
    output[5] = 0.0; /* angular_acceleration.z */
}

To use that function, just call ukf_set_custom_dynamics_model(example_dynamics);.