MV-1070: Create a Simple Pendulum System Using MDL

In this tutorial, you will learn how to create a definition-based entity (such as a system) using MDL.

Using systems allows you to do the following:
  • Organize your model file modularly.
  • Reuse system definition files.
  • Easily debug and maintain your files.
  • Create a library of modeling components.
  • Perform certain operations on the entire system at once (for example; turning systems on/off, making the whole system compliant/rigid, translation, etc.). An operation, such as translation on a system, is automatically performed on all the subsystems within that system.

The concept of system definition is analogous to the procedures/subroutines in a programming language.



Figure 1.
Analogy between programming and MDL approach
A procedure is a program that needs information from the main program. The procedure can be called /instantiated any number of times. A procedure is a part of main program, but can be maintained separately.

Similarly, a system definition is a model aggregate which needs information from the main model. It can be called/instantiated any number of times. A system definition is a part of the main model which can be maintained separately.

Use of system definition is two-step process:
  1. Defining the system
  2. Instantiation of the system definition in the model
Section 1: System Definitions
A system definition is a reusable system model that can be a part of any model as long all the attachment requirements are satisfied.

A system definition is represented by a *DefineSystem() block. This block should end with a *EndDefine() statement that indicates the end of a definition block. All entities defined within this block are considered to be part of the system definition.

A typical system definition example is shown below:
*DefineSystem(def_sys, att_1, att_2…att_n)
In the system definition example above:
  • def_sys is the variable name of the system definition and will be used while instantiating this system.
  • att_1, att_2, … att_n is a list of arguments that act as attachments to the system.
A system definition can be created in two ways:
  1. Using the text editor.
  2. Created from graphical user interface. This requires minimal text editing. Refer to MV-1030: Create a System Definition Using the MotionView GUI.
Note: This tutorial covers Method 1, as it covers all the details of the system definition.
Section 2: System Attachments
The picture below shows a system definition of an SLA suspension. It is an incomplete system which needs information about the attachment bodies and points to get connected to.


Figure 2.

Excluding the *Attachment() statement, other entities in a system definition are similar to an MDL model file.

The general structure of a system definition is:
  • A system receives information about entities external to the system via attachments.
  • Any MDL entity can be passed to a system as an attachment.
  • The *Attachment() statement inside the system definition declares the arguments in the *DefineSystem block as an attachment, along with assigning what type of entity the attachment is going to be.
  • The same variable name as the attachment should be referred within the definition when defining an entity that depends on the external entity.
  • Refer to the entries in bold in the example below. Reference line numbers are for reference only and are not part of the MDL file.
    • Line 2 - defines a system with a variable name sys_definition and has one argument b_body_att as an attachment.
    • Line 4 - declares b_body_att as an attachment with the entity type as Body.
    • Line 7 - creates a revolute joint between b_sys_body which is a body defined within this system (not shown) and b_body_att which is a body that is an attachment to this system.


    Figure 3.
    Note: An attachment entity need not serve as a physical attachment to entities inside the system definition. It may be used to represent external variables being passed into the system definition. For example, datasets may also serve as attachments.
Section 3: Instantiating a System
  • Instantiating a system means creating an instance of a system definition. A system is instantiated using a *System() MDL statement, which has the following syntax:
    *System(varname, “label”, def_varname, arg_1, arg_2, …, arg_n)

    where,

    • varname - variable name of the system instance.
    • label - descriptive label for the system.
    • def_varname - variable name of the system definition being instantiated.
    • arg_1, arg_2,…, arg_n - entity variable names that act as attachment to the system. The number of arguments should match the number of attachments listed and declared in the system definition.
  • A definition can be instantiated multiple times. For example, a single system definition file for an SLA suspension can be used to create multiple SLA suspension systems within one or more vehicle model files.
  • The following example illustrates a system definition and its instantiation within an MDL model file. Some of the terms in the example below are in bold to highlight a few key relationships between a system definition and its instantiation. Reference numbers are for the example only, and are not contained in an MDL file.
    • A system instance with variable name system1 is created in line 2, that refers to the definition sys_definition. B_Ground (Ground Body) which is passed as an argument for the attachment.
    • The system definition is described within the *DefineSystem() and *EndDefine() block between line 3 and line 7. Attachment b_att gets resolved to B_Ground.
    Reference Numbers System Instantiation with Definition
    1 // Model : Body.mdl

    *BeginMDL(base_model, "Base Model")

    2 //Instantiate the system definition sys_definition

    *System(system1, "First System", sys_definition, B_Ground)

    3 //Begin System Definition Block

    *DefineSystem(sys_definition, b_att)

    4 //Declare a body attachment to the system

    *Attachment(b_att, "Body Attachment", Body, "Add an body external to this system

    5 //Entities within the system

    *Point(p_sys, "Point in the system")

    *Body(b_sys, "Body in the system")

    6 //Define a joint with the body b_sys and the body attachment b_att

    *RevJoint(j_rev, "Revolute Joint", b_sys, b_att, p_sys, VECTOR, V_Global_X

    7 *EndDefine() //End Definition Block
    8 *EndMDL()
You can instantiate systems within your model in one of three ways:
  1. Manually author the MDL file as shown in the example above.
  2. Import a system from the System/Assembly panel in the MotionView MBD Model window.
  3. Use the Assembly Wizard in the MotionView MBD Model window.

The exercises that follow explain the first two methods; the third is covered in a separate tutorial.