Model Control Cards

Assembly-Related Cards

The initial assembly related cards are:

Skip Initial Joint Assembly

    <card> ::= skip initial joint assembly ;

This directive inhibits the execution of the initial joint assembly. Note that for a model to behave correctly, the initial joint assembly should always succeed. A correct model succeeds with 0 iterations, i.e. it intrinsically satisfies the constraints from the beginning. However, the initial joint assembly is more than a simple compliance test; it represents a static preprocessor for models. See the directives use in Section 5.1.1 and initial stiffness in Section 5.1.1 for more details on performing appropriate initial joint assembly.

Use

    <card> ::= use : <item_list> , in assembly ;
    <item_list> ::= <item> [ , <item_list> ]
    <item> ::= { rigid bodies 
               | gravity
               | forces
               | beams
               | aerodynamic elements
               | loadable elements }

joints are used by default, and cannot be added to the list. beams are used by default, too, but can be added to the list essentially for backwards compatibility.

Initial Stiffness

    <card> ::= initial stiffness : <position_stiffness>
                                   [ , <velocity_stiffness> ] ;

This directive affects the stiffness of the dummy springs that constrain the position and the orientation (<position_stiffness>) and the linear and angular velocity (<velocity_stiffness>) of the structural nodes (either static or dynamic) during the initial assembly; the default is 1.0 for both. Note that each node can use a specific value; see Section 6.1 for details.
Note that the same value is used for the position and the orientation, so this stiffness is dimensionally inconsistent; It should really be intended as a penalty coefficient. The same considerations apply to the penalty value for linear and angular velocities.

Omega Rotates

    <card> ::= omega rotates : { yes | no } ;

Sets whether the imposed angular velocity should be considered attached to the node or fixed in the global system during the initial assembly.

Tolerance

    <card> ::= tolerance : <tolerance> ;

The tolerance that applies to the initial joint assembly; this tolerance is used to test the norm 2 of the residual, because it is very important, for a correct start of the simulation, that the algebraic constraints be satisfied as much as possible. The alternate statement initial tolerance is tolerated for backwards compatibility.

Max Iterations

    <card> ::= max iterations : <max_iterations> ;

The number of iterations that are allowed during the initial assembly. The alternate statement max initial iterations is tolerated for backwards compatibility.

General-Purpose Cards

Title

    <card> ::= title : " <simulation_title> " ;

Print

    <card> ::= print : {
        dof stats |
        dof description |
        equation description |
        description |
        element connection |
        node connection |
        connection |
        all |
        none
    } [ , ... ] ;

• The keyword dof stats enables printing of all potential dof owner entities at initial assembly and at regular assembly, so that the index of all variables can be easily identified;
• the keyword dof description adds extra variable description;
• the keyword equation description adds extra equation description;
• the keyword description is a shortcut for both dof description and equation description;
• the keyword element connection prints information about element connectivity;
• the keyword node connection prints information about node connectivity;
• the keyword connection is a shortcut for both node connection and element connection;
• the keyword all enables all dof statistics printing;
• the keyword none disables all dof statistics printing (the default).

Note that, apart from none, the other values are additive, i.e. the statement

    print: dof stats;
    print: dof description;

is equivalent to

    print: dof stats, dof description;

while the statement

    print: none;

disables all.

Make Restart File

    <card> ::= make restart file
        [ : { iterations , <iterations_between_restarts>
            | time , <time_between_restarts> } ] ;

The default (no arguments) is to make the restart file only at the end of the simulation.

Select Timeout

    <card> ::= select timeout , <timeout> ;

exit after <timeout> minutes when waiting for connections on stream drives or stream output elements. By default, no timeout is used, so select waits forever.

Default Output

    <card> ::= default output : <output_list> ;
    <output_list> ::= { all | none | <output_item> } 
                      [ , <output_list> ]
    <output_item> ::=
        { reference frames
        | abstract nodes
        | electric nodes
        | hydraulic nodes
        | structural nodes [ | accelerations ]
        | aerodynamic elements
        | air properties
        | beams
        | electric elements
        | forces
        | genels
        | gravity
        | hydraulic elements
        | joints
        | rigid bodies
        | induced velocity elements }

Here the default output flag for a type of node or element can be set. It can be overridden for each entity either when it is created or later, for entity aggregates, in each entity module, by means of the output directive for nodes and elements. Special values are:

• all enables output of all entities;
• none disables output of all entities;
• reference frames by default, reference frames are not output; when enabled, a special file .rfm is generated, which contains all the reference frames defined, using the syntax of the .mov file.
• accelerations enables output of linear and angular accelerations for dynamic structural nodes, which are disabled by default. Accelerations output can be enabled on a node by node basis; see structural node for details.

Since values are additive, except for none, to select only specific entities use none first, followed by a list of the entities whose output should be activated.

Example.

    begin: control data;
        # ...
        # disable all except structural nodes
        default output: none, structural nodes;
        # ...
    end: control data;

Output Frequency

This statement is intended for producing partial output.

    <card> ::= output frequency: <steps> ;

Despite the misleading name, this statement causes output to be produced every <steps> time steps, starting from the initial time. A more general functionality is now provided by the output meter statement (Section 5.1.2).

Output Meter

A drive that causes output to be generated when different from zero, while no output is created when equal to zero. It is useful to reduce the size of the output file during analysis phases that are not of interest.

    <card> ::= output meter: (DriveCaller)<meter> ;

The functionality of the deprecated output frequency statement can be reproduced by using the meter drive caller as follows:

    output meter: meter, 0., forever, steps, 10;

Output Precision

Sets the desired output precision for those file types that allow it (currently, all the native output except the .out file; the ADAMS output, .res files, are not affected. The default is 6; since the output is in formatted plain text, the higher precision, the larger the files and the slower the simulation.

    <card> ::= output precision : <number_of_digits> ;

This will no longer be an issue when the binary output is implemented; in that case, the output format will likely be fixed (float), or an optional extended format (double) will be allowed.

Output Results

This deprecated statement was intended for producing output in formats compatible with other software. See Appendix C for a description of the types of output that MBDyn can provide. Most of them are produced in form of postprocessing, based on the default raw output.

Right now, the output results statement is only used to enable the experimental support for NetCDF output, which eventually will replace the current textual output:

    <card> ::= output results : netcdf ;

Default Orientation

This statement is used to select the default format for orientation output. For historical reasons, MBDyn always used the 123 form of Euler angles (also known as Cardano angles). This statement allows to enable different formats:

    <card> ::= default orientation :
        { euler123 | euler313 | euler321
            | orientation vector | orientation matrix } ;

where

• euler123 is the historical representation by means of three angles that represent three consecutive rotations about axes 1, 2 and 3 respectively, always applied to the axis as it results from the previous rotation;
• euler313 is similar to euler123, but the rotations are about axes 3, 1 and 3 in the given sequence. This is the usual form for Euler angles.
• euler321 is similar to euler123, but the rotations are about axes 3, 2 and 1 in the given sequence.
• orientation vector is the vector whose direction indicates the axis of the rotation that produces the orientation, and whose modulus indicates the magnitude of that rotation;
• orientation matrix indicates the orientation matrix itself.

The default remains euler123.

Note: this change implies that by default the selected way will be used to represent orientations in input and output. This flag is not honored throughout the code, yet. Right now, only structural nodes can output orientations as indicated by default orientation. However, there is no direct means to detect what format is used in the .mov file (while it is easy, for example, in the .nc file generated by NetCDF). As a consequence, it is the user's responsibility to keep track of what representation is being used and treat output accordingly.

Model

    <card> ::= model : <model_type> ;

    <model_type> ::= static

This statement allows to set the model type to static, which means that all dynamic structural nodes will be treated as static, and inertia forces ignored. Gravity and centripetal acceleration will only be considered as forcing terms. See the structural node (Section 6.1) for details.

Rigid Body Kinematics

    <card> ::= rigid body kinematics : <rbk_data> ;

    <rbk_data> ::= { <const_rbk> | <drive_rbk> }

    <const_rbk> ::= const
            [ , position , (Vec3)<abs_position> ]
            [ , orientation , (OrientationMatrix)<abs_orientation> ]
            [ , velocity , (Vec3)<abs_velocity> ]
            [ , angular velocity , (Vec3)<abs_angular_velocity> ]
            [ , acceleration , (Vec3)<abs_acceleration> ]
            [ , angular acceleration , (Vec3)<abs_angular_acceleration> ]

    <drive_rbk> ::= drive
            [ , position , (Vec3_tpl_drive_caller)<abs_position> ]
            [ , orientation , (Vec3_tpl_drive_caller)<abs_orientation_vector> ]
            [ , velocity , (Vec3_tpl_drive_caller)<abs_velocity> ]
            [ , angular velocity , (Vec3_tpl_drive_caller)<abs_angular_velocity> ]
            [ , acceleration , (Vec3_tpl_drive_caller)<abs_acceleration> ]
            [ , angular acceleration , (Vec3_tpl_drive_caller)<abs_angular_acceleration> ]

In principle, the kinematic parameters should be consistent. However, in most cases this is not strictly required, nor desirable. In fact, if the model is made only of rigid bodies, algebraic constraints and deformable restraints, the case of a system rotating at constant angular velocity does not require abs_angular_velocity to be the derivative of abs_orientation, since the latter never appears in the forces acting on the system. Similarly, the abs_position and abs_velocity do not appear as well, as soon as the latter is constant.

However, if other forces that depend on the absolute motion (position, orientation, and velocity) participate, this is no longer true. This is the case, for example, of aerodynamic forces, which depend on the velocity of the body with respect to the airstream, whose velocity is typically expressed in the global reference frame.

Loadable path

    loadable path : [ { set | add } , ] " <path> " ;

This card allows to either set (optional keyword set) or augment (optional keyword add) the search path for run-time loadable modules using the path specified as the mandatory argument path.

Note: this command should be considered obsolete, but its replacement is not implemented yet. It impacts the loading of all run-time loadable modules, not only that of loadable elements (Section 8.18. See for example the module load statement in Section 2.3.6.