---

MdtKea.h

Go to the documentation of this file.

#ifndef _MDTKEA_H
#define _MDTKEA_H
/*
  Copyright Mathengine 2000

  $Name: t-release-0-0-5-msvcrt $

  $Id: MdtKea.h,v 1.55 2000/08/04 15:19:30 williamg Exp $
*/

/** @file
 *
 * Kea solver header file.
 *
 * For explanation of some notation see "Programming From
 * Specifications" by Carroll Morgan.
 */

#include "MePrecision.h"

#define MdtKeaBODYVER1           100

/**
 * Kea Constraints structure.
 *
 * To find the total number of @a rows_to_allocate, find the maximum
 * number of rows the constraints can add, but allow up to an extra
 * three rows padding per partition.
*/
typedef struct
{
    /**
     * Number of partitions described by this structure.
     */
    int num_partitions;

    /**
     * num_rows_partition[i] is number of rows in partition i.
     *
     * The size should be one int for each partition.
     */
    int *num_rows_partition;

    /**
     * num_constraints_partition[i] is number of constraints in
     * partition i.
     *
     * The size should be one int for each partition.
     */
    int *num_constraints_partition;

    /**
     * Total number of constraint rows.
     *
     * (+ | 0<=i<num_partitions . num_rows_partition[i])
     */
    int num_rows;

    /**
     * Total number of constraints.
     *
     * (+ | 0<=i<num_partitions . num_constraints_partition[i])
     */
    int num_constraints;

    /**
     * List of nonzero blocks of jacobian matrix.
     *
     * The size should be 18 MeReals for
     * each rows_to_allocate, initialised to 0.
     */
    MeReal *Jstore;

    /**
     * Constraint error vector.
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *xi;

    /**
     * Vector in the constraint equation m{J*v=c}. 
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *c;

    /**
     * Low limit on Lagrange multiplier.
     *
     * One  MeReal for ebach rows_to_allocate initialised to 0.
     */
    MeReal *lo;

    /**
     * High limit on Lagrange multiplier.
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *hi;

    /**
     * Calculated Lagrange multiplier READ ONLY.
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *lambda;

    /**
     * Vector of forces applied to satisfy constraints READ ONLY.
     *
     * 24 MeReals for each constraint added initialised to 0.
     * Currently disabled on PS2.
     */
    MeReal *force;

    /**
     * First order constraint slipping vector.
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *slipfactor;

    /**
     * Projection constants.
     *
     * One MeReal for each rows_to_allocate initialised to 0.
     */
    MeReal *xgamma;

    /**
     * Jsize[i] is the number of rows in constraint i.
     *
     * One int for each constraint added.
     */
    int *Jsize;

    /**
     * Offset of constraint i from the start of its partition.
     *
     * partition_start+Jofs[i] is the offset in the above vectors of the
     * first element corresponding to constraint i, where partition_start
     * is the offset of the first constraint in the partition which i
     * belongs to. One int for each constraint added
     */
    int *Jofs;

    /**
     * Jbody[i*3+0],Jbody[i*3+1],Jbody[i*3+2] are the bodies
     * constrained by constraint i.
     *
     * 3 ints for each constraint added.
     */
    int *Jbody;
}
MdtKeaConstraints;

/**
 * Kea Parameters structure.
 */
typedef struct
{
    /** Amount of time to evolve system by. */
    MeReal stepsize;

    /** Numerical tolerance used by matrix solver. Default = 0.01. */
    MeReal epsilon;

    /** Constraint relaxation rate. Default = 0.2. */
    MeReal gamma;

    /**
     * Pointer to some memory that Kea can use.
     *
     * Kea doesn't malloc, only uses this area.
     */
    void *memory_pool;

    /** Size of this area in bytes. */     
    unsigned int memory_pool_size;
}
MdtKeaParameters;

/**
 * Kea Body structure.
 *
 * After a time step, the contents of 'force' and 'torque' will be the
 * total applied forces plus any forces and torques due to constraints.
 * These MUST BE RE-ZEROED before accumulating values for the next time
 * step.
*/
typedef struct
{
    /** Data stucture tag. Should be MdtKeaBODYVER1. */
    int tag;                    /* 0x00*/
    /** Total length of data structure. */
    int len;                    

    /** 1/Mass of the body. */
    MeReal invmass;

    /** Nonzero applies fast rotation hack. */
    int fastSpin;

    /** Applied (to centre of mass) force. */
    MeVector4 force;            /* 0x10 */

    /** Applied torque. */
    MeVector4 torque;           /* 0x20 */

    /** Inverse of 3x3 inertia tensor - row 0. */
    MeVector4 invI0;            /* 0x30 */
    /** Inverse of 3x3 inertia tensor - row 1.  */
    MeVector4 invI1;            /* 0x40 */
    /** Inverse of 3x3 inertia tensor - row 2. */
    MeVector4 invI2;            /* 0x50 */

    /** The 3x3 inertia tensor - row 0.  */
    MeVector4 I0;               /* 0x60 */
    /** The 3x3 inertia tensor - row 1. */
    MeVector4 I1;               /* 0x70 */
    /** The 3x3 inertia tensor - row 2. */
    MeVector4 I2;               /* 0x80 */

    /** Linear velocity of body. */ 
    MeVector4 vel;              /* 0x90 */
    /** Angular velocity of body. */ 
    MeVector4 velrot;           /* 0xa0 */
    /** Body orientation quaternion. */ 
    MeVector4 qrot;             /* 0xb0 */

    /** Linearl Acceleration of body (READ ONLY). */
    MeVector4 accel;            /* 0xc0 */
    /** Angular acceleration of body (READ ONLY). */
    MeVector4 accelrot;         /* 0xd0 */

    /** Axis of assumed fast rotation (unit length). */
    MeVector4 fastSpinAxis;     /* 0xe0 */
}
MdtKeaBody;

/**
 * Kea 4x4 Transformation Matrix.
 */
typedef struct
{
    /** Rotation matrix row 0 (last element 0). */
    MeVector4 R0;
    /** Rotation matrix row 1 (last element 0). */
    MeVector4 R1;
    /** Rotation matrix row 2 (last element 0). */
    MeVector4 R2;
    /** Position vector (last element 1). */
    MeVector4 pos;
}
MdtKeaTransformation
#ifdef PS2
__attribute__((aligned(16)))
#endif
;

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * Utility function for calculating the size of the workspace needed by
 * Kea.
 *
 * This memory is passed into Kea in the MdtKeaParameters structure.
 */
int MdtKeaMemoryRequired(int *num_rows_partition, int num_partitions);

/**
 * Kea solver function.
 *
 * Takes an array of bodies and a MdtKeaConstraints struct (which
 * defines the constraints as defined above), as well as an array
 * indicating which constraints are to be solved together as one
 * partition. It solves each partition and evolves the system.
 *
 * @param constraints A MdtKeaConstraints struct containing constraint
 * rows generated by MdtBcl functions.
 * @param blist Array of MdtKeaBody structs to be simulated.
 * @param tlist Array of MdtKeaTransformation structs that correspond to
 * blist.
 * @param num_bodies Number of bodies/transformations in blist/tlist
 * @param parameters A MdtKeaParameters structure containing stepsize,
 * memory pool etc.
 */
void                    MdtKeaStep(MdtKeaConstraints constraints,
                            MdtKeaBody *blist,
                            MdtKeaTransformation *tlist,
                            int num_bodies,
                            MdtKeaParameters parameters);

#ifdef __cplusplus
}
#endif

#endif

---