Data Input Validation Techniques for Real-Time Simulation

Dynamics and Real-Time Simulation (DARTS) Laboratory Input Validation 2023 DARTS Lab Course Abhinandan Jain, Aaron Gaut, Carl Leake, Vivian Steyert, Tristan Hasseler, Asher Elmland, Juan Garcia Bonilla August 2023 https://dartslab.jpl.nasa.gov/ https://dartslab.jpl.nasa.gov/ 1

Questions to Answer How can we make sure out input data is checked to make sure it is valid? What kinds of input data checking is available in the DARTS/Dshell Framework? 2

Typical Scenario Our simulation multibody and models require parameter data that must be validated: Prevent negative masses Ensure valid inertia matrices, and rotational data Values must be within certain ranges Tabular data must be monotonic Important to make sure incoming parameter data is valid to ensure a valid simulation! 3

How Can We Validate Input Data? 4

Example Parameter Data From file defining body parameters: bodies = { SC1' : { 'Bodies' : { Capsule' : BodyParam( mass = 300.0, cmInertia = [[1, 0, 0], [0, 1, 0], [0, 0, 1] ], jointType = FULL6DOF', ), . . . Kilos, Grams? 5

Example Parameter Data from Dshell.Units import kg Safer: bodies = { SC1' : { 'Bodies' : { Capsule' : BodyParam( mass = 300.0*kg, cmInertia = [[1, 0, 0], [0, 1, 0], [0, 0, 1] ], jointType = FULL6DOF', ), . . . Kilos! Here the kg tags this value with a specific units type. As it is digested into the system, it be converted if necessary. 6

Under The Hood! 7

Approach The BaseDataField class provides specialized checking for specific types of parameters Requires parameter classes be derived from BaseParam All input validation classes implement isValid() function BaseParam will call all data field isValid() functions to check validity of each parameter automatically Can still do more complex checking in param class initializer eg, checking combinations of parameters Example: QuaternionDataField formerly ParamInfo 8

quaternion.py (in DshellCommon/python/data_fields) class QuaternionDataField(BaseDataField): def __init__(self, required=False, description='Quaternion parameter field', default_value=None, source=None): BaseDataField.__init__(self, required=required, description=description, quantity= Quaternion , default_value=default_value, data_type=float, length=4, choices=None, source=source) 9

QuaternionDataField.py def isValid(self, val): if isinstance(val, SOAQuaternion): return True if isinstance(val, (list, tuple)): if len(val) != 4: return False try: SOAQuaternion(*val) return True except: return False # Simplified 10

Use of QuaternionDataField In BodyParams.py: class BodyParam(BaseParam): _params = { ... INB_TO_JOINT_QUAT: QuaternionDataField( required=False, description='The quaternion from the inboard body frame to the body hinge', default_value=[0., 0., 0., 1.0]), 11

Input Validation Classes (files in DshellCommon/python/data_fields) base.py joint_limits.py BaseDataField JointLimitsDataField boolean.py model_enum.py BooleanDataField ModelEnumDataField boolean_array.py pointer.py BooleanArrayDataField PointerDataField filename.py pointer_array.py FilenameDataField PointerArrayDataField filename_array.py quaternion.py FilenameArrayDataField QuaternionDataField float.py rotation_matrix.py FloatDataField RotationMatrixDataField float_array.py spice_id.py FloatArrayDataField SpiceIDDataField float_of_vector3.py spice_id_array.py FloatOrVector3DataField SpiceIDArrayDataField geometry.py string.py GeometryDataField StringDataField inertia_matrix.py string_array.py InertiaMatrixDataField StringArrayDataField integer.py vector3.py IntegerDataField Vector3DataField integer_array.py vector3_array.py IntegerArrayDataField Vector3ArrayDataField See QA Item 1166 for more details formerly ParamInfo 12

Extra Input Validation Capabilities Many of these classes support extra functionality via constructor arguments, eg: Integer and Float data fields support min*, max*, positive_only, positive_or_zero_only Float array data fields support montonic* * Implemented by JSC Team, Thanks! 13

Example: BodyParam (abbreviated) class BodyParam(BaseParam): _params = { MASS: FloatDataField( required=True, quantity='Mass', positive_or_zero_only=True, description='The body mass'), BODY_TO_CM: Vector3DataField( required=False, quantity='Length', description='The 3-vector to the body CM from the body frame.', default_value=[0., 0., 0.]), CM_INERTIA: InertiaMatrixDataField( required=False, description='The 3x3 body inertia matrix about the body CM'), INERTIA: InertiaMatrixDataField( required=False, description='The 3x3 body inertia matrix about the body frame'), INB_TO_JOINT: Vector3DataField( required=False, quantity='Length', description='3-vector from the inboard body frame to the body hinge', default_value=[0., 0., 0.]), 14

Example: BodyParam (abbreviated) INB_TO_JOINT_QUAT: QuaternionDataField( required=False, description='The quaternion from the inboard body frame to the body hinge', default_value=[0., 0., 0., 1.0]), BODY_TO_JOINT: Vector3DataField( required=False, quantity='Length', description='The 3-vector from the body frame to the body hinge', default_value=[0., 0., 0.]), BODY_TO_JOINT_QUAT: QuaternionDataField( required=False, description='The quaternion from the body frame to the pnode for the body hinge'), JOINT_TYPE: StringDataField( required=False, choices=JOINT_TYPE_CHOICES, description="The hinge type (string). Supported: %s" % ', '.join(JOINT_TYPE_CHOICES)), JOINT_AXES: Vector3ArrayDataField( required=False, quantity='Dimensionless', default_value=None, description='The hinge rotation/translation axis'), 15

Example: BodyParam (abbreviated) JOINT_LIMITS: JointLimitsDataField( required=False, description='Limits for range of joint generalized coordinate [min, max]'), PRESCRIBED: BooleanArrayDataField( required=False, allow_scalar=True, description='Whether the joint is prescribed or free'), GEOMETRY: GeometryDataField( required=False, description='Geometry to be loaded into DScene.'), SUBHINGE: BaseDataField( required=False, description='Subhinge specification for custom hinge.'), NEGATIVE_INTEGRAL_SENSE: BooleanDataField( required=False, default_value=True, description="""Body products of inertia values expressed in NEGATIVE inertia integral sense (defaults to True)"""), } 16