MBDyn Input File Format
Version 1.7.3
Pierangelo Masarati
Dipartimento di Ingegneria Aerospaziale
Politecnico di Milano
Automatically generated October 14, 2017

Contents
1 Overview
15
1.1 Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1.1 Passing the Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1.2 Passing the Output File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.2 Input File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.2.1 Syntax Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.3 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2 General19
2.1 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.1 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.2 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.3 Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.1 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.2 Plugin Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.3 Higher-Order Math Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.3.1 3 × 1 Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.2 6 × 1 Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.3 3 × 3 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.4 (3 × 3) Orientation Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.3.5 6 × 6 Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.3.6 6 × N Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4 Input Related Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.1 Constitutive Law . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.2 C81 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.4.3 Drive Caller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.4 Hydraulic fluid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.5 Include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.6 Module Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.4.7 Print symbol table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.4.8 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.4.9 Remark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.4.10 Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.4.11 Setenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.4.12 Template Drive Caller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.5 Node Degrees of Freedom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.6 Drives and Drive Callers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1

2.6.1 Array drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.2 Closest next drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.3 Const(ant) drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.4 Cosine drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.5 Cubic drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.6 Direct drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.7 Dof drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.8 Double ramp drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.9 Double step drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.10 Drive drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.11 Element drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.12 Exponential drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.13 File drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.14 Fourier series drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.15 Frequency sweep drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.16 GiNaC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.17 Linear drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.18 Meter drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.19 Mult drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.20 Node drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.21 Null drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.22 Parabolic drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.23 Periodic drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.24 Piecewise linear drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.25 Postponed drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.26 Ramp drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.27 Random drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.28 Sample and hold drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.29 Scalar function drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.30 Sine drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.31 Step drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.32 String drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.33 Tanh drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.34 Time drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.35 Timestep drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.36 Unit drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.37 Deprecated drive callers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.38 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.39 Template Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7 Scalar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8 Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8.1 Friction models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8.2 Shape functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9 Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10 Constitutive Laws . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.1 Linear elastic, linear elastic isotropic . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.2 Linear elastic generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.3 Linear elastic generic axial torsion coupling . . . . . . . . . . . . . . . . . . . . . .
2.10.4 Cubic elastic generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

46
46
46
48
49
49
49
50
50
50
51
52
52
52
53
54
54
54
54
55
55
55
55
56
56
56
57
57
57
58
59
59
60
60
60
60
60
60
61
63
69
69
69
70
71
72
74
74
74

2.10.5 Inverse square elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.6 Log elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.7 Linear elastic bistop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.8 Double linear elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.9 Isotropic hardening elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.10 Scalar function elastic, scalar function elastic isotropic . . . . . . . . . . . . . . . .
2.10.11 Scalar function elastic orthotropic . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.12 Linear viscous, linear viscous isotropic . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.13 Linear viscous generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.14 Linear viscoelastic, linear viscoelastic isotropic . . . . . . . . . . . . . . . . . . . .
2.10.15 Linear viscoelastic generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.16 Linear time variant viscoelastic generic . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.17 Linear viscoelastic generic axial torsion coupling . . . . . . . . . . . . . . . . . . .
2.10.18 Cubic viscoelastic generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.19 Double linear viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.20 Turbulent viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.21 Linear viscoelastic bistop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.22 GRAALL damper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.23 shock absorber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.24 symbolic elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.25 symbolic viscous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.26 symbolic viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.27 ann elastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.28 ann viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.29 nlsf viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.30 nlp viscoelastic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.31 array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.32 bistop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10.33 invariant angular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.11 Hydraulic fluid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.11.1 Incompressible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.11.2 Linearly compressible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.11.3 Linearly compressible, with thermal dependency . . . . . . . . . . . . . . . . . . .
2.11.4 Super (linearly compressible, with thermal dependency) . . . . . . . . . . . . . . .
2.11.5 Exponential compressible fluid, with saturation . . . . . . . . . . . . . . . . . . . .
2.12 Authentication Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.12.1 Note on security and confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . .
2.12.2 No authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.12.3 Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.12.4 PAM (Pluggable Authentication Modules) . . . . . . . . . . . . . . . . . . . . . . .
2.12.5 SASL (Simple Authentication and Security Layer) . . . . . . . . . . . . . . . . . .
2.13 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

75
75
75
75
75
76
76
76
77
77
77
77
78
78
78
78
79
79
79
80
81
81
81
82
82
84
86
86
86
87
87
87
87
88
88
89
89
89
89
89
90
90

3 Data93
3.1 Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

3

4 Problems
94
4.1 Initial-Value Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.1.1 General Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.1.2 Derivatives Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.1.3 Dummy Steps Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.1.4 Output Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
4.1.5 Real-Time Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.2 Other Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5 Control Data
114
5.1 Assembly-Related Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.1.1 Skip Initial Joint Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.1.2 Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.1.3 Initial Stiffness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.1.4 Omega Rotates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.1.5 Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.1.6 Max Iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2 General-Purpose Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2.1 Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2.2 Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2.3 Make Restart File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.2.4 Select Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.2.5 Default Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
5.2.6 Output Frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.2.7 Output Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.2.8 Output Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.2.9 Output Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.2.10 Default Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.2.11 Default Aerodynamic Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.2.12 Default Beam Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.2.13 Default Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.2.14 Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.15 Rigid Body Kinematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.16 Loadable path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.3 Model Counter Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.3.1 Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.3.2 Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.3.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6 Nodes124
6.1 Structural Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.1 Static Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.2 Dynamic Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.3 Modal Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.4 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.5 Dummy Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.2 Electric Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.3 Abstract Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.4 Hydraulic Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.5 Parameter Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
4

6.6

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.6.1 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

7 Drivers133
7.1 File Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
7.1.1 Fixed Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
7.1.2 Variable Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.1.3 Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.1.4 RTAI Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
7.1.5 Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
8 Elements
140
8.1 Aerodynamic Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
8.1.1 Aerodynamic Body/Aerodynamic Beam2/3 . . . . . . . . . . . . . . . . . . . . . . 141
8.1.2 Aeromodal Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
8.1.3 Aircraft Instruments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
8.1.4 Air Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
8.1.5 Generic Aerodynamic Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8.1.6 Induced velocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.1.7 Rotor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8.2 Automatic structural . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8.3 Beam Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
8.3.1 Beam Section Constitutive Law . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.3.2 Three-node beam element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.3.3 Two-node beam element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
8.3.4 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
8.3.5 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
8.4 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
8.5 Bulk Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
8.5.1 Stiffness spring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.6 Couple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.7 Electric Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.7.1 Accelerometer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.7.2 Displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.7.3 Motor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.7.4 Discrete control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
8.8 Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
8.8.1 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
8.8.2 Abstract force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
8.8.3 Abstract reaction force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
8.8.4 Structural force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
8.8.5 Structural internal force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.8.6 Structural couple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8.8.7 Structural internal couple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8.8.8 Modal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.8.9 External forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8.8.10 External Structural . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
8.8.11 External structural mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.8.12 External modal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.8.13 External modal mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
58.9

Genel Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.9.1 General Purpose Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
8.9.2 Special Rotorcraft Genel Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.10 Gravity Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.11 Hydraulic Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.11.1 Actuator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.11.2 Minor Loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.11.3 Three Way Minor Loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.11.4 Control Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.11.5 Dynamic Control Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.11.6 Pressure Flow Control Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
8.11.7 Pressure Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
8.11.8 Flow Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
8.11.9 Orifice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.11.10 Accumulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.11.11 Tank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.11.12 Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.11.13 Dynamic Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.11.14 Imposed Pressure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.11.15 Imposed Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
8.12 Joint Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
8.12.1 Angular acceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.12.2 Angular velocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.12.3 Axial rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.12.4 Beam slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.12.5 Brake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.12.6 Cardano hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.12.7 Cardano pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.12.8 Cardano rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
8.12.9 Clamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
8.12.10 Coincidence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.12.11 Deformable Axial Joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.12.12 Deformable displacement hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.12.13 Deformable displacement joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.12.14 Deformable Hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
8.12.15 Deformable joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.12.16 Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.12.17 Distance with offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.12.18 Drive displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.12.19 Drive displacement pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.12.20 Drive hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.12.21 Gimbal hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
8.12.22 Gimbal rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
8.12.23 Imposed displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
8.12.24 Imposed displacement pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
8.12.25 In line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.12.26 In plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.12.27 Invariant deformable displacement joint . . . . . . . . . . . . . . . . . . . . . . . . 243
8.12.28 Invariant deformable hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

6

8.12.29 Linear acceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.12.30 Linear velocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
8.12.31 Modal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
8.12.32 Plane displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
8.12.33 Plane displacement pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.12.34 Plane hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.12.35 Plane pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.12.36 Prismatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
8.12.37 Revolute hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.12.38 Revolute pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
8.12.39 Revolute rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
8.12.40 Rod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
8.12.41 Rod with offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
8.12.42 Rod Bezier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
8.12.43 Spherical hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
8.12.44 Spherical pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
8.12.45 Total equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
8.12.46 Total joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
8.12.47 Total pin joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
8.12.48 Total reaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
8.12.49 Universal hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8.12.50 Universal pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8.12.51 Universal rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8.12.52 Viscous body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8.12.53 Lower Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8.13 Joint Regularization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
8.13.1 Tikhonov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
8.14 Plate Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
8.14.1 Shell4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
8.14.2 Membrane4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
8.15 User-Defined Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
8.15.1 Loadable Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
8.15.2 User-Defined Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
8.15.3 General Discussion on Run-Time Loadable Modules . . . . . . . . . . . . . . . . . 271
8.16 Output Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
8.16.1 Stream output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
8.16.2 RTAI output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
8.16.3 Stream motion output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
8.17 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
8.17.1 Bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
8.17.2 Driven Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
8.17.3 Inertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
8.17.4 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
A Modal Element Data
283
A.1 FEM File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
A.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
A.1.2 Example: Dynamic Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
A.1.3 Example: Static Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
A.2 Code Aster Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
7A.3 NASTRAN Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
A.4 Procedures for Other FEA Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
B Modules
293
B.1 Element Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
B.1.1 Module-aerodyn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
B.1.2 Module-asynchronous machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
B.1.3 Module-cyclocopter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
B.1.4 Module-fab-electric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
B.1.5 Module-fab-motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
B.1.6 Module-fab-sbearings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
B.1.7 Module-hydrodynamic plain bearing with offset . . . . . . . . . . . . . . . . . . . 296
B.1.8 Module-imu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
B.1.9 Module-mds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
B.1.10 Module-nonsmooth-node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
B.1.11 Module-template2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
B.1.12 Module-wheel2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
B.1.13 Module-wheel4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
B.2 Constitutive Law Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
B.2.1 Module-constlaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
B.2.2 Module-constlaw-f90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
B.2.3 Module-constlaw-f95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
B.2.4 Module-cont-contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
B.2.5 Module-damper-graall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
B.2.6 Module-damper-hydraulic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
B.2.7 Module-muscles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
B.3 Drive Caller Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
B.3.1 Module-drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
B.3.2 Module-randdrive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
B.4 Template Drive Caller Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
B.4.1 Module-eu2phi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
B.5 Driver Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
B.5.1 Module-HID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
B.6 Scalar Function Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
B.6.1 Module-scalarfunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
B.7 Miscellaneous Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
B.7.1 Module-flightgear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
B.7.2 Module-octave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
B.7.3 Module-tclpgin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
B.7.4 Module-template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
B.7.5 Module-udunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
C NetCDF Output Format
315
C.1 NetCDF Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
C.1.1 Base Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
C.1.2 Run Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
C.1.3 Node Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
C.1.4 Element Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.1.5 Eigenanalysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
C.2 Accessing the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
8

C.2.1 Octave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
D Results Visualization
325
D.1 EasyAnim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
D.2 Output Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
D.2.1 Output in a Relative Reference Frame . . . . . . . . . . . . . . . . . . . . . . . . . 326
E Log File Format
328
E.1 Generic Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
E.2 Model Description Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
E.2.1 acceleration, velocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
E.2.2 aero0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
E.2.3 aero2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
E.2.4 aero3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
E.2.5 axial rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
E.2.6 beam2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
E.2.7 beam3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
E.2.8 body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
E.2.9 beam slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
E.2.10 brake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
E.2.11 clamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
E.2.12 deformable joints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
E.2.13 distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
E.2.14 drive displacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
E.2.15 drive displacement pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
E.2.16 gimbal rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
E.2.17 inline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
E.2.18 inplane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
E.2.19 prismatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
E.2.20 relative frame structural node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
E.2.21 revolute hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
E.2.22 revolute rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
E.2.23 rod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
E.2.24 spherical hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
E.2.25 spherical pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
E.2.26 structural forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
E.2.27 structural node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
E.2.28 total joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
E.2.29 total pin joint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
E.2.30 universal hinge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
E.2.31 universal pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
E.2.32 universal rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
E.3 Analysis Description Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
E.3.1 inertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
E.3.2 output frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
E.3.3 struct node dofs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
E.3.4 struct node momentum dofs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
E.3.5 struct node labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
E.4 Output Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
E.4.1 RTAI stream output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
9E.4.2 INET socket stream output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
E.4.3 local socket stream output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
E.4.4 output element content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
E.5 File drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
E.5.1 INET socket stream file driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
F Frequently Asked Questions
340
F.1 Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
F.1.1 What is the exact syntax of element X ? . . . . . . . . . . . . . . . . . . . . . . . . 340
F.1.2 What element should I use to model Y ? . . . . . . . . . . . . . . . . . . . . . . . . 340
F.2 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
F.2.1 How can I reduce the amount of output? . . . . . . . . . . . . . . . . . . . . . . . 341
F.3 Execution Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
F.3.1 How can I find out why the iterative solution of a nonlinear problem does notconverge? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

10

List of Figures
2.1
2.2

Predefined constants in math parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Construction of 3 × 3 orientation matrix from two non-parallel vectors. . . . . . . . . . . .

23
32

8.1 Airfoil geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
8.2 Constitutive coefficients grouping (S: shear, A: axial) . . . . . . . . . . . . . . . . . . . . . 163
8.3 Beam section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
8.4 Geometry of the three-node beam element. . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.5 Geometry of the two-node beam element. . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
8.6 NASTRAN CONM2 card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
8.7 Discrete control layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.8 Cardano hinge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.9 Inline joint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.10 Revolute hinge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
8.11 The rod bezier element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
8.12 Spherical hinge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
8.13 Shell: definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

11

List of Tables
2.1
2.2
2.3
2.4
2.5
2.6
2.7

Built-in mathematical operators in math parser (from higher to lower precedence) . . . .
Built-in types in math parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined variables and constants in math parser . . . . . . . . . . . . . . . . . . . . . .
Built-in mathematical functions in math parser . . . . . . . . . . . . . . . . . . . . . . . .
Functions in the model namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Drive callers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constitutive laws dimensionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.1
4.2
4.3

Linear solvers properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Linear solvers memory usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Linear solvers pivot handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

12

22
23
24
25
27
47
73

Introduction
This document describes the format of the input data for MBDyn, the Multibody Dynamics analysis
suite. It should be considered a syntax more than a format, since the rules of the input allow a lot of
freedom in the file format.
As the title states, this manual describes the syntax of the input. The reader should not expect tolearn how to model systems from this text; it is rather a reference manual where the user can find theexact and detailed description of the syntax of some entity, where it is assumed that the user alreadyknows that entity exactly does what is required to model that system or solve that problem.
To get on the right track, one may have a look at the Frequently Asked Questions (Appendix F),
a steadily growing chapter that collects the most common issues arising from users. They might help
pointing to the right statement for a given purpose, but in any case nothing can replace the judgment of
the user about what entity exactly fits some need. The only document that may help users in growing
this type of judgment is the tutorials book, available from the website. For more specific questions, one
should try the
mbdyn-users@mbdyn.org
mailing list (browse the archives, just in case, then post a question; posting is restricted to subscribers;
subscription is free).

Conventions on the Notation
Throughout the manual, a (sometimes naı̈ve) Backus-Naur-like syntax description is used. Extensions
are made, such as to put optional arguments in square brackets ‘[]’, mutually exclusive arguments incurly brackets ‘{}’, separated by the operator ‘|’ (the logical “OR”). Non-terminal symbols are enclosed
in angle brackets ‘<>’, while terminal symbols are written in normal types. The association of a nonterminal with terminal or non-terminal symbols is performed by means of the operator ‘::=’. Whenrequired, the type of a non-terminal symbol is enforced in a “C” programming language casting style, by
prepending a (usually self-explanatory) type enclosed in plain brackets ‘()’.

Remarks
The input of the program MBDyn is subject to continuous changes at a fast pace, since the code isunder development. This documentation attempts to give some insight into the logic that drove its
implementation.
While most of the software resulted from a careful design, some portions are “as they are” only because
they were made in a hurry, or because no better way was at hand at the moment they were made. The
input format partially reflects the development of the software. Whenever changes in the input format
and in the syntax of existing parts are required, an effort will be attempted to make it as much backward

13

compatible as possible, or at least reliable diagnostics and error checking will be put in place that warns
for possible erroneous inputs related to a change in the input format.
At present the input of MBDyn already warns for many possible errors and makes as many crosschecks as possible on the consistency of the data. Nearly every warning and error issue shows the line of
the input file where the error occurred.
This document will be subjected to changes, so be sure you always have a release that is aligned withthe version of the code you’re running.
For any question or problem, to fix typos, bugs, for comments and suggestions, please contact theusers’ mailing list
mbdyn-users@mbdyn.org
Please note that you need to subscribe to be allowed to post to the list. Posting is public, so please
only post information not subjected to distribution restrictions.
Mailing list subscription information is available on the web site
http://www.aero.polimi.it/mbdyn/
As an alternative, you can directly contact the Developers’ Team:
Pierangelo Masarati,
MBDyn Development Team
Dipartimento di Ingegneria Aerospaziale
Politecnico di Milano
via La Masa 34, 20156 Milano, Italy
Fax:+39 02 2399 8334
E-mail: mbdyn@aero.polimi.it
Web:
http://www.aero.polimi.it/mbdyn/
This manual is also available online at
http://www.aero.polimi.it/masarati/MBDyn-input/manual/index.html
Make sure you use the manual that refers to the version of MBDyn that you are using; from MBDyn
1.2 on, the input manual is marked with the same version number of the package.
The website http://www.mbdyn.org/ may advertise different versions of the manual, including thoserelated to past releases and a HEAD or -devel version, which refers to current development; this canbe useful to check whether the current development may address problems you are having. Moreover,since the updating of the manual is not as prompt as required to keep pace with code releases, the -devel
manual may describe features that are already in the latest release but not yet documented in that
release’s manual.

14

Chapter 1

Overview
This chapter gives a global overview of the structure of the input file.

1.1

Execution

MBDyn is a command-line tool. This means that in order to execute it, one needs to start the executablefrom a terminal, and, as a minimum, pass it some indications about the problem it must analyze.
Usually, this is done by preparing one or more input files that describe the model and the analysis
that needs to be performed.

1.1.1

Passing the Input

The input file can be passed either using a specific switch (-f, preferred), or by listing multiple input
file names on the command line. In the latter case, the analyses are executed in sequence. The formatof the input file is the topic of most of this manual. If no input file is defined, MBDyn as a last resort
tries to read from the standard input. As a consequence, the following commands are equivalent:# assuming file "input" exists in the current working directory and is readable...
$ mbdyn -f input$ mbdyn input$ mbdyn < input
They are listed in order of preference.
If the input file name consists of a path, either absolute or relative, the file can reside anywhere in
the file system. In this case, MBDyn changes its current working directory (see chdir(2) for details)
to the directory where the input file resides. As a consequence, the path of any included file is seen as
relative to the directory where the file containing the include directive is located (see Section 2.4.5 fordetails).

1.1.2

Passing the Output File Name

The output is stored in a family of files whose common name is passed through another switch (-o).
Those files are formed by adding an extension specific to their contents to the output file name. If none
is defined, the output file name defaults to MBDyn.
If the argument of the -o switch consists of a path, either absolute or relative, and a file name, thefull path up to the file name excluded must exist and be write-accessible. The output files are stored in15the corresponding directory. Otherwise they are stored in the current working directory of the process
at the time of its execution.
If the argument of the -o switch consists of exactly a directory, either absolute or relative, without
any file name, the name of the input file is used, but the output files are placed in the directory indicatedin the argument of the -o switch.
For example:$ mbdyn -f input$ mbdyn -f input -o output$ mbdyn -f input -o folder/output$ mbdyn -f input -o folder/$ mbdyn < input

1.2# output in "input.<extension>"# output in "output.<extension>"# output in "folder/output.<extension>"# output in "folder/input.<extension>"# output in "MBDyn.<extension>"

Input File Structure

The input is divided in blocks. This is a consequence of the fact that almost every module of the codeneeds data and each module is responsible for its data input. So it is natural to make each module readand interpret its data starting from the input phase.
Every statement (or ‘card’) follows the syntax:<card> ::= <description> [ : <arglist> ] ;arglist is a(n optional) list of arguments, that is driven by the description that identifies the card.
The keyword can be made of multiple words separated by spaces or tabs; the extra spaces1 are skipped,
and the match is case insensitive. The arguments are usually separated by commas2 . A semicolon ends
the card.
Many cards allow extra arguments that may assume default values if not supplied by the user. Usuallythese arguments are at the end of the card and must follow some rules. A check for the existence of
extra args is made, and they are usually read in a fixed sequence. Optional args are usually prefixed bya keyword.
When structured arguments like matrices, vectors, or drive callers are expected, they are parsed bydedicated functions. Anyway, the structured data always follows the rules of the general data. Few
exceptions are present, and will be eliminated soon. Every data block is surrounded by the control
statements begin and end:
begin : <block_name> ;# block content
end : <block_name> ;The block sequence is:begin : data ;# select a problem
problem : <problem_name> ;end : data ;begin : <problem_name> ;# problem-specific data
1 Anything that makes the C function isspace() return true
2 A few exceptions require a colon to separate blocks of arguments; wherever it is feasible, those exceptions will beeliminated in future versions. Those cards will be marked as deprecated.

16

end : <problem_name> ;begin : control data ;# model control data
end : control data ;begin : nodes ;# nodes data
end : nodes ;# note: optional, if requested in control data
begin : drivers ;# special drivers data
end : drivers ;begin : elements ;# elements data
end : elements ;The drivers block is optional.
The Schur solver allows an extra block after that of the elements:# note: optional; only allowed when Schur solver is defined in problem_namebegin : parallel ;# parallel data
end : parallel ;where data specific to the partitioning and the connectivity of the Schur solver is provided. This is yet
undocumented, and will likely be described in a future chapter.
Chapter 2 describes the basic and aggregate data structures that concur in building up the cards.
Chapter 3 describes problem selection options. Chapter 4 describes the cards dedicated to the specification of the parameters of the simulation and of the selected integration scheme. Chapter 5 describes
the model control data. Chapter 6 describes the cards related to the input of nodes. Nodes come first
because they are the elementary blocks of the connectivity graph of the model, so historically they had
to be defined before any element could be introduced. Chapter 7 describes the cards related to special
drivers. Chapter 8 describes the cards related to the input of elements.

1.2.1

Syntax Highlighting

To ease the creation of MBDyn file, several syntax highlighting plugins, for different text editors, can beused:• Vim (and its GUI variants): syntax highlighting for MBDyn can be activated by adding the<mbdyn-directory>/var/mbd.vim file to the ~/.vim/syntax/ folder;• Geany: the methodology to add MBDyn syntax highlighting is given in Geany’s wiki.
• Kate and KWrite: instructions to add MBDyn syntax support can be found here;• Atom: the language-mbdyn package can be installed directly from the Atom Preferences->Install
panel: it provides both MBDyn syntax highlighting and autocompletion snippets.

17

1.3

Output

The program outputs data to a set of files for each simulation. The contents of each file is related to thefile extension, which is appended to the input file if no output file name is explicitly supplied.
If no input file is explicitly provided as well, and thus input is directly read from stdin, the output
file name defaults to ‘MBDyn’. Otherwise, unless the output file name is explicitly set, the name of the
input file is used.
The contents of the output files are described within the description of the items (nodes or elements)that generate them. Only a general information file, with extension .out, is described here. The filecontains general information about the simulation; it is not formatted.
The file contains occasional informational messages, prefixed by a hash mark (‘#’). These messages
should be intended as comments about the current status of the simulation. At some point, after
initialization completes, the comment# Step Time TStep NIter ResErr SolErr SolConv
appears, which illustrates the contents of the lines that will be written for each time step. The fields
indicate:
1. Step: the time step number;
2. Time: the time at that step;
3. TStep: the time step at that step (Timek - Timek−1);
4. NIter: the number of iterations required to converge;
5. ResErr: the error on the residual after convergence (0 if not computed);
6. SolErr: the error on the solution after convergence (0 if not computed);
7. SolConv: a boolean that indicates whether convergence was determined by the error criterion on
the residual or on the solution (0 for residual, 1 for solution).
There is also a supplementary file, with .log extension, that may contain extra (logging) information.
Its content, although very experimental and subjected to changes, is documented in Appendix E.
Experimental support for output using the NetCDF database format is available for selected items.
See Appendix C for details.

18

Chapter 2GeneralThis chapter describes how data structures are read and how they participate, as building blocks, to thedefinition of specific cards. Consistency across the software and the input file has been a driving principle
in designing the input of MBDyn. As such, the very same elementary data structures are present in very
different contexts.

2.1

Types

2.1.1

Keywords

In MBDyn’s input a lot of so-called “keywords”appear literally in the input file. They are case-insensitiveand may have an arbitrary amount of space in between. For example, ‘control data’, ‘Control Data’,and ‘controldata’ are equivalent.
However, most of the keywords are context-dependent, so they are not illustrated altogether in a
dedicated section, but rather presented in relation to the contexts they may appear in.

2.1.2

Strings

Literal strings are not used very much in MBDyn. However, they may be used in quite a few significant
places, for example to indicate file names, so few details on their syntax are provided.
Strings are typically delimited by double quotes (‘"’). When a string is expected, the parser looks
for the opening double quotes and eats up all the white space before it. Then all characters are read as
they are until the closing double quotes are encountered. The escape character is the backslash (‘\’); it
is used:• to escape the escape character itself (‘\’);• to escape any double quotes that are part of the string, and would otherwise be interpreted as theclosure of the string;• to break a string on multiple lines by placing it before the newline character (‘\n’); in this case,the escape character and the newline are eaten up;• to allow the use of non-printing characters, represented in the form ‘\<hexpair>’, so that thehexadecimal representation of the non-printing char is converted into its integer equivalent in the
0–255 range.
Character sets different from ASCII are not supported.
19

2.1.3

Numeric Values

Every time a numeric value is expected, the result of evaluating a mathematical expression can beused, including variable declaration and assignment (variable names and values are kept in memory
throughout the input phase and the simulation) and simple math functions. Limited math on strings isalso supported. Named variables and non-named constants are strongly typed. Four types are currently
available: bool, integer, real, and string.
Bool
A bool can take the values 0 or 1. In the symbol table, the constants TRUE ( = 1) and FALSE ( = 0) are
predefined. Casting from integer and real to bool is supported; zero casts to (bool)0 and non-zero
casts to (bool)1.
Integer
An integer can take any integer value between the predefined constants INT_MIN and INT_MAX (which aremachine-dependent; the C built-in type int is used). Integers are signed. Please note that any sequenceof digit not terminated by a dot (‘.’) is interpreted as an integer. Thus, very large numbers, intended
as real, might overflow. Use the exponential notation, instead, or terminate real-valued numbers witha dot.
Examples:
0
1
1234
-12
1000000000000000 # this likely overflows!
RealA real can take any real value between the predefined constants REAL_MIN and REAL_MAX (which aremachine-dependent; the C built-in type double is used). Any number that contains a dot (‘.’) is treatedas real.
Examples:
0.
1.
1.234
-1.2
1000000000000000. # same as 1e15
1e15 # same as 1000000000000000.
StringA string is an arbitrary sequence of characters. Currently, only basic chars (i.e. 0 to 127) are guaranteed
to work. Strings are enclosed in double quotes (‘"’).

20

Examples:"0""1""hello"Label
Labels are not actually types. They are treated separately because they play an important role inidentifying several simulation entities. Currently, only unsigned integer values can be used as labels.
Please note that unsigned integers are not treated specially by the mathematical parser, but negative
integers will be rejected when used as labels. In the future, string values might be used as labels.

2.2

Variables

Variable declaration/definition:<declaration> ::= [<declaration_modifier>] [<type_modifier>] <type> <name><definition> ::= [<declaration_modifier>] [<type_modifier>] <type> <name> = <value><declaration_modifier> ::= ifndef<type_modifier> ::= const<type> ::= { bool | integer | real | string }<name> ::= [_[:alpha:]][_[:alnum:]]*The declaration_modifier ifndef declares the variable only if it does not exist yet, otherwise it isignored.
The type_modifier const requires the initialization by assigning a value, since the variable would
remain uninitialized as const variables cannot be assigned a value later.
Examples:set: integer N;
set: const integer M = 100;
set: string welcome_message = "hello";
set: const real x = -1.e-3;
set: real y;set: bool B;
set: const real z; # error!
Operations are strongly typed and perform implicit cast when allowed. For instance 1+2.5 returns areal whose value is 3.5, since one of the two addenda is real, while 1/3 returns 0 because both values
are implicit integers and thus the integer division is used.
An empty field, delimited by a valid separator (a comma or a semicolon, depending on whether otherarguments are expected or not) returns the (program supplied) default value for that field, if suppliedby the caller, otherwise the parser automatically defaults to zero.
Multiple expressions can be used, provided they are enclosed in plain brackets and are separated
by semicolons; the result of the last expression will be used as the expected numeric value, but all
the expressions (which may have persistent effects, like variable declarations and assignments) will be
evaluated.

21

Table 2.1: Built-in mathematical operators in math parser (from higher to lower precedence)
Operator
Type
Description^
Binary, right Power+
Unary, left
Plus sign
Unary, left
Minus sign*
Binary, left
Multiplication/
Binary, left
Division+
Binary, left
Addition
Binary, left
Subtraction>
Binary, left
Greater than>=Binary, left
Greater than or equal to==
Binary, left
Equal to<=Binary, left
Less than or equal to<
Binary, left
Less than!=Binary, left
Not equal!
Unary, right NOT&&
Binary, left
AND||
Binary, left
OR~|
Binary, left
XOR (exclusive OR)=
Binary, right Assignment
Note: “left” and “right” refer to the associativity of the operators.
Note: the string type only supports the binary “+” operator.

Example.
1.
(real r = 2.*pi; integer i = 3; sin(i*r*Time+.87))# == 1.
# == sin(6*pi*Time+.87)

The latter sequence evaluates to sin (6πt + .87), depending on the current value of the pre-defined variable
Time. The constant pi is always defined as π with machine precision (the macro M_PI in the standard C
header file math.h). Other constants are pre-defined, as illustrated in Table 2.3.
When MBDyn is invoked with the ‘-H’ option,
mbdyn -H
it prints the predefined variables table. A typical output is shown in Figure 2.2. Real values are storedwith the maximum precision allowed by the underlying real type (by default, double precision, 64 bit).
The variable Time is declared, defined and initialized1 from the beginning of the control data section,and during the solution phase it is assigned the value of the current time.
Table 2.1 shows the supported mathematical operators, while Table 2.4 shows the built-in mathematical functions. In addition, type names used as functions provide explicit type casting according tobuilt-in casting rules.
The supported types are listed in Table 2.2. Table 2.3 lists the predefined variables; notice thatthey’re treated exactly as user-defined variables, so they can be reassigned.
Example.
• Print a zeros-padded integer: the statement
1 Note: a variable is declared when its name enters the namespace; it is defined when it can be referenced; it is initialized
when it is first assigned a value.

22

user@host:~> mbdyn -H
MBDyn - MultiBody Dynamics 1.X-Develconfigured on Sep 3 2012 at 12:16:44
Copyright 1996-2017 (C) Paolo Mantegazza and Pierangelo Masarati,
Dipartimento di Ingegneria Aerospaziale <http://www.aero.polimi.it/>
Politecnico di Milano<http://www.polimi.it/>
MBDyn is free software, covered by the GNU General Public License,and you are welcome to change it and/or distribute copies of it
under certain conditions. Use ’mbdyn --license’ to see the conditions.
There is absolutely no warranty for MBDyn. Use "mbdyn --warranty"
for details.
default symbol table:
const bool FALSE = 0
const integer INT_MAX = 2147483647
const integer INT_MIN = -2147483648
const integer RAND_MAX = 2147483647
const real REAL_MAX = 1.79769e+308
const real REAL_MIN = 2.22507e-308
const bool TRUE = 1
const real deg2rad = 0.0174533
const real e = 2.71828
const real ft2m = 0.3048
const real in2m = 0.0254
const real in2mm = 25.4
const real kg2lb = 2.20462
const real kg2slug = 0.0685218
const real lb2kg = 0.453592
const real m2ft = 3.28084
const real m2in = 39.3701
const real mm2in = 0.0393701
const real pi = 3.14159
const real rad2deg = 57.2958
const real slug2kg = 14.5939
MBDyn terminated normally

Figure 2.1: Predefined constants in math parser

Name
bool
integerreal
stringTable 2.2: Built-in types in math parser
Description
Boolean number (promoted to integer, real, or string (0 or 1), whenever required)
Integer number (promoted to real, or string, whenever required)Real number (promoted to string whenever required)
Text string

23

Table 2.3: Predefined variables and constants in math parser
Name
Type
Value
Time
Real
Current simulation time
TimeStep Real
Current simulation time step
Step
Integer Current simulation stepVar
RealSet by dof, node, or element drive callers with degree of freedom value, node or element private data
value, respectively
e
pi

Real
Real

Neper’s number
π

FALSE
TRUE

Bool
Bool

‘false’‘true’

INT_MAXINT_MINRAND_MAXREAL_MAXREAL_MIN

Integer
Integer
IntegerReal
Real

Largest integer
Smallest integer
Largest random integer
Largest real
Smallest real

in2m
m2in
in2mm
mm2in
ft2m
m2ft
lb2kg
kg2lb
deg2radrad2degslug2kgkg2slug

Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real

Inch to meter ratio (0.0254)
Meter to inch ratio (1.0/0.0254)
Inch to meter ratio (25.4)
Meter to inch ratio (1.0/25.4)
Foot to meter ratio (0.3048)
Meter to foot ratio (1.0/0.3048)
Pound to kilogram ratio (0.45359237)
Kilogram to pound ratio (1.0/0.45359237)
Degree to radian ratio (π/180)
Radian to degree ratio (180/π)
Slug to kilogram ratio (14.5939)
Kilogram to slug ratio (1.0/14.5939)

24

Name
abs
acos
acosh
actan
actan2
actanh
asinh
atanh
asin
atan
atan2
ceil
copysign
cos
cosh
ctan
ctanh
exp
floor
in_ee
in_el
in_le
in_ll
log
log10
min
max
par
print
ramp
rand
random
round
seed
sign
sin
sinh
sprintf
sqrt
sramp
step
stop
tan
tanh

Table 2.4: Built-in mathematical functions in math parser
Returns
Arg[s]
Description
real
real
absolute value
real
real
arc cosine
real
real
hyperbolic arc cosine
real
real
arc co-tangent
real
real, real(robust) arc co-tangent
real
real
hyperbolic arc co-tangent
real
real
hyperbolic arc sine
real
real
hyperbolic arc tangent
real
real
arc sinereal
real
arc tangent
real
real, real(robust) arc tangent
integerrealclosest integer from above
real
real, realfirst arg with sign of second
real
real
cosinereal
real
hyperbolic cosine
real
real
co-tangent
real
real
hyperbolic co-tangent
real
real
exponential
integerrealclosest integer from belowboolreal, real, real true when arg1 ≤ arg2 ≤ arg3, false otherwiseboolreal, real, real true when arg1 ≤ arg2 < arg3, false otherwiseboolreal, real, real true when arg1 < arg2 ≤ arg3, false otherwiseboolreal, real, real true when arg1 < arg2 < arg3, false otherwise
real
real
natural logarithm
real
real
base 10 logarithm
real
real, real
returns the smallest of the two inputs
real
real, real
returns the largest of the two inputs
real
real
parabolic function
void
real
prints a value to standard output
real
real
ramp function
integervoid
random integer [0, RAND MAX]
real
void
random real [−1.0, 1.0]
integerrealclosest integer
void
integerseeds the random number generator
real
real
sign
real
real
sine
real
real
hyperbolic sine
stringstring, any
returns a string with value formatted according to format
real
real
square root
real
real, real
saturated ramp function
real
real
step function
integerbool, integer
stops and returns second arg if first is true
real
real
tangent
real
real
hyperbolic tangent

25

remark: sprintf("%04d", 9);yieldsline 1, file <initial file>: "0009"• Print an integer in hexadecimal format: the statement
remark: sprintf("0x%x", 255);
yieldsline 1, file <initial file>: "0xff"• Print a string that formats multiple numbers: the statement
remark: sprintf("N%04d", 9) + " = " + sprintf("%e", 0.1);
yieldsline 1, file <initial file>: "N0009 = 1.000000e-01"

2.2.1

Namespaces

The math parser uses the notion of namespace to separate functions. The functions listed in Table 2.4
are implicitly defined in the default namespace, i.e. they should be referenced by writing
default::sqrt(2.)
Other namespaces may be defined by the user, and loaded by means of the module load card describedin Section 2.4.6.
The namespace that refers to the current model is loaded by default. Its name is model, and contains
the functions defined in Table 2.5. With the exception of the drive and sf functions, all functions in
the model namespace with the suffix _prev (e.g. position_prev) use the configuration at the previous
time step. They may be useful, for example, when parsing hints (see Section 2.6.38), since hint parsing
occurs after prediction, but often needs to refer to the configuration at the previous, just completed time
step.
Example 1. This string returns the y component of the relative angular velocity between structuralnodes “NODENAME_1” and “NODENAME_2” at the current timestep:
string, "model::yangvrel(NODENAME_1,NODENAME_2)", ...
Example 2. This string returns the absolute x component of the position of node “NODENAME” at theprevious timestep, plus the value of “DRIVE_1 * DRIVE_2” when time is greater than 5 seconds:
drive, string, "model::xposition_prev(NODENAME) + \model::drive(DRIVE_1, Time) * model::drive(DRIVE_2, Time) * (Time > 5.)",26

Table 2.5: Functions in the model namespaceName
position
position2
xposition
yposition
zposition
distance
distance2
xdistance
ydistance
zdistance
xunitvec
yunitvec
zunitvec
angle
xangleyanglezangleanglerelxanglerel
yanglerel
zanglerelvelocity
velocity2
xvelocity
yvelocity
zvelocity
vrel
vrel2
xvrel
yvrel
zvrel
angvelangvelxangvelyangvelzangvelangvrelangvrel2
xangvrelyangvrelzangvrelcurrent
drive

Ret.
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real
Real

sf::<name>Real

node::<type>element::<type>

Real
Real

Arg[s]
Integer
Integer
Integer
Integer
Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer
Integer
Integer
Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer
Integer
Integer
Integer
Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer
Integer
Integer
Integer
Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
Integer, Integer
StringInteger, Real

Description
norm of structural node positionsquare norm of structural node position
X component of structural node position
Y component of structural node position
Z component of structural node position
distance between structural nodes
square distance between structural nodes
X component of distance between structural nodes
Y component of distance between structural nodes
Z component of distance between structural nodes
X component of unit vector between structural nodes
Y component of unit vector between structural nodes
Z component of unit vector between structural nodes
norm of rotation vector of structural node
X component of structural node rotation vector
Y component of structural node rotation vector
Z component of structural node rotation vector
angle between structural nodes (norm of rotation vector)
X component of rotation vector between structural nodes
Y component of rotation vector between structural nodes
Z component of rotation vector between structural nodes
norm of structural node velocity
square norm of structural node velocity
X component of structural node velocity
Y component of structural node velocity
Z component of structural node velocity
norm of relative velocity between structural nodes
square norm of relative velocity between structural nodes
X component of relative velocity between structural nodes
Y component of relative velocity between structural nodes
Z component of relative velocity between structural nodes
norm of structural node angular velocity
square norm of structural node angular velocity
X component of structural node angular velocity
Y component of structural node angular velocity
Z component of structural node angular velocity
norm of relative angular velocity between structural nodes
square norm of rel. angular velocity between structural nodes
X component of rel. angular velocity between structural nodes
Y component of rel. angular velocity between structural nodes
Z component of rel. angular velocity between structural nodes
allows to retrieve data specific to the current context
evaluates the drive caller indicated by its label (the firstargument) for the input specified as second argument
Real, (opt)Integer
evaluates the scalar function name for the input specified asargument (value, optional derivative order)
Integer, String
evaluates a private datum of a node (label, string)(opt)Integer, String evaluates a private datum of an element (label, string)27

2.2.2

Plugin Variables

Plugin variables, or plugins, as the name states, are pluggable extensions to the math parser that allow
to register mechanisms to bind a variable to some means to dynamically generate its value. As aconsequence, any time a variable declared as part of a plugin is used, its value is dynamically evaluatedexecuting the related code.
There are built-in plugins that allow to link variables to the value of degrees of freedom and to special
parameters computed by nodes and elements.
The syntax of a plugin consists in specially defining a variable so that it gets registered to theappropriate code:
set : OSQBR <plugin> , <var> [ , <arglist> ] CSQBR ;<arglist> ::= <arg> [ , ... ]where OSQBR and CSQBR stand for ‘open’ and ‘close’ square brackets, respectively, which should not be
confused with those that indicate optional parameters.
In the following, the built-in plugins2 are illustrated. For details on nodes, elements, their properties
and the information they can expose, see the related sections.
Dof plugin
Note: this plugin is now obsoleted by the node plugin, which allows to access more significant information
about nodes, including the value of the degrees of freedom.
The dof plugin allows to link a variable to a specific degree of freedom of a node, or to its derivative,
whenever defined. The syntax is<plugin> ::= dof<arglist> ::= <label> , <type>[ , <index> ] ,{ algebraic | differential }[ , prev= <prev> ]<prev> ::= { true | false }where label is the label of the node, type is the node type, index is the index of the degree of freedomthat is requested, if the node has more than one, while algebraic and differential refer to the valueof the dof and of its derivative, respectively. The derivative can be requested only for those degrees of
freedom that have one. When prev is true, the value at the previous time step is used.
Example.

The variable VARNAME takes the value of the derivative of abstract node NODENAME

set: integer NODENAME = 1000;# the node must exist
set: [dof,VARNAME,NODENAME,abstract,differential];
2 Built-in and plug-in may sound contradictory, and in fact they are. However, consider that the mathematical parser
is essentially independent of MBDyn (in fact, it has been turned into a command-line calculator in cl(1)), so, from thispoint of view, built-in plug-ins are used to plug MBDyn information into an independent, lower-level piece of code.

28

Node plugin
The node plugin allows to link a variable to any data a node can expose, including the values of its
degrees of freedom. The syntax is<plugin> ::= node<arglist> ::= <label> , <type>[ , { string= <name> | index= <index> } ] # index is deprecatedwhere label is the label of the node, type is the node type, and the mutually exclusive index and namerepresent the index of the datum that is requested, name being a user-friendly representation of the actualindex. The index form is the default; however, the name form is recommended. Note that name should
be enclosed in double quotes, although not strictly required. In fact, some node types allow data namesthat include square brackets. In those cases, double-quote enclosing is needed to avoid parsing errors,since closing square brackets indicate the end of the plugin variable specification.
Example. This implements a variable VARNAME with exactly the same value of the one defined in theexample of the dof plugin, where the variable takes the value of the derivative of the abstract node
NODENAME
set: integer NODENAME = 1000;# the node must exist
set: [node,VARNAME,NODENAME,abstract,string="xP"];
Element plugin
The element plugin allows to link a variable to any data an element can expose, including the values of
its degrees of freedom. The syntax is<plugin> ::= element<arglist> ::= <label> , <type>[ , { string= <name> | index= <index> } ] # index is deprecatedwhere label is the label of the element, type is the element type, and the mutually exclusive index andname represent the index of the datum that is requested, name being a user-friendly representation of theactual index. The index form is the default; however, the name form is recommended. Note that nameshould be enclosed in double quotes, although not strictly required. In fact, some element types allow
names that include square brackets. In those cases, double-quote enclosing is needed to avoid parsing
errors, since closing square brackets indicate the end of the plugin variable specification.
Example.
ELEMNAME

The variable VARNAME takes the value of the z component of the reaction force of joint

set: integer ELEMNAME = 1000;# the joint must exist
set: [element,VARNAME,ELEMNAME,joint,string="Fz"];

2.3

Higher-Order Math Structures

Every time a higher-order mathematical structure is expected, it can be preceded by a keyword that
influences how the structure is read. All of the available structures support the keyword null whichcauses the structure to be initialized with zeros. When a non-null value is input, it can be followed by29

the keyword scale with a scale factor; the scale factor can be any mathematical expression. This isuseful to rescale structure values by reassigning the value of the scale factor. The main data structures
are:

2.3.1

3 × 1 Vector

Implements the type Vec3.
1. general case: a sequence of 3 reals, comma-separated.
2. null vector: keyword null; the vector is initialized with zeros.
As an example, all the following lines define an empty 3 × 1 vector:
default
null
0.,0.,0.
,,the first case is correct if no default was actually available for that specific vector, thus falling back tothree zeros. The following rescales an arbitrary vectorcos(pi/3.),0.,sin(pi/3.), scale, 100.

2.3.2

6 × 1 Vector

Implements the type Vec6.
1. general case: a sequence of 6 reals, comma-separated.
2. null vector: keyword null; the vector is initialized with zeros.

2.3.3

3 × 3 Matrix

Implements the type Mat3x3.
1. general case: a sequence of 9 reals, comma-separated, which represent the row-oriented coefficients
a11 , a12 , . . . , a32 , a33 . Note: the 9 coefficients can be preceded by the keyword matr for consistency
with other entities; its use is recommended whenever an ambiguity is possible.

a11 a12 a13
m =  a21 a22 a23 (2.1)
a31 a32 a33
2. symmetric matrix: keyword sym, followed by a sequence of 6 reals, comma-separated, that represents the upper triangle, row-oriented coefficients of a symmetric matrix, e.g. a11 , . . . , a13 , a22 ,
a23 , a33 .

a11 a12 a13
m =  a12 a22 a23 (2.2)
a13 a23 a33

30

3. skew symmetric matrix: keyword skew, followed by a sequence of 3 reals, comma-separated, thatare the components of the vector v that generates a skew symmetric matrix m = v × :0−v3 v20−v1 m =  v3
(2.3)
−v2 v10
4. diagonal matrix: keyword diag, followed by a sequence of 3 reals, comma-separated, that represent
the diagonal coefficients of a diagonal matrix, namely a11 , a22 , a33


a11 0
0
m =  0 a22 0 
(2.4)
0
0 a33
5. identity matrix: keyword eye; the matrix is initialized as the identity matrix, that is a null matrix
except for the diagonal coefficients that are 1.
6. null matrix: keyword null; the matrix is initialized with zeros.
For example, the identity matrix can be defined as:
matr, 1.,0.,0., 0.,1.,0., 0.,0.,1.
1.,0.,0., 0.,1.,0., 0.,0.,1.
sym, 1.,0.,0., 1.,0., 1.
diag, 1.,1.,1.
eye# ‘‘matr’’ omitted# upper triangular part
# diagonal# a la matlab

Although not required, for better readability it is recommended to format the above data as
matr,
1.,0.,0.,0.,1.,0.,0.,0.,1.
1.,0.,0.,0.,1.,0.,0.,0.,1.
sym,
1.,0.,0.,1.,0.,
1.
diag, 1.,1.,1.
eye

2.3.4

# ‘‘matr’’ omitted# upper triangular part
# diagonal# a la matlab(3 × 3) Orientation Matrix

Implements the type OrientationMatrix.

1. general case: two vectors that define an orthonormal reference system, each of them preceded by
its index in the final orientation matrix. The procedure that builds the orientation matrix from thetwo vectors is illustrated in Figure 2.2. The first vector, vector 1 in subfigure (a), is normalized andassumed to represent the desired direction. The second vector, vector 2’ in subfigure (b), simply
concurs in the definition of the plane the vector that is not given is normal to. The third vector,
31

3
2

3

1

3
2

2’
(a)

1

2’

1

2’

1

(b)

(c)

1
(d)

Figure 2.2: Construction of 3 × 3 orientation matrix from two non-parallel vectors.
vector 3 in subfigure (c), results from the cross-product of the first two vectors, after normalization.
The actual direction of the second vector, vector 2 in subfigure (d), results from the cross productof the third and the first vector. Examples:
1, 1.,0.,0., 2, 0.,1.,0.
1, (real ALPHA = pi/6.; cos(ALPHA)), sin(ALPHA), 0.,3, 0.,0.,1.
The first example represents the identity matrix, i.e. no rotation occurs with respect to the global
reference frame: direction 1 in the local frame is parallel to 1.,0.,0., which represents direction
1 in the global frame, while direction 2 in the local frame is parallel to 0.,1.,0., which represents
direction 2 in the global frame.
The second example describes a rotation of π/6 radian about global direction 3: direction 1 in thelocal frame results from composing cos(pi/6.) in global direction 1 and sin(pi/6.) in global
direction 2, while direction 3 in the local frame remains parallel to 0.,0.,1., which represents
direction 3 in the global frame.
2. a variant of the above, which may be useful when only one direction really matters, is illustrated
in the example below:
1, 1.,0.,0., 2, guess
The keyword guess tells the parser to generate a random vector that is orthogonal to the given one,which is used as the direction indicated by the index (2 in the example). The vector is computed
based on a very simple algorithm: it contains• 1.0 corresponding to the index with smallest module, v1 (min);• −v1 (min) /v1 (max) corresponding to the index with the largest module, v1 (max);• 0.0 on the remaining index.

3. identity matrix: keyword eye; the identity matrix, which means there is no rotation with respect
to the global reference frame.
32

4. a complete orientation matrix: keyword matr followed by the nine, row-oriented, coefficients,
namely r11 , r12 , . . . , r33 . Note: no orthogonality check is performed; be sure an orthogonal matrix,
within the desired tolerance, is input.
5. Euler angles: keyword euler, followed by the three values, as output by structural nodes. The
keywords euler123, euler313 and euler321 allow to use orientations in the sequence specified by
the keyword.
{ euler | euler123 | euler313 | euler321 } ,[ degrees , ]<angle_1> , <angle_2> , <angle_3>
Note: the output in the .mov file is in degrees, while in input MBDyn requires angles in radians,
unless the values are preceded by the keyword degrees.
Note: the definition of the three angles that are used by the code to express orientations may vary
between versions. Currently, Bryant-Cardano angles are used in place of Euler angles; see the noterelated to the output of the structural nodes in Section 6.1.5, and the Technical Manual. The code
will remain consistent, i.e. the same angle definition will be used for input and output, but models
over versions may become incompatible, so this syntax should really be used only as a means toquickly reproduce in the input an orientation as resulting from a previous analysis.
6. Orientation vector: keyword vector, followed by the three values, as output by structural nodes.
The resulting matrix is computed as
R = exp (v × )
(2.5)

2.3.5

6 × 6 Matrix

Implements the type Mat6x6.
1. general case: a sequence of 36 reals, comma-separated, that represent the row-oriented coefficients
a11 , a12 , . . . , a65 , a66 .
2. ANBA format: keyword anba, followed by 36 reals, comma-separated, that represent the coefficientsof the beam stiffness matrix as generated by the beam section analysis code ANBA, namely thefollowing transformation is performed:• axis x, in the section plane in ANBA notation, becomes axis 2 in MBDyn notation;• axis y, in the section plane in ANBA notation, becomes axis 3 in MBDyn notation;• axis z, the beam axis in ANBA notation, becomes axis 1 in MBDyn notation;
Note: this format is mainly intended for backwards compatibility with older versions of that beam
section analysis software, which used a different numbering convention for the reference frame thatis local to the beam section.
3. symmetric matrix: keyword sym, followed by a sequence of 21 reals, comma-separated, that represents the upper triangle, row-oriented coefficients of a symmetric matrix, e.g. a11 , . . . , a16 , a22 ,. . . , a26 , . . . , a66 .
4. diagonal matrix: keyword diag, followed by a sequence of 6 reals, comma-separated, that represent
the diagonal coefficients of a diagonal matrix.
5. identity matrix: keyword eye; the matrix is initialized as the identity matrix, that is a null matrix
except for the diagonal coefficients that are 1.
6. null matrix: keyword null; the matrix is initialized with zeros.
33

2.3.6

6 × N Matrix

Implements the type Mat6xN.
1. general case: a sequence of 6 × N reals, comma-separated, that represent the row-oriented coefficients a11 , a12 , . . . , a6(N −1) , a6N .
2. ANBA format: keyword anba, followed by 6 × N reals, comma-separated, that represent thecoefficients of the beam stiffness matrix as generated by the code ANBA, namely the following
transformation is performed:• axis x, in the section plane in ANBA notation, becomes axis 2 in MBDyn notation;• axis y, in the section plane in ANBA notation, becomes axis 3 in MBDyn notation;• axis z, the beam axis in ANBA notation, becomes axis 1 in MBDyn notation;

3. null matrix: keyword null; the matrix is initialized with zeros.

2.4

Input Related Cards(Almost) everywhere in the input file the statement cards defined in the following can be used. They arehandled directly by the parsing object, and merely act as an indirect reference to entities that are notexplicitly enumerated. They are:

2.4.1

Constitutive Law<card> ::= constitutive law : <label> ,[ name , " <name> " , ]<dim> , (ConstitutiveLaw<<dim>D>) <constitutive_law> ;Constitutive laws are grouped by their dimensionality dim, which (up to now) can be any of 1, 3 and 6.
The constitutive_law is parsed according to the rules described in Section 2.10, and can be referenced
later when it needs to be used.

2.4.2

C81 Data

This keyword allows to define and read the c81 data airfoil tables that are used by aerodynamic elements.
<card> ::= c81 data : <label> [ , name , " <name> " ]" <filename> "[ , tolerance , <tolerance> ][ , { free format | nrel | fc511 } ][ , flip ][ , echo , " <output_filename> " [ , free format ] ] ;Data is read from file filename according to the format specified in the following.
The optional keyword tolerance allows to specify the tolerance that is used to determine the boundaries of the linear portion of the lift curve slope.
The traditional format is used unless a format is specified using any of the keywords free format,
nrel or fc511 (the latter is intentionally not documented). The format is automatically inferred byreading the heading line of the input file.

34

The optional keyword flip instructs MBDyn to “flip” the data, i.e. treat the airfoil data as if thesign of the angle of attack changed along with that of the lift and moment coefficients, but not that ofthe drag coefficient. This corresponds to considering the airfoil “upside down”.
The optional keyword echo allows to specify the name of the file that will be generated with the data
just read, for cross-checking purposes. If the following optional keyword is free format, or if data wasread in free format, the echo will also be in free format. Otherwise, it will be in the traditional format.
Traditional Format
The file is in textual form; the traditional format (the default) is:• first line: "%30s%2d%2d%2d%2d%2d%2d" where the first 30 chars are a title string, currently ignored
by MBDyn, followed by 6 consecutive two-digit integers that indicate:– the number ML of Mach points for Cl ;– the number NL of angle of attack points for Cl ;– the number MD of Mach points for Cd ;– the number ND of angle of attack points for Cd ;– the number MM of Mach points for Cm ;– the number NM of angle of attack points for Cm .
The example in var/naca0012.c81 contains:
1........01........01........0MLNLMDNDMMNM; not part of format
PROFILO NACA 0012
11391165 947• the format of each following line is up to 10 fields of 7 chars each; records longer than 10 fields arebroken on multiple lines, with the first field filled with blanks;• a block containing the Cl data, made of:– a record with the first field blank, followed by the ML Mach values for the Cl ;– NL records containing the angle of attack in the first field, followed by ML values of Cl for each
Mach number; angles of attack wrap around 360 deg, starting from -180 deg.
The example provided in file var/naca0012.c81 contains 11 Mach points and 39 angle of attack
records for the Cl of the NACA0012 airfoil at high (unspecified) Reynolds:......7......7......7......7......7......7......7......7......7......7; not part of format
0.
.20
.30
.40
.50
.60
.70
.75
.80
.90
1.
-180. 0.
0.
0.
0.
0.
0.
0.
0.
0.
0.
0.
-172.5 .78
.78
.78
.78
.78
.78
.78
.78
.78
.78
.78
...

• a block containing the Cd data, same as for Cl , with MD Mach points and ND angle of attack records;• a block containing the Cm data, same as for Cl , with MM Mach points and NM angle of attack records.

35

Free Format
Finally, to allow higher precision whenever available, a native format, based on c81, called free format,
is available. It basically consists in the c81 format without continuation lines and with arbitrary precision,
with fields separated by blanks. The header is made of an arbitrary string, terminated by a semicolon‘;’, followed by the six numbers that define the dimensionality of the expected data.
Example.
# FREE FORMAT
this is the header; 2 8 2 2 2 2
0.0
0.9-180.0 0.0
0.0-170.0 1.0
0.9-90.0 0.0
0.0
-10.0 -1.0 -0.9
10.0 1.0
0.9
90.0 0.0
0.0
170.0 -1.0 -0.9
180.0 0.0
0.0
0.0
0.9
-180.0 0.1
0.1
180.0 0.1
0.1
0.0
0.9
-180.0 0.0
0.0
180.0 0.0
0.0
NREL
The nrel format is used to provide airfoil data for wind turbines. The format is very compact, but does
not allow to account for Mach dependence, and requires the same angle of attack resolution for all threecoefficients. See AeroDyn’s User Guide [1] for a description of the format. Please note that MBDyn only
supports one airfoil per file, and only considers static coefficients from line 15 on.
To be completed.
Alternative Format
An alternative format, required by some projects, can be used by supplying the optional switch fc511;
it is intentionally not documented.
Format Conversion
Traditional format files can be automatically converted in free format using the c81test(1) utility:$ c81test -d var/naca0012_free_format.c81 var/naca0012.c81
generates a free format version of the NACA 0012 airfoil data provided in the distribution.
Miscellaneous
A simple program that allows to read and plot the C81 tables is available at
http://homepage.mac.com/jhuwaldt/java/Applications/TableReader/TableReader.html(thanks to Marco Fossati for pointing it out).
36

A simple utility that parses the C81 file and computes the aerodynamic coefficients for a given pairof angle of attack and Mach number is c81test(1), available in the MBDyn utils suite. This routine
uses exactly the same code internally used by MBDyn, so it should be considered a check of the code
rather than a real tool.

2.4.3

Drive Caller

The drive caller directive<card> ::= drive caller : <label> ,[ name , " <name> " , ](DriveCaller) <drive_caller> ;allows to define a drive caller (see Section 2.6) that can be subsequently reused. It is useful essentiallyin two cases:a) to define a drive that will be used many times throughout a model;b) to define a drive that needs to be used in a later defined part of a model, in order to make itparametric.

2.4.4

Hydraulic fluid

The hydraulic fluid directive:<card> ::= hydraulic fluid : <label> ,<fluid_type> , <fluid_properties> ;allows to define a hydraulic fluid to be later used in hydraulic elements, see Section 8.11. The fluid is
identified by the label. The fluid_types, with the related fluid_properties, are described in 2.11

2.4.5

IncludeThe include directive<card> ::= include : " <file_name> " ;allows to include the contents of the file file_name, which must be a valid filename for the operating
system in use. The file name must be enclosed in double quotes ("). The full (absolute or relative) pathmust be given if the included file is not in the directory of the including one.
There is no check for recursive include directives, so the user must take care of recursion.
The include directive forces the parser to scan the included file file_name before continuing with
the including one. This is very useful if, for instance, a big model can be made of many small models
that are meaningful by themselves.
It can be used to replicate parts of the model, by simply using parametric labels for nodes, elements,
reference systems, and setting a bias value before multiple-including the same bulk data file. Examples ofthis usage are given in the tutorials (http://www.aero.polimi.it/mbdyn/documentation/tutorials/).

37

2.4.6Module Load

The module load directive:<card> ::= module load : " <file_name> "[ , <module_arglist> ] ;<module_arglist> ::= <arg> [ , ... ]where file_name is the name of a runtime loadable object, causes the object to be opened, and a function
module_init(), with prototype
extern "C" intmodule_init(const char *module_name,void *data_manager, void *mbdyn_parser);to be executed.
The function is assumed to perform the operations required to initialize the module, eventually taking
advantage of the parsing and of the data manager; see the technical manual for details.
The function is also expected to take care of the optional module_arglist arguments; in detail,module developers are encouraged to support help as the first optional argument. The presence of thisargument should result in printing to standard output as much information as possible about the use of
the module.
The typical use consists in registering some methods for later use. A clear example is given inmodules/module-wheel2/module-wheel2.cc
where the module_init() function registers the user defined element called wheel2 in the set of userdefined element handlers. The module can be retrieved later using the syntax described in Section 8.15.
Note, however, that the module_init() function may be used for any purpose. A typical use consists inregistering any kind of handlers for subsequent use.
Run-time module loading is taken care of by GNU’s libltdl. Modules are compiled using libtool
for portability purposes. The resulting modules take the name libmodule-<name>.la.
Modules are installed by default in the directory ${prefix}/libexec. When loaded using only themodule name, the default directory is searched. The run-time loading path can be modified by theloadable path statement described in Section 5.2.16.
Although libltdl is supposed to be portable on a wide variety of platforms (this is what it is designed
for, all in all), run-time loading within MBDyn is mainly tested using Linux. Users are encouraged toreport problems they might encounter, especially when building modules for different platforms, as thiswould help making MBDyn more portable.

2.4.7

Print symbol table

The print symbol table directive:<card> ::= print symbol table [ :all | <namespace_list> ] ;<namespace_list> ::= <namespace> [ , <namespace_list> ]allows to print to standard output the contents of the parser’s symbol table at any stage of the input
phase. This may be useful for model debugging purposes.
When no arguments are provided, it prints the symbol table of the math parser. Otherwise, it prints
the symbol table associated with a specific namespace, according to the list of arguments (all namespaces
when the keyword all is used).
38

2.4.8Reference

The reference directive:<card> ::= reference : <unique_label> ,[ name , (string) <name> , ](Vec3) <absolute_position> ,(OrientationMatrix) <absolute_orientation_matrix> ,(Vec3) <absolute_velocity> ,(Vec3) <absolute_angular_velocity> ;A reference system is declared and defined. It must be given a unique identifier, scanned by the mathparser (which means that any regular expression is allowed, and the result is rounded up to the nearest
unsigned integer). The entries absolute_* are parsed by routines that compute absolute (i.e. referringto the global frame) entities starting from a given entity in a given reference frame. These routines arevery general, and make intense use of the reference entries themselves, which means that a reference
can be recursively defined by means of previously defined reference entries.
Alternative form, based on Denavit-Hartenberg parameters, which are particularly used in robotics.
It defines the reference system of the second part of a joint with respect to the first part, when the twoparts are connected by revolute joints.
<card> ::= reference : <unique_label> ,[ name , " <name> " , ]Denavit Hartenberg ,[ reference , { global | <ref_label> } , ]<d> , <theta> , <a> , <alpha> ;where:• d: offset d along previous z axis to the common normal (the current x axis);• theta: the angle θ about previous z from previous to current x axis;• a: length a of the common normal; for revolute joints, the radius of the previous z;• alpha: the angle α about the common normal, from previous to new z axis.
The configuration of the first part of the joint is identified by an axis z1 and a point P1 on it. The
configuration of the second part of the joint is identified by an axis z2 ; point P2 on the second part of thejoint results from the definition itself, and is not strictly relevant for the definition. If the two axes are
not parallel, they have a common normal, x2 , that crosses both; otherwise, one can arbitrarily choose x2
as a direction orthogonal to both z1 (and z2 , since they are parallel, or even coincident). Choose x1 asa vector normal to z1 , originating from the reference point of the first part of the joint, P1 , and directed
towards the reference point of the second part of the joint, P2 (this is not strictly required, as one canchoose axis x1 at will, as it only provides the reference for the joint rotation). In general, x1 will not beable to intersect axis z2 , unless axes z1 and z2 are co-planar. Point P2 is the intersection between axes
x2 and z2 . If needed, axes y1 and y2 are defined according to the right-hand rule. Then:• d is the distance, along z1 , between the reference point of the first part, P1 , and the plane determinedby axes z2 and x2 ;• theta is the angle about axis z1 between axes x2 and x1 ; it represents the actual rotation of thejoint;
39• a is the distance between axes z1 and z2 , which is along axis x2 ;• alpha is the angle formed by axis z2 with respect to axis z1 ; it corresponds to a rotation aboutaxis x2 .
The new reference data arexnew = xold + Rold (d e3 + exp ((theta e3 ) × ) · (a e1 ))Rnew = Rold exp ((theta e3 ) × ) exp ((alpha e1 ) × )vnew = vold + ωold × Rold (d e3 + exp ((theta e3 ) × ) · (a e1 ))ωnew = ωold

(2.6a)(2.6b)(2.6c)(2.6d)

where the subscript “old” refers to the reference frame with label ref_label1, if any, or otherwise to theglobal reference system.
Use of Reference Frames
Every time an absolute or a relative geometric or physical entity is required, it is processed by a set ofroutines that allow the entity to be expressed in the desired reference frame. The following cases are
considered:• relative position (physical)• absolute position (physical)• relative orientation matrix (physical)• absolute orientation matrix (physical)• relative velocity (physical)• absolute velocity (physical)• relative angular velocity (physical)• absolute angular velocity (physical)• relative arbitrary vector (geometric)• absolute arbitrary vector (geometric)
The caller is responsible for the final interpretation of the input. The caller always supplies the routines
a default reference structure the input must be referred to. So, depending on the caller, the entry canbe in the following forms:
1. <entity>:
the data supplied in entity is intended in the default reference frame
2. reference , <reference_type> , <entity>:
the data are in reference_type reference frame, where<reference_type> ::= { global | node | local }3. reference , <reference_label> , <entity>:
the data are in reference_label reference frame. This reference frame must be already defined.

40

In some cases, significantly in case of joints (see Section 8.12) that connect two nodes a and b, specialreference types are allowed when reading specific entities related to the second node. These reference
types compute the value of the entity with respect to the reference frame associated to the first node, a:
1. other position:a relative position p̃ is intended in the other node’s reference frame, with respect to the relative
position f˜a already specified for the other node,




(2.7)
f˜b = RTb xa + Ra f˜a + p̃ − xb ,which is the solution of equation
xa + Ra f˜a + p̃ = xb + Rb f˜b ;(2.8)

2. other orientation:a relative orientation R̃ is intended in the other node’s reference frame, with respect to the relativeorientation R̃ha already specified for the other node,R̃hb = RTb Ra R̃ha R̃,(2.9)

Ra R̃ha R̃ = Rb R̃hb ;(2.10)

which is the solution of equation
3. other node:a relative position p̃ or a relative orientation R̃ are intended in the other node’s reference frame,f˜b = RTb (xa + Ra p̃ − xb )R̃hb = RTb Ra R̃,(2.11a)(2.11b)which are the solutions of equations
xa + Ra p̃ = xb + Rb f˜b(2.12a)Ra R̃ = Rb R̃hb .

(2.12b)Example.
• absolute position:null
reference, global, nullreference, 8, 1., sin(.3*pi), log(3.)• relative orientation matrix (e.g. as required by many constraints and thus referred to a node):eyereference, node, eyereference, 8,3, 0., 1., 0.,1, .5, sqrt(3)/2., 0.

41

Notes:• the global reference frame has position {0, 0, 0}, orientation matrix eye, velocity {0, 0, 0} andangular velocity {0, 0, 0}.
• if the caller is not related to a node, the reference type node is not defined.
• when processing a velocity or an angular velocity, the resulting value always accounts for thevelocity and angular velocity of the frame the entry is referred to.
As an example, if a node is defined in a reference frame RR that has non-null angular velocity ΩR ,and the position xinput of the node is not coincident with the origin XR of the reference frame it
is attached to, its global velocity and angular velocity result as the composition of the input values
and of those of the reference frame:
w
v

=
=

RR ωinput + ΩR
RR vinput + VR + ΩR × (RR xinput )This, for instance, eases the input of all the parts of a complex system that is moving as a rigid
body, by defining a reference frame with the proper initial linear and angular velocity, and thenreferring all the entities, e.g. the nodes, to that frame, with null local linear and angular velocity.
Recalling the declaration and the definition of reference frames, a simple reference frame definition, withall the entries referring by default to the global system, would be:reference: 1000,
null,
eye,
null,
null;
which represents a redefinition of the global system.
A more verbose, and self-explanatory definition would be:reference: 1000,
reference, global, null,reference, global, eye,reference, global, null,reference, global, null;
The reference frame one is referring to must be repeated for all the entries since they must be allowed torefer to whatever frame is preferred by the user.
A fancier definition would be:reference: Rotating_structure,reference, Fixed_structure, null,reference, Spindle_1,
1, 0., 0., 1.,3, 0., 1., 0.,reference, Fixed_structure, null,reference, Spindle_1, 0., 0., Omega_1;

42Output
The reference frames are used only during the input phase, where they help referring entities either
absolute or relative to other entities depending on their internal representation during the analysis. As
such, reference frames cannot be “used” or “visualized” neither directly nor indirectly at any time during
the analysis or by interpreting the output, because they do not “evolve” nor are attached to any statedependent entity. To allow their debugging, however, they can be output in the global reference frame
according to the representation of structural nodes, as described in Section 6.1.5, by using the default
output directive with the value reference frames, as detailed in Section 5.2.5.

2.4.9

Remark

The remark directive:<card> ::= remark [ : <math_expression> [ , ... ] ] ;This directive simply prints to stdout the (list of) expression(s) math_expression. It is used to allow
rough input debugging. The file name and line number are logged first, followed by the result of theevaluation of the expression(s list).
Example.

A file “remarks”, containing only the statements

remark: "square root of 2", sqrt(2);set: (
real EA = 1e6; # N, axial stiffness
real GA = 1e6; # N, shear stiffness
real EJ = 1e3; # Nm^2, bending stiffness
real GJ = 1e3; # Nm^2, torsional stiffness0);
remark: "Stiffness properties", EA, GA, EJ, GJ;
results in
user@host:~>$ mbdyn -f remarks
MBDyn - Multi-Body Dynamics 1.6.2
configured on Jun 26 2015 at 10:17:02
Copyright 1996-2017 (C) Paolo Mantegazza and Pierangelo Masarati,
Dipartimento di Ingegneria Aerospaziale <http://www.aero.polimi.it/>
Politecnico di Milano<http://www.polimi.it/>
MBDyn is free software, covered by the GNU General Public License,and you are welcome to change it and/or distribute copies of it
under certain conditions. Use ’mbdyn --license’ to see the conditions.
There is absolutely no warranty for MBDyn. Use "mbdyn --warranty"
for details.
reading from file "remarks"line 1, file <remarks>: square root of 2, 1.41421
line 8, file <remarks>: Stiffness properties, 1e+06, 1e+06, 1000, 1000
MBDyn terminated normallyuser@host:~>$43

Notice that in the example above the first expression is actually a string, as it was required up to version
1.6.1; this is no longer required.

2.4.10Set

The set directive:<card> ::= set : <math_expression> ;This directive simply invokes the math parser to evaluate the expression math_expression and thendiscards the result.
It can be used to declare new variables, or to set the values of existing ones. This feature is very
useful, since it allows to build parametric models, and to reuse generic model components.
Example.
set: integer LABEL = 1000;
set: real E = 210e+9;
set: real A = 1e-4;
set: real K = E*A;

2.4.11# a label# Pa, steel’s elastic module# m^2, a beam’s cross section# N, a beam’s axial stiffness

Setenv

The setenv directive:<card> ::= setenv :[ overwrite , { yes | no | (bool) <overwrite> } , ]" <varname> [ = <value> ] " ;This directive sets the environment variable varname to value, if given; otherwise, the variable is unset.
If overwrite is set, the variable is overwritten, if already set. By default, overwrite is set according tosetenv(3)’s overwrite parameter (no).
# set FILE to "test", if it does not exist
setenv: "FILE=test";# set FILE to "test", even if it exists
setenv: overwrite, yes, "FILE=test";# unset FILE
setenv: "FILE";# set FILE to the empty string, if it does not exist
setenv: "FILE=";See setenv(3) and unsetenv(3) (or putenv(3), if the former is not available) man pages for details.

2.4.12

Template Drive Caller

The template drive caller directive<card> ::= template drive caller : <label> , { " <dim_name> " | (integer) <dim> } ,(TplDriveCaller<<Entity>>) <tpl_drive_caller> ;<dim_name> ::= { 1 | 3 | 6 | 3x3 | 6x6 }<dim> ::= { 1 | 3 | 6 }44

allows to define a template drive caller (see Section 2.6.39) that can be subsequently reused. The
type is defined according to
Entity
real
Vec3
Vec6
Mat3x3Mat6x6

dim_name
1
3
6
3x3
6x6

dim
1
3
6

Template drive callers are useful essentially in two cases:a) to define a template drive that will be used many times throughout a model;b) to define a template drive that needs to be used in part of a model that is defined later, in orderto make it parametric.

2.5

Node Degrees of Freedom

A node in MBDyn is an entity that owns public degrees of freedom and instantiates the corresponding
public equations. It can lend them to other entities, called elements, to let them write contributions topublic equations, possibly depending on the value of the public degrees of freedom.
Usually elements access nodal degrees of freedom through well-defined interfaces, at a high level. But
in a few cases, nodal degrees of freedom must be accessed at a very low level, with the bare knowledge ofthe node label, the node type, the internal number of the degree of freedom, and the order of that degreeof freedom (algebraic or differential, if any). The data that allows an entity to track a nodal degree of
freedom is called NodeDof; it is read according to<node_dof> :: = <node_label> ,<node_type>[ , <dof_number> ][ , { algebraic | differential } ]The label node_label and the type node_type of the node are used to track the pointer to the desirednode.
If node_type refers to a non-scalar node type, the dof_number field is required to indicate therequested degree of freedom.
Finally, the order of the degree of freedom is read, if required. It must be one of algebraic or
differential. If the dof_number degree of freedom is differential, both orders can be addressed, while
in case of a node referring to an algebraic degree of freedom there is no choice, only the algebraic ordercan be addressed and thus this field is not required.
The dof_number must be between 1 and the number of degrees of freedom related to the node. Not
all numbers might be valid for specific nodes; for example, dof_number values 4, 5, and 6 are not valid
for a structural node, Section 6.1 when the order is algebraic.
When the node degree of freedom input syntax is used to address an equation (as in abstract
force elements, Section 8.8.2, or in discrete control elements, Section 8.7.4), the distinction between
algebraic and differential is meaningless, and thus this field is not required.

2.6

Drives and Drive Callers

Implements the type DriveCaller. Every time some entity can be “driven”, i.e. a value can be expressed
as dependent on some “external” input, an object of the class DriveCaller is used. The drive essentially45

represents a scalar function, whose value can change over time or, through some more sophisticatedmeans, can depend on the state of the analysis. Usually, the dependence over time is implicitly assumed,
unless otherwise specified. For example, the amplitude of the force applied by a force element (seeSection 8.8) is defined by means of a drive; as such, the value of the drive is implicitly calculated as afunction of the time. However, a dof drive (see Section 2.6.7) uses a subordinate drive to compute its
value based on the value of a degree of freedom of the analysis; as a consequence, the value of the dof
drive is represented by the value of the subordinate drive when evaluated as a function of that specificdegree of freedom at the desired time (function of function).
The family of the DriveCaller object is very large. The type of the DriveCaller is declared as<drive_caller> ::={ <drive_caller_type> [ , <arglist> ]| reference , <label> }where arglist, if any, is a comma-separated list of arguments that depends on drive_caller_type. As
an exception, a constant DriveCaller (that behaves exactly as a numerical constant with little or nooverhead depending on the optimizing capability of the compiler) is assumed when a numeric value isused instead of a keyword.
If the alternative format is used, the keyword reference must be followed by the label of an alreadydefined, valid drive caller (See Section 2.4.3).
Drive callers are listed in Table 2.6.

2.6.1

Array drive<drive_caller> ::= array ,<num_drives> ,(DriveCaller) <drive_caller>[ , ... ]this is simply a front-end for the linear combination of num_drives normal drives; num_drives must be
at least 1, in which case a simple drive caller is created, otherwise an array of drive callers is created andat every call their value is added to give the final value of the array drive.

2.6.2

Closest next drive<drive_caller> ::= closest next ,<initial_time> ,{ forever | <final_time> } ,(DriveCaller) <increment>This drive returns a non-zero value when called for the first time with an argument greater that or equal
to the current threshold value, which is computed starting from initial_time and incrementing it eachtime by as many increment values as required to pass the current value of Time. As soon as a thresholdvalue is exceeded, as many values of increment as required to pass the current value of Time are added,
and the process repeats.
This drive caller is useful within the output meter statement (see Section 5.2.7) to obtain nearly
equally spaced output when integrating with variable time step.

2.6.3

Const(ant) drive<drive_caller> ::= [ const , ] <const_coef>
46

Name
array
closest next
const
cosinecubic
directdof
double ramp
double step
drive
element
exponential
ginac
file
fourier series
frequency sweep
linear
meter
mult
node
null
parabolicperiodicpiecewise linear
ramp
randomsample and holdscalar function
sine
step
stringtanh
time
timestep
unit

Table 2.6: Drive callers
Differentiable Notes√
depends on subordinate drive callers√
depends on subordinate drive caller
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√

depends on subordinate drive caller

depends on subordinate drive callers
depends on subordinate drive caller
symbolic differentiation using GiNaC

depends on subordinate drive callers

depends on subordinate drive callers
depends on subordinate drive caller

depends on subordinate drive caller

depends on underlying scalar function

47

The keyword const can be omitted, thus highlighting the real nature of this driver, that is completely
equivalent to a constant, static real value.

2.6.4

Cosine drive<drive_caller> ::= cosine ,<initial_time> ,<angular_velocity> ,<amplitude> ,{ [ - ] <number_of_cycles> | half | one | forever } ,<initial_value>
where angular_velocity is 2π/T . This drive actually computes a function of the typef (t) = initial_value + amplitude · (1 − cos (angular_velocity · (t − initial_time))) .

(2.13)The value of number_of_cycles determines the behavior of the drive. If it is positive, number_of_cycles
oscillations are performed. If it is negative, the oscillations end after number_of_cycles−1/2 cycles at
the top of the cosine, with null tangent. Special keywords can be used for number_of_cycles:• forever: the oscillation never stops;• one: exactly one cycle is performed (equivalent to number_of_cycles = 1);• half: exactly half cycle is performed (equivalent to number_of_cycles = -1), so the function stops
atf = initial_value0when t ≤ initial_time








 amplitude · (1 − cos(angular_velocity · (t − initial_time)))π+when initial_time < t < initial_time +angular_velocity



π


 2 · amplitude when initial_time +≤tangular_velocity(2.14)

starting and ending with continuous first derivative. In this case, it may be convenient to indicate
the angular_velocity as π/duration, where duration is the time required to complete the halfwave.
Note that this drive caller does not correspond to cos(t).
Example.
# starts at 1.5, duration = T, amplitude = A, a "bump" of height 2*A..., cosine, 1.5, 2*pi/T, A, one, 0., ...
# starts at .5, duration = T, amplitude = A, half "bump", remains at 2*A..., cosine, .5, pi/T, A, half, 0., ...
# starts at 1.2, frequency = Omega, amplitude = A, lasts forever..., cosine, 1.2, Omega, A, forever, 0., ...
TODO: add a plot that exemplifies the three cases.
48

2.6.5

Cubic drive<drive_caller> ::= cubic ,<const_coef> ,<linear_coef> ,<parabolic_coef> ,<cubic_coef>
The function
f (t) = const_coef+ linear_coef · t+ parabolic_coef · t2
+ cubic_coef · t3 .

2.6.6

(2.15)

Direct drive<drive_caller> ::= direct
Transparently returns the input value; the arglist is empty. It is useful in conjunction with those drive
callers that require their output to be fed into another drive caller, like the dof, node and element drive
callers, when the output needs to be used as is.

2.6.7

Dof drive<drive_caller> ::= dof ,(NodeDof) <driving_dof> ,(DriveCaller) <func_drive>a NodeDof, namely the reference to a degree of freedom of a node, is read. Then a recursive call to adrive data is read. The driver returns the value of the func_drive drive using the value of the NodeDofas input instead of the time. This can be used as a sort of explicit feedback, to implement fancy springs(where a force is driven through a function by the displacement of the node it is applied to) or an active
control system; e.g.:..., dof, 1000, structural, 3, algebraic,
linear, 0., 1. ...
uses the value of the third component (z) of structural node 1000 as is (that is, in a linear expression
with null constant coefficient and unit linear coefficient, while..., dof, 1000, abstract, differential,
string, "2.*exp(-100.*Var)" ...
uses the value of the derivative of abstract node 1000 in computing a string expression. Refer to thedescription of a NodeDof entry for further details.
The same effect can be obtained using the dof plugin as follows:
set: [dof,x,1000,structural,1,algebraic];# ...
..., string, "2.*exp(-100.*x)" ...
which applies a couple whose amplitude is computed by evaluating a string drive which depends onvariable x; this, in turn, is defined as a dof plugin, which causes its evaluation in terms of the selected
degree of freedom of the node at each invocation.
49

2.6.8

Double ramp drive<drive_caller> ::= double ramp ,<a_slope> ,<a_initial_time> ,<a_final_time> ,<d_slope> ,<d_initial_time> ,{ forever | <d_final_time> } ,<initial_value>
The function<f_a> ::= a_slope · (a_final_time − a_initial_time)

2.6.9<f_d> ::= d_slope · (d_final_time − d_initial_time)
f (t) = initial_value0t < a_initial_time








a_slope · (t − a_initial_time)
a_initial_time ≤ t ≤ a_final_value





f_a
a_final_time < t < d_initial_time
+






f_a + d_slope · (t − d_initial_time)
d_initial_time ≤ t ≤ d_final_value







f_a + f_d d_final_time < t(2.16)

Double step drive<drive_caller> ::= double step ,<initial_time> ,<final_time> ,<step_value> ,<initial_value>
The function

2.6.10f (t) = initial_value0t < initial_time





step_value initial_time ≤ t ≤ final_value
+





0
final_time < tDrive drive<drive_caller> ::= drive ,(DriveCaller) <drive_caller1> ,(DriveCaller) <drive_caller2>50(2.17)

This is simply a “function of function” drive: the output of drive_caller2 is fed to drive_caller1 andthe result is returned. So the value of drive_caller2 becomes the input argument to drive_caller1.
Note that the very same thing occurs, for instance, in the dof, node and element drives, where the valueof the dof or of the element’s private datum, respectively, are fed into the given drive.
Example.
force: 1, abstract,1, abstract,drive,
string, "Var*(Var>0.)",sine, 0., 2*pi/.2, 10., forever, 0.;is equivalent to
set: real v;
force: 1, abstract,1, abstract,
string, "v=sin(5.*2*pi*Time); 10.*v*(v>0)";2.6.11Element drive<drive_caller> ::= element ,<label> ,<type> ,[ { string , " <name> " | index , <index> } , ] # index is deprecated(DriveCaller) <func_drive>a reference to the private data of an element is read. This is made of: the element’s label, the element’s
type and a specification of which private data are being referred; the index can be directly given,
prepended by the keyword index, or the symbolic name name can be used, prepended by the keyword
string. If that element allows only one private data, the specification can be omitted. Then a recursive
call to a drive data is read. The driver returns the value of the func_drive drive using the value ofthe element’s private data as input instead of the time. This can be used as a sort of explicit feedback,to implement fancy springs (where a force is driven through a function by the rotation of a joint) or an
active control system; e.g.:element, 1000, joint, string, "rz", direct
uses the value of the rotation about axis z of a revolute hinge as is (that is, in a linear expression withnull constant coefficient and unit linear coefficient, while
element, 1000, joint, index, 1
string, "2.*exp(-100.*Var)"
uses the same value, addressed in an alternative manner, in computing a string expression.
The same effect can be obtained using the element plugin as follows:
set: [element,x,1000,joint,string=rz];# ...
couple: 1, conservative, 1, 0.,0.,1.,
string, "2.*exp(-100.*x)";which applies a couple whose amplitude is computed by evaluating a string drive which depends onthe variable x; this, in turn, is defined as an element plugin, which causes its evaluation in terms of theelement’s private data at each invocation.
51

2.6.12

Exponential drive<drive_caller> ::= exponential ,<amplitude_value> ,<time_constant_value> ,<initial_time> ,<initial_value>
This drive yields a function that resembles the response of a first-order system to a step input. Itsvalue corresponds to initial_value for t < initial_time. For t ≥ initial_time, it grows to
initial_value+amplitude_value exponentially. The growth rate is governed by time_constant_value.
If time_constant_value < 0, the function diverges.

t − initial_time −
time_constant_value 
(2.18)
f (t) = initial_value + amplitude_value · 1 − eExample.
..., exponential, 10.0, 0.2, 5.0, 0.0, ...
yields a function identical to the response of the system
H(s) =

1
1 + 0.2s(2.19)

to a step input occurring at time t = 5.0 with amplitude A = 10.0.

2.6.13File drive

The DriveCaller is attached to a file drive object that must be declared and defined in the drivers
section of the input file (see Section 7). As a consequence, file drive callers can only be instantiatedafter the drivers section of the input file.
<drive_caller> ::= file ,<drive_label>[ , { <column_number> | <user_defined> } ][ , amplitude , <amplitude> ]<user_defined> ::= <user_defined_type> [ , ...]
drive_label is the label of the drive the DriveCaller is attached to, while column_number is thenumber of the column the DriveCaller refers to (defaults to 1). An additional scaling factor amplitude
can be used to rescale the drive value (defaults to 1.0).

2.6.14

Fourier series drive<drive_caller> ::= fourier series ,<initial_time> ,<angular_velocity> ,<number_of_terms> ,52

<a_0> ,<a_1> , <b_1> ,[ ... , ]{ <number_of_cycles> | one | forever } ,<initial_value>
This drive corresponds to a Fourier series of fundamental angular velocity ω, truncated after n terms,
over a given number of cycles P and starting at a given initial time t0 asnf (t) =

a_0 X+
(ak cos (kω (t − t0 )) + bk sin (kω (t − t0 )))
2
k=1

for

2π
ω
The value of f (t), if defined, is added to initial_value. The value of number_of_cycles determines the
behavior of the drive. If it is positive, number_of_cycles oscillations are performed. Special keywords
can be used for number_of_cycles:t0 ≤ t ≤ t0 + P• forever: the oscillation never stops;• one: exactly one cycle is performed;
the number_of_terms must be at least 1.

2.6.15Frequency sweep drive<drive_caller> ::= frequency sweep ,<initial_time> ,(DriveCaller) <angular_velocity_drive> ,(DriveCaller) <amplitude_drive> ,<initial_value> ,{ forever | <final_time> } ,<final_value>
this drive recursively calls two other drives that supply the angular velocity and the amplitude of theoscillation. Any drive can be used.
ω(t) = angular_velocity_drive
A(t) = amplitude_drive
ti = initial_time
tf = final_time (forever: + ∞)fi = initial_value
ff = final_valuet < ti fi
fi + A(t) sin (ω(t) (t − ti )) ti ≤ t ≤ tf
f (t) =
ff
tf < t53(2.20)

2.6.16

GiNaC<drive_caller> ::= ginac ,[ symbol , " <symbol> " , ]" <expression> "The function expression is evaluated and differentiated, if needed, as a function of the variable passed
as the optional symbol. If none is passed, Var is used. Currently there is no way to share the variablesof the math parser used by the string drive caller. Not to be confused with the string drive caller.
Example.
..., ginac, "10*log(1 + Var)" ...
..., ginac, symbol, "x", "10*log(1 + x)" ...

2.6.17

Linear drive<drive_caller> ::= linear ,<const_coef> ,<slope_coef>
The function
f (t) = const_coef+ slope_coef · t

2.6.18(2.21)

Meter drive

The meter drive has value zero except for every steps steps, where it assumes unit value.
<drive_caller> ::= meter ,<initial_time> ,{ forever | <final_time> }[ , steps , <steps_between_spikes> ]the first optional entry, preceded by the keyword steps, sets the number of steps between spikes.
Example.
..., meter, 0., forever, steps, 10, ...
defines a drive whose value is zero except at time step 0. and every 10 time steps from that, where it
assumes unit value.

2.6.19Mult drive

The mult drive multiplies the value of two subordinate drives.
<drive_caller> ::= mult ,(DriveCaller) <drive_1> ,(DriveCaller) <drive_2>54

2.6.20

Node drive<drive_caller> ::= node ,<label> ,<type> ,[ { string , " <name> " | index , <index> } , ] # index is deprecated(DriveCaller) <func_drive>a reference to the private data of a node is read. This is made of: the node’s label, the node’s type anda specification of which private data are being referred; the index can be directly given, prepended by
the keyword index, or the symbolic name name can be used, prepended by the keyword string. If that
node allows only one private data, the specification can be omitted. Then a recursive call to a drive data
is read. The driver returns the value of the func_drive drive using the value of the node’s private data
as input instead of the time. This can be used as a sort of explicit feedback, to implement fancy springs(where a force is driven through a function by the rotation of a joint) or an active control system; e.g.:..., node, 1000, structural, string, "X[3]",linear, 0., 1. ...
uses the value of the displacement in direction z (3) of a structural node, Section 6.1.5, as is (thatis, in a linear expression with null constant coefficient and unit linear coefficient, see the linear drive,
Section 2.6.17), while..., node, 1000, structural, index, 3,
string, "2.*exp(-100.*Var)" ...
uses the same value, addressed in an alternative manner, in computing a string expression.

2.6.21

Null drive<drive_caller> ::= null
Zero valued; the arglist is empty.

2.6.22

Parabolic drive<drive_caller> ::= parabolic ,<const_coef> ,<linear_coef> ,<parabolic_coef>
The function
f (t) = const_coef+ linear_coef · t+ parabolic_coef · t2

2.6.23

Periodic drive<drive_caller> ::= periodic ,<initial_time> ,<period> ,(DriveCaller)<func_drive>55(2.22)

The function
f (t) = 0t < initial_time
t − initial_time
f (t) = func_drive t − initial_time − period · floort ≥ initial_time
period(2.23)

2.6.24

Piecewise linear drive<drive_caller> ::= piecewise linear ,<num_points> ,<point> , <value>[ , ... ]Piecewise linear function; the first and the last point/value pairs are extrapolated in case a value beyond
the extremes is required. Linear interpolation between pairs is used.

2.6.25

Postponed drive<drive_caller> ::= postponed ,<label>This drive is actually a stub for a drive that cannot be defined because it occurs too early, when the data
manager is not yet available. A drive caller with label must be defined before the drive caller is firstused.
Example.
begin: initial value;# ...
method: ms, postponed, 99;# ...
end: initial value;# ...
begin: control data;# ...
end: control data;# ...
drive caller: 99, ...
A drive caller that depends on the data manager must be used to define the spectral radius of theintegration method. A reference to drive caller 99 is used. The drive caller labeled 99 is defined later,when all the required information is available.

2.6.26

Ramp drive<drive_caller> ::= ramp ,<slope> ,<initial_time> ,{ forever | <final_time> } ,<initial_value>
56

The function
f (t) = initial_value0t < initial_time





initial_time ≤ t ≤ final_value
slope · (t − initial_time)
+





slope · (final_time − initial_time) final_time < t

2.6.27(2.24)

Random drive<drive_caller> ::= random ,<amplitude_value> ,<mean_value> ,<initial_time> ,{ forever | <final_time> }[ , steps , <steps_to_hold_value> ][ , seed , { time | <seed_value> } ]Generates pseudo-random numbers using the rand(3) call of the C standard library. Numbers are
uniformly distributed in the interval [mean_value−amplitude_value, mean_value+amplitude_value).
The first optional entry, steps_to_hold_value, preceded by the keyword steps, sets the numberof steps a random value must be held before generating a new random number. The second optional
entry, preceded by the keyword seed, sets the new seed for the random number generator. A numeric
seed_value value can be used, otherwise the keyword time uses the current time from the internal
clock. A given seed can be used to ensure that two simulations use exactly the same random sequence(concurrent settings are not managed, so it is not very reliable).

2.6.28Sample and hold drive<drive_caller> ::= sample and hold ,(DriveCaller) <function> ,(DriveCaller) <trigger>[ , initial value , <initial_value> ]When trigger is non-zero, the value of function is recorded and returned; when trigger is zero, thelast recorded value is returned. When the optional keyword initial value is present, if the trigger is
initially zero, the value initial_value is returned until trigger becomes non-zero.

2.6.29Scalar function drive<drive_caller> ::= scalar function , " <scalar_function_name> "[ , <scalar_function_definition> ]The scalar function called scalar_function_name must exist; alternatively, it is defined inline according
to scalar_function_definition.
Example.

57

scalar function: "this_is_a_test",
multilinear,-20., 1.,
-10., 0.1,
0., 0.,
10., 0.1,
20., 1.;
set: integer MY_DRIVE = 1000;
drive caller: MY_DRIVE, scalar function, "this_is_a_test";
Alternative syntax example:
set: integer MY_DRIVE = 1000;
drive caller: MY_DRIVE, scalar function, "this_is_a_test",
multilinear,-20., 1.,
-10., 0.1,
0., 0.,
10., 0.1,
20., 1.;

2.6.30Sine drive<drive_caller> ::= sine ,<initial_time> ,<angular_velocity> ,<amplitude> ,{ [ - ] <number_of_cycles> | half | one | forever } ,<initial_value>
where angular_velocity is 2π/T . This drive actually computes
f (t) = initial_value + amplitude · sin (angular_velocity · (t − initial_time))(2.25)The value of number_of_cycles determines the behavior of the drive. If it is positive, number_of_cycles−
1/2 oscillations are performed. If it is negative, the oscillations end after number_of_cycles− 3/4 cycles
at the top of the sine, with null tangent. Special keywords can be used for number_of_cycles:• forever: the oscillation never stops;• one: exactly half period is performed (equivalent to number_of_cycles = 1);• half: exactly a quarter of period is performed (equivalent to number_of_cycles = -1), so thefunction stops at
f (t) = initial_value(2.26)
0
when t < initial_time








amplitude · sin (angular_velocity · (t − initial_time))



π
+
.
when initial_time ≤ t ≤ initial_time +
2 · angular_velocity







π


 amplitude when initial_time +≤t
2 · angular_velocity
58

Note that this drive caller does not correspond to sin(t).
Example.
# starts at 1.5, duration = T, amplitude = A, a "bump" of height A..., sine, 1.5, pi/T, A, one, 0., ...
# starts at .5, duration = T, amplitude = A, half "bump", remains at A..., sine, .5, pi/(2*T), A, half, 0., ...
# starts at 1.2, frequency = Omega, amplitude = A, lasts forever..., sine, 1.2, Omega, A, forever, 0., ...

2.6.31

Step drive<drive_caller> ::= step ,<initial_time> ,<step_value> ,<initial_value>
The function
f (t) = initial_value +2.6.32String drive


 0


t < initial_time(2.27)

step_value initial_time ≤ t<drive_caller> ::= string ," <expression_string> "expression_string is a string, delimited by double quotes. It is parsed by the math parser every timethe drive is invoked. The variable Time is kept up to date and can be used in the string to compute thereturn value, e.g.:..., string, "e^(-Time)*cos(2.*pi*Time)" ...
generates a cosine modulated by an exponential. Another variable, Var, is set to the value provided by
the caller in case the drive is called with an explicit argument as, for instance, in the dof drive (seeSection 2.6.7); e.g.:..., string, "e^(-Var)*cos(2.*pi*Time)" ...
Note: originally, the expression was parsed each time it is evaluated; this is not very efficient. Starting from release 1.7.0, a tree-like form of the parsed expression is built, where non-symbolic branches
are evaluated once for all, to speed up evaluation. That version can be compiled using the additional
compilation flags: ./configure CPPFLAGS="-DUSE_EE=1" CXX="g++ -std=c++11"
Note: all whitespace in the string is eaten up during input. For example..., string, "1 \+ cos(2 * pi * Time)", ...
is internally stored as..., string, "1+cos(2*pi*Time)", ...
59

2.6.33

Tanh drive<drive_caller> ::= tanh ,<initial_time> ,<amplitude> ,<slope> ,<initial_value>
This drive computes a function of the typef (t) = initial_value + amplitude · tanh (slope · (t − initial_time)) .
It is differentiable.

2.6.34

Time drive<drive_caller> ::= time
Yields the current time; the arglist is empty.

2.6.35

Timestep drive<drive_caller> ::= timestep
Yields the current timestep; the arglist is empty.

2.6.36

Unit drive<drive_caller> ::= unit
Always 1; the arglist is empty.

2.6.37

Deprecated drive callers• one; use unit instead.

2.6.38Hints

Hints have been sponsored by Hutchinson CdR.
In some cases, during the analysis, different entities can be reinitialized as a consequence of someevent, typically triggered by the waking up of a so-called driven element (See Section 8.17.2). The
DriveCaller is re-parsed when the entity that owns it is sent a hint of the form
"drive{ (DriveCaller) <drive_caller> }"is used, where drive_caller is an arbitrary DriveCaller specification. The whole hint argument needs
to be enclosed in double quotes because MBDyn treats it as a string. It is not parsed until needed. Atthat point, the string (after removing the enclosing double quotes) is fed into the parser.
Typically, the use of a hint is needed when the specification of the drive caller parameters depends
on the configuration of the system when the entity that uses it is waken up. For example, a distancejoint, an element that enforces the distance between two nodes, may be waken up by some event. In
the example reported below, the initial value of the cosine drive caller is computed by extracting thecurrent distance between the nodes at the time the element is waken up:
60

driven: 1, string, "Time > 10.",
hint, "drive{cosine, 10., 2., .25, half, model::distance_prev(10, 20)}",joint: 1, distance,
10,
20,
const, 1; # this length is not actually used,# since the element is inactive until "Time > 10.";# subsequently, the length is replaced by the hint
Note that the function distance_prev (from the built-in model namespace) is used instead of the function
distance. This is needed because hints are parsed after the prediction of the state of the model for asubsequent new time step, i.e. they extract information from the model after its current state has been
modified by the prediction for the next time step. As a consequence, unless an exactly steady state wasreached for a sufficient number of steps to result in a prediction that does not change the state of thatpart of model, unexpected values could result from a call to a function that returns information based on
the current state of the model. On the contrary, to access the last converged state of the model within ahint one needs to call model namespace functions that refer to the previous time step. See Section 2.2.1
for further details on the functions of the model namespace.

2.6.39

Template Drive

The template drive caller, indicated as TplDriveCaller<<Entity>>, is a higher-dimensional DriveCaller,
whose dimensions are those of <Entity>. The family of the TplDriveCaller<<Entity>> object is verylarge. A TplDriveCaller<<Entity>> is declared as<tpl_drive_caller> ::={ <tpl_drive_caller_type> [ , <arglist> ]| reference , <label> }where arglist, if any, is a comma-separated list of arguments that depends on tpl_drive_caller_type.
If the alternative format is used, the keyword reference must be followed by the label of an alreadydefined, valid template drive caller (See Section 2.4.12).
There are four types of template drive callers:• the null template drive caller:<tpl_drive_caller> ::= nulla shortcut for nothing;• the single template drive caller:<tpl_drive_caller> ::= single ,(<Entity>) <entity> , (DriveCaller) <drive_caller>
corresponding to entity · drive_caller, where entity is a constant of the expected type (scalar,
3 × 1 vector, 6 × 1 vector, 3 × 3 matrix, 6 matrix are the types currently defined, but since a C++
template has been used, the implementation of new ones is straightforward).
The keyword single can be omitted; however, this practice is not recommended, since in somecontexts the keyword is required to disambiguate the syntax.

61

In some contexts (e.g. when specifying the direction of a force), in which the entity is a Vec3, it
can be prefixed by an orientation modifier in the form of the specification of a reference frame inwhich entity is expressed; for example,
single, 1., 0., 0.
# in the default context-specific reference
single, reference, 99, 1., 0., 0.
# in reference frame 99
single, reference, global, 1., 0., 0. # in the global reference frame
Example. The following example implements a Vec3 template drive having a constant unitary
value in the X direction.
single,1., 0., 0.,const, 1.;
The following example implements a Mat3x3 template drive that is sine-valued along the diagonal.
single,eye,sine, 0., 2*pi, 1., forever, 0.;# identity matrix# sine drive caller• the component template drive caller:<tpl_drive_caller> ::= component , [ <type> , ]<component_drive_caller>[ , ... ]# as many component_drive_caller as the dimensionality of entity<type> ::= { sym | diag }<component_drive_caller> ::= { inactive | (DriveCaller) <drive_caller> }where each element consists of the corresponding drive caller; the optional type is used withmatrix-type entities to specify special matrix layouts:– sym indicates that only the upper triangular components are expected;– diag indicates that only the diagonal components are expected;
Example. The following example implements a Vec3 template drive having constant value in
the X direction, and a sine drive in the Z direction.
component,
const, 1.,
inactive,sine, 0., 2*pi, 1., forever, 0.;• the array template drive caller:62# X: 1# Y: 0# Z: sine<tpl_drive_caller> ::= array ,<num_template_drive_callers> ,<tpl_drive_caller>[ , ... ]# num_template_drive_callers instances of tpl_drive_caller
which linearly combines a set of arbitrary template drive callers.
In case of scalar values, a normal drive caller is actually instantiated, so no overhead is added.
In the case of the component template drive caller, as many instances of a DriveCaller as thedimensionality of the template drive caller are expected.
At least one tpl_drive_caller is expected in the case of the array template drive caller. If
num_template_drive_callers is exactly 1, only a single template drive caller is actually constructed,
thus avoiding the overhead related to handling the template drive caller array.
Hints
The template drive can be re-parsed as a consequence of a hint (see Section 2.6.38). In this case, thesyntax of the hint is:"drive<n>{ <tpl_drive_caller> }"where n is the dimension of entity.
For example, a TplDriveCaller<Vec3> drive hint is:"drive3{single, 1., 0., 0., sine, 0., 2*pi, 1., forever, 0.}"which corresponds to a 3 × 1 vector 1., 0., 0. that multiplies a sine drive caller with the parameters
illustrated above.
A TplDriveCaller<Mat3x3> drive hint is:"drive3x3{single, eye, sine, 0., 2*pi, 1., forever, 0.}"which corresponds to a 3 × 3 identity matrix (the keyword eye) that multiplies a sine drive caller withthe parameters illustrated above.

2.7

Scalar functions

A ScalarFunction object computes the value of a function. Almost every scalar function is of type
DifferentiableScalarFunction, derived from ScalarFunction, and allows to compute the derivativesof the function as well. Currently implemented scalar functions are• const: f (x) = c• exp: f (x) = m · bc·x
• log: f (x) = m · logb (c · x)
• pow: f (x) = xp
• linear: linear interpolation between the two points (x1 , y1 ) and (x2 , y2 )• cubicspline: cubic natural spline interpolation between the set of points {(xi , yi ), i ∈ [1, k ≥ 3]}• multilinear: multilinear interpolation between the set of points {(xi , yi ), i ∈ [1, k ≥ 2]}63• chebychev: Chebychev interpolation between the set of points {a, b}• sum: f (x) = f1 (x) + f2 (x)• sub: f (x) = f1 (x) − f2 (x)• mul: f (x) = f1 (x) · f2 (x)• div: f (x) = f1 (x)/f2 (x)Every ScalarFunction card follows the format<card> :: = scalar function : " <unique_scalar_func_name> " ,<scalar_func_type> ,<scalar_func_args>
The name of the scalar function is a string, thus it needs to be enclosed in double quotes.
The type of scalar function, scalar_func_type, together with relevant arguments, scalar_func_args,
are as follows:
Const Scalar Function<scalar_func_type> ::= const<scalar_func_args> ::= <const_coef>
Note: if the scalar_func_type is omitted, a const scalar function is assumed.
Example.
scalar function: "const_function", const, 1.e-2;
Exp Scalar Function<scalar_func_type> ::= exp<scalar_func_args> ::=[ base , <base> , ][ coefficient , <coef> , ]<multiplier_coef>f (x) = multiplier_coef · base(coef·x)
Note: the optional base must be positive (defaults to ‘e’, Neper’s number); coef defaults to 1.
Example.
scalar function: "exp_function", exp, 1.e-2; # 1.e-2*e^x64(2.28)

Log Scalar Function<scalar_func_type> ::= log<scalar_func_args> ::=[ base , <base> , ][ coefficient , <coef> , ]<multiplier_coef>f (x) = multiplier_coef · logbase (coef · x)

(2.29)

Note: the optional base (defaults to ‘e’, Neper’s number, resulting in natural logarithms) must be positive. The optional value coef, prepended by the keyword coefficient, (defaults to 1). The argument
must be positive, otherwise an exception is thrown.
Example.
scalar function: "log_function", log, 1.e-2; # 1.e-2*log(x)Pow Scalar Function<scalar_func_type> ::= pow<scalar_func_args> ::= <exponent_coef>f (x) = xexponent_coef(2.30)

Example.
scalar function: "pow_function", pow, 3.; # x^3.
Linear Scalar Function<scalar_func_type> ::= linear<scalar_func_args> ::= <point> , <point><point>::= <x>, <y>A line passing through the two points,
f (x) = yi +yf − yi(x − xi )xf − xi(2.31)

where xi , yi are the coordinates of the first point, while xf , yf are the coordinates of the second point.
Example.
scalar function: "linear_function", linear, 0., 0., 1., 1.;65

Cubic Natural Spline Scalar Function<scalar_func_type> ::= cubic spline<scalar_func_args> ::= [ do not extrapolate , ]<point> ,<point>[ , ... ][ , end ]<point>::= <x> , <y>The end delimiter is required if the card needs to continue (i.e. the ScalarFunction definition is embedded in a more complex statement); it can be omitted if the card ends with a semicolon right after thelast point.
Multilinear Scalar Function<scalar_func_type> ::= multilinear<scalar_func_args> ::= [ do not extrapolate , ]<point> ,<point>[ , ... ][ , end ]<point>::= <x> , <y>Unless do not extrapolate is set, when the input is outside the provided values of x the value isextrapolated using the slope of the nearest point pair.
Chebychev Scalar Function<scalar_func_type> ::= chebychev<scalar_func_args> ::=<lower_bound> , <upper_bound> ,[ do not extrapolate , ]<coef_0> [ , <coef_1> [ , ... ] ][ , end ]Chebychev polynomials of the first kind are defined aswithTn (ξ) = cos n cos−1 (ξ) ,
ξ=2

x
b+a
−
,
b−a b−a66(2.32)(2.33)

where a = lower_bound and b = upper_bound, which corresponds to the series
T0 (ξ) = 1(2.34)

T1 (ξ) = ξ...

(2.35)Tn (ξ) = 2ξTn−1 (ξ) − Tn−2 (ξ) .

(2.36)For example, the first five coefficients are
T0 (ξ) = 1(2.37)

T1 (ξ) = ξ(2.38)2

T2 (ξ) = 2ξ − 1(2.39)3

T3 (ξ) = 4ξ − 3ξ4

(2.40)2

T4 (ξ) = 8ξ − 8ξ + 1

This scalar function implements the truncated series in the formXf (x) =
ck Tk (ξ) ,(2.41)(2.42)

k=0,nwhere ck = coef_<k>. The first derivative of the series is obtained by consideringdT0 (ξ) = 0dξdT1 (ξ) = 1
dξ
...
d
d
d
Tn (ξ) = 2Tn−1 (ξ) + 2ξ Tn−1 (ξ) − Tn−2 (ξ) ,
dξ
dξ
dξ

(2.43)(2.44)(2.45)

so the first derivative of the scalar function isddξ Xdf (x) =
ck Tk (ξ) .
dx
dx
dξ

(2.46)

k=1,nSubsequent derivatives follow the rule
di
di−1
di
di
Tn (ξ) = 2i i−1 Tn−1 (ξ) + 2ξ i Tn−1 (ξ) − i Tn−2 (ξ) .
i
dξ
dξ
dξ
dξ

(2.47)

Differentiation of order higher than 1 is not currently implemented.
Sum Scalar Function<scalar_func_type> ::= sum<scalar_func_args> ::= (ScalarFunction) <f1> , (ScalarFunction) <f2>
f (x) = f1 (x) + f2 (x)67(2.48)Example.
scalar function: "first_function", const, 1.;
scalar function: "second_function", const, 2.;scalar function: "sum_function", sum, "first_function", "second_function";
Sub Scalar Function<scalar_func_type> ::= sub<scalar_func_args> ::= (ScalarFunction) <f1> , (ScalarFunction) <f2>
f (x) = f1 (x) − f2 (x)(2.49)

Example.
scalar function: "first_function", const, 1.;
scalar function: "second_function", const, 2.;scalar function: "sub_function", sub, "first_function", "second_function";
Mul Scalar Function<scalar_func_type> ::= mul<scalar_func_args> ::= (ScalarFunction) <f1> , (ScalarFunction) <f2>
f (x) = f1 (x) · f2 (x)(2.50)

Example.
scalar function: "first_function", const, 1.;
scalar function: "second_function", const, 2.;scalar function: "mul_function", mul, "first_function", "second_function";
Div Scalar Function<scalar_func_type> ::= div<scalar_func_args> ::= (ScalarFunction) <f1> , (ScalarFunction) <f2>
f (x) = f1 (x) /f2 (x)Note: division by zero is checked, and an exception is thrown.
Example.
scalar function: "first_function", const, 1.;
scalar function: "second_function", const, 2.;scalar function: "div_function", div, "first_function", "second_function";68(2.51)

2.8

Friction

A friction-based element needs the definition of at least a friction model and of a shape function.

2.8.1

Friction models

The friction model input format is:<friction_model> ::= <friction_type> ,<friction_arglist>
where friction_function gives the static friction as a function of sliding velocity.
Currently implemented friction models are:
1. modlugre
This friction model is based on the one presented in [2] by Pierre Dupont, Vincent Hayward, Brian
Armstrong and Friedhelm Altpeter, known as ‘LuGre’. The input format is:<friction_model> ::= modlugre<friction_arglist> ::=<sigma0> ,<sigma1> ,<sigma2> ,<kappa> ,(ScalarFunction) <friction_function>
2. discrete coulomb
This is a Coulomb model with viscous friction and internal states to resolve stick/slip conditions.
<friction_model> ::= discrete coulomb<friction_arglist> ::=(ScalarFunction) <friction_function>[ , sigma2 , <sigma2> ][ , velocity ratio , <vel_ratio> ]where sigma2 gives the viscous friction; vel_ratio defaults to 0.8, and is used to discriminate
stick/slip conditions. Note that discrete coulomb cannot handle stick conditions when the reaction force in the constraint goes to zero (resulting in a singular Jacobian matrix). The preload
parameter needs to be used to make sure the joint is preloaded as appropriate (see the documentation of the specific joint for details).

2.8.2

Shape functions

Implements the type Shape. The input format of shape functions is:<shape_function> ::= <shape_function_type>[ , <shape_function_arglist> ]Currently implemented shape functions for friction models are:
1. simple
This shape function is equal to one. It does not need arguments.
69

<shape_function_type> ::= simple<shape_function_arglist> ::=2. simple plane hinge<shape_function_type> ::= simple plane hinge<shape_function_arglist> ::= <radius>This is the shape function of a revolute hinge with radius equal to radius and subject to smallloads.

2.9

ShapesThe Shape entities are objects that return a value depending on one (or two, for 2D shapes) dimensionlessabscissa, ranging [−1, 1]. At present, only 1D shapes are used, by aerodynamic elements. A Shape input
format is:<shape_1D> ::= <shape_type> ,<shape_arglist>
The shapes currently available are:
1. const<shape_type> ::= const<shape_arglist> ::= <const_value>f = const_value(2.52)

2. piecewise const<shape_type> ::= piecewise const<shape_arglist> ::=<number_of_points> ,<abscissa> , <value>[ , ... ]ξ ≤ abscissa1

f (ξ) = value1
f (ξ) = valuei
f (ξ) = valueN

abscissai ≤ ξ < abscissai+1
abscissaN ≤ ξ

3. linear<shape_type> ::= linear<shape_arglist> ::=<value_at_-1> ,<value_at_1>
70(2.53a)(2.53b)(2.53c)f (ξ) =value_at_-1 + value_at_1 value_at_-1 − value_at_1+
ξ2
2(2.54)

4. piecewise linear<shape_type> ::= piecewise linear<shape_arglist> ::=<number_of_points> ,<abscissa> , <value>[ , ... ]f (ξ) = value1
abscissai+1 − ξ
f (ξ) = valuei
abscissai+1 − abscissai
ξ − abscissai+ valuei+1
abscissai+1 − abscissaif (ξ) = valueNξ ≤ abscissa1(2.55a)abscissai ≤ ξ < abscissai+1(2.55b)abscissaN ≤ ξ(2.55c)

5. parabolic<shape_type> ::= parabolic<shape_arglist> ::=<value_at_-1> ,<value_at_0> ,<value_at_1>
f (ξ) = value_at_-1 · ξ (ξ − 1) + value_at_0 · 1 − ξ 2 + value_at_1 · ξ (ξ + 1)

(2.56)

This form of input has been chosen since, being the shapes mainly used to interpolate values, it looks
more “natural” to insert the mapping values at characteristic points. For piecewise linear shapes,
there must be number_of_points pairs of abscissæ and values; abscissæ must be in the range [−1, 1], instrict ascending order.

2.10

Constitutive Laws

Implements the type ConstitutiveLaw<<Entity>, <DerivativeOfEntity>>. Every time a “deformable”
entity requires a constitutive law, a template constitutive law is read. This has been implemented bymeans of C++ templates in order to allow the definition of a general constitutive law when possible.
The “deformable” elements at present are:• rod and genel spring and related elements (1D);• deformable hinge and deformable displacement joint elements (3D);• deformable joint and beam elements (6D).

71Constitutive laws are also used in non-structural components, to allow some degree of generality indefining input/output relationships. Some constitutive laws are meaningful only when related to some
precise dimensionality. In some special cases, general purpose (genel) elements use 1D constitutive laws
to express an arbitrary dependence of some value on a scalar state of the system. Table 2.7 shows theavailability of each constitutive law.
The meaning of the input and output parameters of a constitutive law is dictated by the entity thatuses it. In general, the user should refer to the element the constitutive law is being instantiated for inorder to understand what the input and the output parameters are supposed to be.
Usually, constitutive laws can be directly defined when required, according to the definition of anelement. However, the special card described in Section 2.4.1 allows to define constitutive laws standalone, and attach them to the elements by means of the following mechanism:<constitutive_law> ::={ <constitutive_law_definition> | reference , <label> }where <constitutive_law_definition> is described in the following, while <label> is the label of apreviously defined constitutive law of the appropriate dimensionality, as described in Section 2.4.1.
The constitutive laws are entered as follows:<constitutive_law_definition> ::= <specific_const_law>[ , prestress , (Entity) <prestress> ][ , prestrain , (TplDriveCaller<<Entity>>) <prestrain> ]<specific_const_law> ::= <const_law_name> ,<const_law_data>
where const_law_name is the name of the constitutive law and const_law_data depends on the specificconstitutive law. The latter fields, whose type depends on the dimensionality of the constitutive law,
are optional, under the assumption that the constitutive law is the last portion of a card, or that any
ambiguity can be avoided. The data specific to the currently available constitutive laws must be enteredas follows:

2.10.1

Linear elastic, linear elastic isotropic<specific_const_law> ::= linear elastic [ isotropic ] ,(real) <stiffness>the isotropic stiffness coefficient; the word isotropic can be omitted, essentially because it has no
meaning for scalar constitutive laws.
Example.
constitutive law: 1, name, "scalar isotropic law",
1, linear elastic, 1.e9;
constitutive law: 2, name, "3D isotropic law",3, linear elastic isotropic, 1.e9;
constitutive law: 3, name, "6D isotropic law",6, linear elastic isotropic, 1.e9;

72

Table 2.7: Constitutive laws dimensionality
Constitutive law
linear elastic, linear elastic isotropic
linear elastic genericlinear elastic generic axial torsion coupling
cubic elastic genericinverse square elastic
log elastic
linear elastic bistop
double linear elastic
isotropic hardening elastic
scalar function elastic, scalar function elastic isotropic
scalar function elastic orthotropic
linear viscous, linear viscous isotropic
linear viscous genericlinear viscoelastic, linear viscoelastic isotropic
linear viscoelastic genericlinear time variant viscoelastic genericlinear viscoelastic generic axial torsion coupling
cubic viscoelastic generic
double linear viscoelastic
turbulent viscoelastic
linear viscoelastic bistop
shock absorbersymbolic elastic
symbolic viscous
symbolic viscoelastic
ann elastic
ann viscoelastic
nlsf elastic
nlsf viscous
nlsf viscoelastic
nlp elastic
nlp viscous
nlp viscoelastic
Constitutive law wrapper
array (wrapper)
bistop (wrapper)
invariant angular (wrapper)

73

1D
√
√

3D
√
√

√
√
√
√
√
√
√
√
√
√
√
√
√

√

√
√
√
√
√
√
√
√
√
√
√
√
√
√
√
√

√
√

1D
√
√

√
√
√
√
√
√
√
√
√
√

6D
√
√
√

√
√
√
√
√
√
√
√
√
√

√

√

√
√
√
√
√
√
√
√
√
√
√

√
√
√
√
√
√
√
√
√
√
√

3D
√
√
√

6D
√
√

2.10.2

Linear elastic generic<specific_const_law> ::= linear elastic generic ,(DerivativeOfEntity) <stiffness>the stiffness matrix. In case of 1D, the type is scalar, and there is no distinction between generic andisotropic, while, in case of N × 1 vectors, the type is the corresponding N × N matrix.
Example.
constitutive law: 1, name, "scalar isotropic law",
1, linear elastic generic, 1.e9;
constitutive law: 2, name, "3D isotropic law",3, linear elastic generic,sym, 1.e9, 0.,0.,1.e6, -1.e5,
1.e6;
constitutive law: 3, name, "6D isotropic law",6, linear elastic generic,diag, 1.e9, 1.e9, 1.e9, 1.e6, 1.e6, 1.e6;

2.10.3

Linear elastic generic axial torsion coupling<specific_const_law> ::=linear elastic generic axial torsion coupling ,(DerivativeOfEntity) <stiffness> ,(real) <coupling_coefficient>
this is defined only for 6 × 1 vectors, where the torsion stiffness, coefficient a44 in the stiffness matrix,
depends linearly on the axial strain, ε1 , by means of coupling_coefficient, i.e. the run-time torsion
stiffness is
a44 = GJ + coupling_coefficient · ε1 .

(2.57)

This <coupling_coefficient>, in the classical nonlinear beam theory, is estimated according to somegeometric property [3]; a general approach to the computation of prestressed beam properties is presented
in [4], which is implemented in some versions of the ANBA software.

2.10.4

Cubic elastic generic<specific_const_law> ::=cubic elastic generic(Entity) <stiffness_1> ,(Entity) <stiffness_2> ,(Entity) <stiffness_3>
this is defined only for scalar and 3 × 1 vectors; the constitutive law is written according to the formulaf = stiffness_1 · ε + stiffness_2 · |ε| ε + stiffness_3 · ε374

(2.58)

2.10.5

Inverse square elastic<specific_const_law> ::= inverse square elastic ,(real) <stiffness> , (real) <ref_length>
this is defined only for scalars. The force is defined as:f=

2.10.6

stiffness(ref_lenght · (1 + ε))2(2.59)

Log elastic<specific_const_law> ::= log elastic ,(DerivativeOfEntity) <stiffness>this is defined only for scalars. The force is defined as:
f = stiffness · log (1 + ε)

2.10.7(2.60)

Linear elastic bistop<specific_const_law> ::= linear elastic bistop ,(DerivativeOfEntity) <stiffness> ,[ initial status , { inactive | active | (bool) <status> } , ](DriveCaller) <activating_condition> ,(DriveCaller) <deactivating_condition>

2.10.8

Double linear elastic<specific_const_law> ::= double linear elastic ,(real) <stiffness_1> ,(real) <upper_strain> ,(real) <lower_strain> ,(real) <stiffness_2>
this is defined for scalar and 3×1 vectors. In the scalar case the meaning of the entries is straightforward,
while in case of 3 × 1 vectors the constitutive law is isotropic but in the local direction 3, where, in caseof strain out of the upper or lower bound, the stiffness_2 is used.

2.10.9Isotropic hardening elastic<specific_const_law> ::= isotropic hardening elastic ,(real) <stiffness> ,(real) <reference_strain>[ , linear stiffness , <linear_stiffness> ]this constitutive law is defined as follows:2

f = stiffness2

β + α |ε|1 + α |ε|2εwhere α = 3/ |reference_strain| , and β = linear_stiffness/stiffness. The resulting constitutive
law, in the scalar case, is somewhat soft/hard when β is lower/greater than 1 and |ε| is smaller thanreference_strain, approaching linear_stiffness when ε → 0, while it grows to quasi-linear for larger|ε|, with slope stiffness.
75

2.10.10

Scalar function elastic, scalar function elastic isotropic

This constitutive law is based on a ScalarFunction to represent an analytical force-displacement curveof a single variable that is automatically differentiated to compute the slope of the curve, namely the
local stiffness.
<specific_const_law> ::= scalar function elastic [ isotropic ] ,(DifferentiableScalarFunction) <function>
this constitutive law is defined as follows:fi = function (εi )the force is computed for each direction as a function of the respective strain component using the samefunction. When used for 1D elements, the word isotropic can be omitted.

2.10.11

Scalar function elastic orthotropic<specific_const_law> ::= scalar function elastic [ orthotropic ] ,{ (DifferentiableScalarFunction) <function> | null }[ , ... ]this constitutive law is defined as follows:fi = functioni (εi )the force is computed for each direction as a function of the respective strain component using a specificfunction for each component. If no force ought to be used for a direction, for example because that
direction is constrained by a kinematic joint, the keyword null can be used to indicate that no function
is expected for that component. When used for 1D elements, the word orthotropic can be omitted;
note that in this case a scalar function elastic isotropic constitutive law is actually instantiated.
Example.
scalar function: "myfunc", multilinear,-1., -100.,-.5, -70.,
0., 0.,.5, 70.,1., 100.;
constitutive law: 1000, 3,
scalar function elastic orthotropic,
null,
null,
"myfunc";
indicates that the constitutive law is only defined in direction 3 as a multilinear function.

2.10.12

Linear viscous, linear viscous isotropic<specific_const_law> ::= linear viscous [ isotropic ] ,(real) <viscosity>
the linear viscous coefficient.
Note: this constitutive law does not require any prestrain template drive caller.
762.10.13

Linear viscous generic<specific_const_law> ::= linear viscous generic ,(DerivativeOfEntity) <viscosity>
the linear viscous N × N matrix.
Note: this constitutive law does not require any prestrain template drive caller.

2.10.14

Linear viscoelastic, linear viscoelastic isotropic<specific_const_law> ::= linear viscoelastic [ isotropic ] ,(real) <stiffness> ,{ (real) <viscosity>| proportional , (real) <factor> }the isotropic stiffness and viscosity coefficients. If proportional is given, then viscosity = factor ·stiffness.

2.10.15

Linear viscoelastic generic<specific_const_law> ::= linear viscoelastic generic ,(DerivativeOfEntity) stiffness ,{ (DerivativeOfEntity) <viscosity>| proportional , (real) <factor> }the linear stiffness and viscosity N × N matrices. If proportional is given, then viscosity = factor ·stiffness.

2.10.16

Linear time variant viscoelastic generic<specific_const_law> ::= linear time variant viscoelastic generic ,(DerivativeOfEntity) <stiffness> ,(DriveCaller) <stiffness_scale> ,{ (DerivativeOfEntity) <viscosity>| proportional , (real) <factor> } ,(DriveCaller) <viscosity_scale>the linear stiffness and viscosity matrices are multiplied by the respective scale factors,
f = stiffness · stiffness_scale · ε + viscosity · viscosity_scale · ε̇.

(2.61)

If proportional is given, then viscosity = factor · stiffness.
Example.
linear time variant viscoelastic,
1000., cosine, 2., pi/.2, .1/2, half, 1.,100., cosine, 2., pi/.2, 1/2, half, 1.
At 2s, the stiffness grows of 10% from the nominal value in .2s, while the damping doubles. See Section 2.6
for details on the syntax of DriveCaller entities.
Beware that arbitrarily changing the stiffness and the damping of an elastic component during theexecution of the simulation may have no physical meaning. The intended use of this feature is for tailoring
the analysis; for example, a higher damping level may be desirable to smooth out a non-physical transient,and later return to the appropriate damping value.
772.10.17

Linear viscoelastic generic axial torsion coupling<specific_const_law> ::=linear viscoelastic generic axial torsion coupling ,(DerivativeOfEntity) <stiffness> ,{ (DerivativeOfEntity) <viscosity>| proportional , (real) <factor> }(real) <coupling_coefficient>
this is defined only for 6 × 1 vectors; it is the viscoelastic extension of the linear elastic genericaxial torsion coupling constitutive law (see Section 2.10.3).

2.10.18

Cubic viscoelastic generic<specific_const_law> ::=cubic elastic generic(Entity) <stiffness_1> ,(Entity) <stiffness_2> ,(Entity) <stiffness_3> ,(DerivativeOfEntity) <viscosity>
this is defined only for scalar and 3 × 1 vectors; the constitutive law is written according to the formulaf = stiffness_1 · ε + stiffness_2 · |ε| ε + stiffness_3 · ε3 + viscosity · ε̇and it is mainly intended for use with human body models where the stiffness of the joints is typicallygiven in this form.

2.10.19

Double linear viscoelastic<specific_const_law> ::= double linear viscoelastic ,(real) <stiffness_1> ,(real) <upper_strain> ,(real) <lower_strain> ,(real) <stiffness_2> ,(real) <viscosity>[ , second damping , (real) <viscosity_2> ]this is analogous to the double linear elastic constitutive law, except for the isotropic viscosity term.
The second viscosity value is used when the strain is outside the lower_strain − upper_strain range.
When this constitutive law is used with 3 × 1 vectors, the double linear elastic and viscous term only
applies to component 3.

2.10.20

Turbulent viscoelastic<specific_const_law> ::= turbulent viscoelastic ,(real) <stiffness> ,(real) <parabolic_viscosity>[ , (real) <threshold>[ , (real) <linear_viscosity> ] ]78

the constitutive law has the form:f = stiffness ε + k ε̇where:k=

linear_viscosity
parabolic_viscosity|ε̇| ≤ threshold|ε̇| > threshold

if threshold is null, or not defined, the constitutive law is always parabolic. If the linear_viscosity
is not defined, it is computed based on parabolic_viscosity and on threshold to give a continuous
force curve (with discontinuous slope). Otherwise, it can be set by the user to give a discontinuous force
curve, as observed in some fluids at intermediate Reynolds number.

2.10.21

Linear viscoelastic bistop<specific_const_law> ::= linear viscoelastic bistop ,(DerivativeOfEntity) <stiffness> ,(DerivativeOfEntity) <viscosity> ,[ initial status , { inactive | active | (bool) <status> } , ](DriveCaller) <activating_condition> ,(DriveCaller) <deactivating_condition>

2.10.22

GRAALL damper

This very experimental constitutive law, based on a nonlinear model for a hydraulic damper to be usedin landing gear modeling, has been moved to module-damper-graall.

2.10.23

shock absorberThis constitutive law implements a landing gear hydraulic shock absorber:<specific_const_law> ::= shock absorber ,[ prestrain , <value> , ]<reference_pressure> ,<reference_area_for_force_computation> ,<interaction_coefficient> ,<polytropic_exponent> ,[ epsilon max , <upper_strain_bound> , ][ epsilon min , <lower_strain_bound> , ][ penalty , <penalty_factor_for_strain> ,<penalty_factor_for_strain_rate> , ][ metering , (DriveCaller)<metering_area> ,[ negative , (DriveCaller)<metering_area_for_negative_strain_rate> , ][ orifice , (DriveCaller)<orifice_area> , ]<fluid_area> ,<fluid_density> ,<drag_coefficient_/_reference_length> # scales strain rate to velocity[ , friction , <reference_epsilon_prime> ,<friction_amplitude_coefficient> ]
where

79

• the interaction_coefficient is represented bykinematic scale ·LA
V0

where kinematic scale is the ratio between the stroke of the shock absorber and that of the gas;
• upper_strain_bound is the upper strain bound; it must be at least larger than the prestrain, anddefaults to 0, i.e. the shock absorber, at rest, is assumed to be fully extended;• lower_strain_bound is the lower strain bound; it must be at least smaller than the prestrain,
and defaults to -0.5, i.e. the shock absorber is assumed to allow a contraction equal to half its fulllength;• the penalty_factor_for_strain defaults to 1e+9; it is active only when strain bounds are violated;• the penalty_factor_for_strain_rate defaults to 0; it is active only when strain bounds are
violated;• the metering_area is given by a DriveCaller and is strain dependent; if the keyword negativeis used, then the metering_area_for_negative_strain_rate is used when the strain rate is
negative, i.e. the shock absorber is being compressed, while metering_area is used only when theshock absorber is extending;• the orifice drive determines the area of an additional orifice, which essentially depends on thesign of the strain rate; it is used to implement relief valves;• ...
This constitutive law contributes to the output of the element it is associated with. The name associatedto each output contribution can be used to reference the corresponding value as element private data.
The contributions are
1. "p" gas pressure;
2. "A" metering area;
3. "Fe" elastic force;
4. "Fv" viscous force.

2.10.24

symbolic elastic

The implementation of the family of symbolic constitutive laws is based on GiNaC (http://www.ginac.de/),a free software package for symbolic algebra manipulation. It is essentially used to automatically differentiate the user-supplied expression that describes the relationship between the output and the input.
The syntax is<specific_const_law> ::= symbolic elastic ,epsilon , " <epsilon> " [ , ... ] ,expression , " <expression> " [ , ... ]where epsilon is the symbol describing the input parameter as it will be used in expression.
For constitutive laws with more than one dimension, a string for each epsilon and one for each
expression are expected. For example:80

# 1D symbolic constitutive law
constitutive law: 1001, 1, symbolic elastic,
epsilon, "eps",
expression, "1000.*eps + 5.*eps^3";# 3D symbolic constitutive law
constitutive law: 1003, 3, symbolic elastic,
epsilon, "eps1", "eps2", "eps3",
expression,"1000.*eps1 + 5.*eps1^3 - 10.*eps2*eps3","1000.*eps2 + 5.*eps2^3 - 10.*eps3*eps1","1000.*eps3 + 5.*eps3^3 - 10.*eps1*eps2";
Note: right now, the symbols defined within the mathematical parser are not available within symbolic
constitutive laws.

2.10.25

symbolic viscous

The syntax is<specific_const_law> ::= symbolic viscous ,epsilon prime , " <epsilon_prime> " [ , ... ] ,expression , " <expression> " [ , ... ]where epsilon_prime is the symbol describing the derivative of the input parameter as it will be usedin expression.
For constitutive laws with more than one dimension, a string for each epsilon_prime and one foreach expression are expected.

2.10.26

symbolic viscoelastic

The syntax is<specific_const_law> ::= symbolic viscoelastic ,epsilon , " <epsilon> " [ , ... ] ,epsilon prime , " <epsilon_prime> " [ , ... ] ,expression , " <expression> " [ , ... ]where epsilon and epsilon_prime are the symbols describing the input parameter and its derivative
as they will be used in expression.
For constitutive laws with more than one dimension, a string for each epsilon, one for each epsilon_prime,and one for each expression are expected.

2.10.27ann elastic

The implementation of the family of ann constitutive laws is based on an Artificial Neural Network
library that is embedded in MBDyn.
The syntax is<specific_const_law> ::= ann elastic ," <file_name> "where the file file_name contains the parameters of the network. What is mainly significant to users
is the need to scale inputs and outputs to match the amplitudes and possibly the offsets used in the
training. For this purpose, the last two rows of the input files contain coefficients81b1 b0a1 a0which are used to scale the input u and the output y according to the transformationu = b1 u + b0
y = a1 y + a0

(2.62)(2.63)

f (b1 u + b0 ) − a0a1(2.64)

so that the actual output isy=2.10.28

ann viscoelastic

The syntax is<specific_const_law> ::= ann viscoelastic ," <file_name> "where the file file_name contains the parameters of the network.

2.10.29

nlsf viscoelastic

This constitutive law was sponsored by Hutchinson CdR.
For an n-dimensional constitutive law, it implements the formula
X
X
′′
′
k0ij
ε̇j + fi′′ (ε˙i )k0ij
εj + fi′ (εi ) +fi =(2.65)

j=1,n

j=1,n

where fi′ and fi′′ are arbitrary instances of the scalar functions primitive, which includes piecewise′′′
linear and spline regularization of given data, while k0ij
and k0ij
are the constant coefficients of a linear
viscoelastic model, that account for the cross-couplings between the stresses and the strains and strain
rates.
Elastic and viscous variants are defined. They differ from the viscoelastic one by only allowing thespecific fraction of the input data.
Syntax.

The syntax is<specific_const_law> ::= nlsf viscoelastic ,(DerivativeOfEntity) <kappa_0’> ,{ null | (ScalarFunction) <diag_force’> }[ , ... ] ,{ (DerivativeOfEntity) <kappa_0’’> | proportional , <coef> } ,{ null | (ScalarFunction) <diag_force’’> }[ , ... ]<specific_const_law> ::= nlsf elastic ,(DerivativeOfEntity) <kappa_0’> ,{ null | (ScalarFunction) <diag_force’> }[ , ... ]82

<specific_const_law> ::= nlsf viscous ,(DerivativeOfEntity) <kappa_0’’> ,{ null | (ScalarFunction) <diag_force’’> }[ , ... ]The terms kappa_0’ and kappa_0’’ are indicated as DerivativeOfEntity because in the generic casethey are the result of a differential operator that computes the derivative of the force vector as functionof the strain or strain rate vectors. So, for a 3D constitutive law, the force, the strain and the strain rate
are 3 × 1 vectors, while kappa_0’ and kappa_0’’ are 3 × 3 matrices. Matrix input, in MBDyn, requires
to write the whole set of coefficients, row-wise; however, it can be described in many synthetic manners
if matrices have some special properties, as typical linear constitutive laws do.
For example, symmetric, diagonal and empty matrices have specific short forms; in the 3 × 3 casethey are# generic 3x3 matrix:
10., -2., -2.,
-2., 20., -8.,
-2., -8., 20.
# symmetric 3x3 matrix (same as above matrix):sym,
10., -2., -2.,
20., -8.,20.
# diagonal 3x3 matrix (diagonal of above matrix):diag,10., 20., 20.
# empty 3x3 matrix:null
The terms diag_force’ and diag_force’’ refer to the names of the scalar functions that are defined foreach component of the force vector. There must be as many terms as the dimensions of the constitutive
law. These terms can either be null, if no non-linear contribution is defined for that component, or
contain a string, enclosed in double quotes, which must refer to an already defined scalar function. The
same scalar function can be used multiple times.
Example.

A 1D and a 3D constitutive law using the same exponential scalar function:# define a scalar function
scalar function: "exponential", exp, coefficient, -2., 5.;# define a 1D constitutive law
constitutive law: 1000, 1,
nlsf viscoelastic,
10.,
null,
0.,
"exponential";# stiffness is just linear# damping is exponential83

# define a 3D constitutive law
constitutive law: 3000, 3,
nlsf viscoelastic,sym,
10., -2., -2.,
10., -2.,
10.,
null,
null,
null,
null,
"exponential",
null,
null;

# stiffness is just linear# stiffness is just linear# stiffness is just linear# damping is exponential...
# ...but in direction 1 only!

The first constitutive law corresponds to
f = 10.0 · ε + 5.0 · e−2ε̇while the second one corresponds to

 


10.0 −2.0 −2.0  ε1   5.0 · e−2ε̇1 
ε20.0
f =  −2.0 10.0 −2.0 
+


 
ε3
0.0
−2.0 −2.0 10.0

2.10.30(2.66)(2.67)

nlp viscoelastic

This constitutive law was sponsored by Hutchinson CdR.
This constitutive law consists in the linear combination of nonlinear elastic and viscous effects whose
coefficients are arbitrary nonlinear functions of the strain ε:
X
X


′′
′
k0ij
+ δij ki′′ (εi ) ε̇j ,(2.68)
k0ij+ δij ki′ (εi ) εj +
fi =
j=1,3

j=1,3

where δij is Kronecker’s operator; ki′ and ki′′ are implemented as arbitrary scalar functions, which
includes piecewise linear and spline regularization of given data.
Elastic and viscous variants are defined. They differ from the viscoelastic one by only allowing thespecific fraction of the input data.
Syntax.

The syntax is<specific_const_law> ::= nlp viscoelastic ,(DerivativeOfEntity) <kappa_0’> ,{ null | (ScalarFunction) <diag_stiffness> }[ , ... ] ,{ (DerivativeOfEntity) <kappa_0’’> | proportional , <coef> } ,{ null | (ScalarFunction) <diag_damping> }[ , ... ]<specific_const_law> ::= nlp elastic ,(DerivativeOfEntity) <kappa_0’> ,84

{ null | (ScalarFunction) <diag_stiffness> }[ , ... ]<specific_const_law> ::= nlp viscous ,(DerivativeOfEntity) <kappa_0’’> ,{ null | (ScalarFunction) <diag_damping> }[ , ... ]Example.

A 1D and a 3D constitutive law using the same exponential scalar function:# define a scalar function
scalar function: "exponential", exp, coefficient, -2., 5.;# define a 1D constitutive law
constitutive law: 1000, 1,
nlp viscoelastic,
10.,
null,
0.,
"exponential";# define a 3D constitutive law
constitutive law: 3000, 3,
nlp viscoelastic,sym,
10., -2., -2.,
10., -2.,
10.,
null,
null,
null,
null,
"exponential",
null,
null;

# stiffness is just linear# damping slope is exp.

# stiffness is just linear# stiffness is just linear# stiffness is just linear# damping slope is exp...
# ...but in direction 1 only!

The first constitutive law corresponds to
f = 10.0 · ε + 5.0 · e−2ε · ε̇while the second one corresponds to 
10.0 −2.0 −2.0  ε1 
5.0 · e−2ε1



ε2
0.0
f = −2.0 10.0 −2.0+
−2.0 −2.0 10.0
ε3
0.0

(2.69)


0.0 0.0  ε̇1 
0.0 0.0 ε̇2
0.0 0.0ε̇3(2.70)

Note: although the syntax of this constitutive law and that of the nlsf viscoelastic one (Section 2.10.29) is essentially identical, their behavior may be quite different, as indicated by Equations (2.65)
and (2.68).

85

2.10.31

arrayThis constitutive law wrapper linearly combines the output of multiple constitutive laws. The syntax is<specific_const_law> ::= array ,<number> ,<wrapped_const_law> [ , ... ]The type of the resulting constitutive law is computed by combining that of the underlying constitutive
laws. For example, if an elastic and a viscous constitutive law are combined, the type of the resulting
array is viscoelastic. If number is 1, the underlying constitutive law is instantiated, and the array isignored. Each underlying constitutive law can have a specific value of prestress and prestrain, as allowedby its own definition. No overall prestress nor prestrain is allowed by the array wrapper.
Example.
# the constitutive law
array, 2,linear elastic, 1000.,
linear viscous, 10.
# is equivalent tolinear viscoelastic, 1000., 10.

2.10.32

bistopThis wrapper applies the logic of the bistop, that is activate or deactivate the constitutive property basedon distinct conditions, with memory, to a generic underlying constitutive law. The syntax is<specific_const_law> ::= bistop ,[ initial status , { inactive | active | (bool) <status> } , ](DriveCaller) <activating_condition> ,(DriveCaller) <deactivating_condition> ,(ConstitutiveLaw<<Entity>, <DerivativeOfEntity>>) <wrapped_const_law>

2.10.33

invariant angularThis is not a constitutive law, but rather a wrapper for constitutive laws used within the “attached”
variant of the deformable hinge joint. As such, it can only be used with the 3D dimensionality. It
basically allows to refer an ancillary 3D constitutive law to an orientation that is intermediate withrespect to the orientations of the two connected nodes.
<specific_const_law> ::= invariant angular ,<xi> , <wrapped_const_law>
xi is the fraction of relative orientation the ancillary constitutive law will be referred to, with respect
to the first node of the joint. Its value should be comprised between 0 (attached to the first node) and1 (attached to the second node); a value of 1/2 yields the invariant deformable hinge joint, but any
value is allowed, not limited to within the [0, 1] range.
Note: the contribution to the Jacobian matrix will be incomplete when the underlying constitutive
law has a viscous contribution. This may slow down convergence, or even prevent it. If this is an issue,
the invariant deformable hinge should be used, since it does not suffer from this limitation, although
it only allows xi = 1/2.
86

2.11

Hydraulic fluid

Hydraulic fluid data defines the constitutive properties of hydraulic fluids, which are generally requiredby hydraulic elements. Hydraulic fluid data can be defined in two ways, according to the BNF:
<hydraulic_fluid> ::={ <fluid_type> , <fluid_properties>| reference , <label> }The latter references a previously defined hydraulic fluid dataset, described in Section 2.4.4. The available
types fluid_type, with the related fluid_properties, are:2.11.1

Incompressible<fluid_type> ::= incompressible<fluid_properties> ::=<property> [ , ... ]<property> ::={ density , <density>| viscosity , <viscosity>| pressure , <pressure>| temperature , <temperature> }2.11.2

Linearly compressible<fluid_type> ::= linear compressible<fluid_properties> ::=<property> [ , ... ]<property> ::={ density , <ref_density> ,{ sound celerity , <sound_celerity> | <beta> } , <ref_pressure>| viscosity , <viscosity>| temperature , <temperature> }If the keyword sound celerity is used, the bulk modulus beta is computed asbeta = ref_density · sound_celerity2

2.11.3

Linearly compressible, with thermal dependency<fluid_type> ::= linear thermal compressible<fluid_properties> ::=<property> [ , ... ]<property> ::={ density , <ref_density> ,87(2.71)

{ sound celerity , <sound_celerity> | <beta> } , <ref_pressure><alpha> , <ref_temperature>| viscosity , <viscosity> }2.11.4

Super (linearly compressible, with thermal dependency)<fluid_type> ::= super<fluid_properties> ::=<property> [ , ... ]<property> ::={ density , <ref_density> ,{ sound celerity , <sound_celerity> | <beta> } , <ref_pressure>| viscosity , <viscosity>| temperature , <temperature> }according to equation
ρ− = ρ0 + ref_density ·1(1 + tanh (a (p − p0 )))2

ρ = ρ−
ρ = ρ− +p < p0p − p0beta(2.72)

p > p0Note: highly experimental; currently, ρ0 , a and p0 are hardcoded in SI units; the syntax will change

2.11.5

Exponential compressible fluid, with saturation<fluid_type> ::= exponential<fluid_properties> ::=[ <property> [ , ... ] , ] <p_sat><property> ::={ density , <ref_density> ,{ sound celerity , <sound_celerity> | <beta> } , <ref_pressure>| viscosity , <viscosity>| temperature , <temperature> }where p_sat is the saturation pressure, according to equationp − ref_pressurebetaρ = ref_density · ep − ref_pressure
1000
beta
ρ = ref_density · ep > p_sat
p < p_sat(2.73)

Note: this fluid constitutive law is loosely inspired by AMESim’s simply corrected compressible fluid.

88

2.12

Authentication Methods

Some authentication methods are defined and made available to specific program modules; they are used
to authenticate before accessing some resources of the program while it is running. The syntax is:<authentication_method> ::= <method> [ , <specific_data> ]Authentication methods in general expect some authentication tokens to be input. Usually a user nameand a password are required.

2.12.1

Note on security and confidentiality

No encryption is used in communications, unless provided by the underlying mechanism (e.g. some
SASL mechs), so the authentication methods are very rough and should be considered as insecure. TLS
may be considered in the future. If confidentiality is required, SASL with at least DIGEST-MD5 isstrongly recommended; otherwise no authentication should be used. As an alternative, a SSH tunnel
may be established between the client and the server machine, and simple authentication can be used.
Otherwise, if the user has direct access to the server where the computation is being run, sockets withlocal namespace can be used, and security can be enforced by means of the access privileges of thesocket file. Since some of the UN*X systems do not honor socket permissions, a portable way to exploit
filesystem access permissions is to put the socket in a dedicated directory, and use the permissions of thedirectory to control access to the socket.
Available methods are:2.12.2

No authentication<authentication_method> ::= no auth2.12.3

Password<authentication_method> ::= password<specific_data> ::=user , " <user_name> " ,credentials , { prompt | " <user_cred> " }[ , salt format , <salt_format> ]In case the keyword prompt is given as credentials, the user is prompted for a password; user_cred
is used otherwise. The optional parameter salt_format allows to specify different formats for the salt,
for those crypt(3) extensions that support more sophisticated encryption mechanisms (e.g. MD5). See
crypt(3) for details. If the credentials are preceded by the string {CRYPT}, they are assumed to bealready encrypted, and the remaining portion is used.

2.12.4

PAM (Pluggable Authentication Modules)<authentication_method> ::= pam<specific_data> ::=[ user , " <user_name> " ]89

The Linux-PAM Pluggable Authentication Modules can be used to authenticate a user. If no username is provided, the effective user id, as provided by the geteuid(2) system function, is used to retrieve the username of the owner of mbdyn process. the user must be valid. The authentication is
performed through a system-dependent pam configuration file. No checks on the validity of the account or on the permission of opening a session are made; account, session and password changes
should be explicitly denied to mbdyn to avoid possible security breaks (see the following example).
The interested reader should consult the documentation that comes with the package, try for instance
http://www.kernel.org/pub/linux/libs/pam/ for details.
An example is provided with the package, in /etc/pam.d/mbdyn:### use either of the following:authrequired/lib/security/pam_unix_auth.so# authrequired/lib/security/pam_pwdb.so#### no account, session or password allowed
account
required/lib/security/pam_deny.so
sessionrequired/lib/security/pam_deny.sopassword
required/lib/security/pam_deny.sowhich allows authentication by using standard Un*x or libpwdb based authentication.

2.12.5

SASL (Simple Authentication and Security Layer)<authentication_method> ::= sasl
<specific_data> ::= [ <parameter> [ , ... ] ]<parameter> ::={ user , " <user_name> "| mechanism , " <preferred_mechanism> " }This is the preferred authentication method because it is mechanism-independent, it can be reasonably
secure and automatically selects the most appropriate mechanism available on both the client and theserver machine. It requires Cyrus SASL 2 (See http://asg.web.cmu.edu/sasl/ for details, and follow
the documentation to obtain a working setup).

2.13

Miscellaneous

Finally there are some miscellaneous points:• (UN*X systems) Environment variables whose name starts with MBDYN may be defined andpassed to an execution of the mbdyn command. The following are recognized at present:
1. MBDYNVARS=<expr_list> where expr_list is a series of mathematical expressions separated
by semicolons. They are parsed and evaluated; if variables are declared, they are added tothe symbol table to be used during the whole execution of the program.
2. MBDYN_<type>_<name>=<value>, where type is a legal mbdyn type (integer, real or string;see Table 2.2 for details), name is a legal symbol name and value is a legal expression.
Example: sample code to execute MBDyn from within a python script, passing it the time stepin the real variable DT:90

import os;
dt = 1.e-3;
os.environ[’MBDYNVARS’] = ’real DT = ’ + str(dt) + ’;’;
os.system(’mbdyn -f input.mbd -o output > output.txt 2>&1 &’);
# use ’dt’ in the python peer’s analysis as appropriate...
• Newlines and indentations are not meaningful. But good indentation habits can lead to better andmore readable input files.
• Everything that follows the character ‘#’ is considered a remark, and is discarded until the endof the line. This can occur everywhere in the file, even inside a math expression (if any problems
occur, please let me know, because chances are it is a bug!)• A new style for comments has been introduced, resembling the C programming language style:everything comprised between the marks /* and */ is regarded as a remark:/** useful comments make input files readable!
*/
This can happen (almost) everywhere in the text except in the middle of a keyword.
• (UN*X systems) Whenever a file name contains a portion of the form $VARNAME or ${VARNAME},
appropriate expansion from environment is performed; VARNAME is
VARNAME ::= [_a-zA-Z][_a-zA-Z0-9]*
namely, it must begin with a letter or an underscore, and can be made of underscores, letters anddigits.
• (UN*X systems) Whenever a file name is required, if the string containing the file name starts with’$’, shell environment variable expansion occurs.
Example: expand the local socket’s name in external forces# ...
path, "$MBSOCK",# ...
Example: sample code to execute MBDyn from within a python script, passing it the name of
the local socket to be used for an external force:
import os;
import tempfile;tmpdir = tempfile.mkdtemp(’’, ’.mbdyn_’);path = tmpdir + ’/mbdyn.sock’;
os.environ[’MBSOCK’] = path;os.system(’mbdyn -f input.mbd -o output > output.txt 2>&1 &’);
# use ’path’ as the name of the socket as shown in the previous example# ...
# when done...
os.rmdir(tmpdir);91

This code:– creates a uniquely named temporary directory in the default temporary directory (e.g. /tmp)
only accessible to the owner of the process, according to /tmp/.mbdyn_XXXXXX, where XXXXXX
are six random chars (see mkdtemp(3) for details);– appends the name /mbdyn.sock to form the full path of the socket;– sets the full path of the socket in the environment under the name MBSOCK;– executes MBDyn; its input file is supposed to use ”$MBSOCK” as path name of a local socket.
This procedure guarantees that a co-simulation performed between MBDyn and the peer Python
script uses a unique, protected socket and thus does not interfere with other co-simulations runningon the same system.
• (UN*X systems) Whenever a file name is required, the shell-like syntax for home directories (i.e.
~/filename or ~user/filename is automatically resolved if legal [user and] filename values areinserted. Home expansion occurs after environment variable expansion (see above).
• The license and the warranty statements respectively show on the standard output the license
and the warranty statement under which the code is released. They do not affect the simulation.

92

Chapter 3

Data
The data section is read directly by the driver program. It is included between the cards:
begin : data ;# ...
end : data ;3.1

Problem

The only active card is the problem card.
The syntax is<card> ::= problem : <problem_name> ;<problem_name> ::= { initial value | inverse dynamics } ;For long time the only supported problem type was the initial value problem. As a consequence, if
no problem card is present, an initial value problem is assumed. An experimental inverse dynamics
problem is supported as well.

93

Chapter 4

Problems
This section is used to insert all the data related to the problem that one needs MBDyn to solve in thesimulation. The section data are included between the cards:
begin : <problem_name> ;# ...
end : <problem_name> ;Implemented problems are:• initial value, the time integration of mechanical and multidisciplinary problems formulated as
Differential-Algebraic Equations (DAE). It can be downgraded to the solution of static and kinematic problems, by selecting purely static or kinematic contributions to the governing equations,thus giving time the role of an ordinal parameter.
• inverse dynamics, the computation of the generalized forces required to make a generic system
perform a given trajectory. This problem is currently under development, so it is not discussed indetail.

4.1

Initial-Value Problem

At present, the main problem is initial value, which solves initial value problems by means of genericintegration schemes that can be cast in a broad family of multistep and, experimentally, Implicit RungeKutta-like schemes [5].
The syntax of the module is:begin : initial value ;# ...
end : initial value ;At present, there are a number of cards that can be grouped as follows, based on the integration phasethey refer to.

4.1.1

General Data

those data that refer to the main integration phase or the simulation as a whole. They are:94

Initial Time<card> ::= initial time : <time> ;Final Time<card> ::= final time : { forever | <time> } ;Strategy<card> ::= strategy : <strategy_type> [ , <strategy_data> ] ;The available strategies are:• no change<strategy_type> ::= no change
the time step is never changed. However, this prevents simulation termination when the maximum
number of iterations is reached. As a consequence, its use only makes sense when repeating a time
step results in some modification of the analysis related to some user-defined function.
• factor<strategy_type> ::= factor<strategy_data> ::=<reduction_factor> ,<steps_before_reduction> ,<raise_factor> ,<steps_before_raise> ,<min_iterations>[ , <max_iterations> ]the time step is reduced or raised of the proper factor not before a minimum number of time steps; itis reduced if more than max_iterations are performed at a time step, or it the current step do notconverge; it is raised if less than min_iterations are performed at a time step; max_iterations
defaults to the global max_iterations simulation value; however, it is better to set it to a lower
value, leaving some spare iterations before bailing out the simulation; the simulation bails out if
two consecutive solution steps are performed without converging.
• change<strategy_type> ::= change<strategy_data> ::= (DriveCaller) <time_step_pattern>
the time step is changed according to the time_step_pattern pattern. If the time step returnedby the drive caller does not change when a step needs to be repeated, the analysis is interrupted.
Note: the change strategy is not normally intended to provide adaptive time step, it rather allows
to prescribe a given variable time step pattern based on the rule defined by the time_step_pattern
DriveCaller.
In any case, step change only occurs after the first step, which is performed using the time_step value
provided with the time step statement.
95

Min Time Step
<card> ::= min time step : <min_time_step> ;Defines the minimum value allowed for the time step. This statement is only meaningful when variable
time step is used. If the time step change strategy tries to use a time step smaller than min_time_step,
the simulation aborts.
Max Time Step
<card> ::= max time step : { <max_time_step> | unlimited } ;Defines the maximum value allowed for the time step. This statement is only meaningful when variable
time step is used. If the time step change strategy tries to use a time step larger than max_time_step,
the value max_time_step is used instead.
Time Step<card> ::= time step : <time_step> ;The initial time step. This value is used throughout the simulation unless some variable time step
strategy is defined using the strategy statement.
Tolerance<card> ::= tolerance : { null | <residual_tolerance> }[ , test , { none | norm | minmax } [ , scale ] ][ , { null | <solution_tolerance> }[ , test , { none | norm | minmax } ] ] ;The only mandatory value is residual_tolerance, the tolerance used for the residual test; the keyword
null disables the residual testing, disabling the computation of the test on the residual. The test
mechanism is used to select what kind of test must be performed; currently, only norm (the default)
and minmax are supported. The special value none means that the test is not actually computed; it isthe default when the test is disabled by setting the tolerance to zero, or by using the keyword null;
however, it can be restored to any mechanism for output purposes. The optional parameter scale isused to enable the scaling of the residual before performing the test; default scale factors can be set foreach type of degree of freedom owner, as seen for the control data item of Section 5.2.13; some entities
allow individual scaling, as seen for nodes in Chapter 6; by default, no scaling takes place. A tolerance
solution_tolerance to test the solution (the difference between the states at two iterations) is allowed,
and also in this case a test mechanism can be chosen; by default, no test on the solution convergence isdone. Currently, no scaling is allowed in the solution test.
Example.
# residual test by means of the norm
tolerance: 1.e-6;# residual test with minmax method
tolerance: 1.e-6, test, minmax;# residual test with norm method and scaling
tolerance: 1.e-6, test, norm, scale;# solution test96

tolerance: null, 1.e-9;# residual and solution test
# (the first that succeeds breaks the loop)
tolerance: 1.e-6, 1.e-9;# residual test with computation of solution norm
tolerance: 1.e-6, null, test, norm;
Max Iterations<card> ::= max iterations : <max_iterations> [ , at most ] ;Error out after max_iterations without passing the convergence test. The default value is zero.
If the optional keywords at most are given, the step is considered successfully performed after
max_iterations regardless of passing the convergence test, as soon as the error reduced since the first
iteration. For example, when using
max iterations: 5, at most;the convergence pattern...
Iteration(0) 1.16374e+06 J
SolErr 0
Iteration(1) 8330.76 J
SolErr 0
Iteration(2) 43768.8 J
SolErr 0
Iteration(3) 2981.01 J
SolErr 0
Iteration(4) 118839 J
SolErr 0
Iteration(5) 8654.02 J...
succeeds, since 8654.02 < 1.16374e+06, while...
Iteration(0) 1.66901e+06 J
SolErr 0
Iteration(1) 2.06327e+09 J
SolErr 0
Iteration(2) 2.64337e+10 J
SolErr 0
Iteration(3) 1.2131e+12 J
SolErr 0
Iteration(4) 7.08449e+12 J
SolErr 0
Iteration(5) 2.18828e+15 J
Max iterations number 5 has been reached during Step=6, Time=0.06; \TimeStep=0.01 cannot be reduced further; aborting...
An error occurred during the execution of MBDyn; aborting...
fails since 2.18828e+15 > 1.66901e+06.
This option should be used with extreme care.
97Modify Residual Test<card> ::= modify residual test ;modify the residual test taking in account the rate of change of the status.
Method<card> ::= method : <method_data> ;there are four multistep methods at present.
The first is Crank-Nicolson:<method_data> ::= crank nicolson
The second and the third are original methods; the former is discussed in [5], see also
http://www.aero.polimi.it/mbdyn/publications.html
Those methods are unconditionally stable and can be tuned to give the desired algorithmic dissipation by
setting the value of the asymptotic spectral radius. The radius can be set independently for the differential
and the algebraic variables, and a driver is used, to allow parameter dependent radius variation.
<method_data> ::= { ms | hope } ,(DriveCaller) <differential_radius>[ , (DriveCaller) <algebraic_radius> ]The first method proved to be more accurate at high values of asymptotic radius (low dissipation),while the second proved to be more accurate at low values of the radius (high dissipation). They looknearly equivalent at radii close to 0.4, with the former giving the best compromise between algorithmic
dissipation and accuracy at about 0.6. The algebraic_radius can be omitted, defaulting to the sameas the differential one. It is unclear whether a different spectral radius can help in increasing accuracy
or dissipation of the algebraic unknowns.
The fourth method is experimental. It is a third-order, two stage unconditionally stable method,which can be tuned to give the desired algorithmic dissipation by setting the value of the asymptotic
spectral radius, which should not be too close to zero. Currently it is not possible to independently set
the radius for the differential and the algebraic variables.
<method_data> ::= third order ,{ ad hoc | (DriveCaller) <differential_radius> }When the keyword ad hoc is used, a method equivalent to a Runge-Kutta Radau IIA results, with zero
asymptotic spectral radius; otherwise, an original third-order integration method is used, with tunable
algorithmic dissipation.
The multistep method, when the asymptotic radius is zero, degenerates in the Backward Differentiation
Formulas of order two. A shortcut to this case is provided as<method_data> ::= bdf [ , order , <order> ]The keyword order can be used to indicate a specific order of the Backward Differentiation Formulas(BDF); only first order (implicit Euler) and second order formulas are currently implemented, and thedefault is the second order formula, which is the most useful. The first order formula may be of help forvery specific problems. It can also be selected using the shortcut<method_data> ::= implicit euler
98Nonlinear Solver
The nonlinear solver solves a nonlinear problem F (x) = 0. The syntax is<card> ::= nonlinear solver : <nonlinear_solver_name>[ , <nonlinear_solver_data> ] ;Currently available nonlinear solvers are:Newton-Raphson.
<nonlinear_solver_name> ::= newton raphson<nonlinear_solver_data> ::=[ { true| modified , <iterations>[ , keep jacobian matrix ][ , honor element requests ] } ] ;if modified, the number of iterations the same Jacobian matrix will be reused, and thus factored only
once, is expected. If the option keep jacobian matrix is selected, the Jacobian matrix is preserved
for the desired iterations even across time steps. By default, the Jacobian matrix is recomputed at
the beginning of each time step. If the option honor element requests is selected, the factorization is
updated also when an element changes the structure of its equations. The default behavior is to ignore
such requests1 . This nonlinear solver is well tested.
Line search.

Author: Reinhard Resch<nonlinear_solver_name> ::= line search<nonlinear_solver_data> ::=[ { true| modified , <iterations>[ , keep jacobian matrix ][ , honor element requests ] } ][ , tolerance x , <tolerance_x> ][ , tolerance min , <tolerance_min> ][ , max iterations , <max_iterations> ][ , alpha , <alpha> ][ , lambda min , <lambda_min>[ , relative , { yes | no | (bool) <relative> } ] ][ , lambda factor min , <lambda_factor_min> ][ , max step , <max_step> ][ , zero gradient , continue , { yes | no | (bool) <zero_gradient_continue> } ][ , divergence check , { yes | no | (bool) <divergence_check> }[ , factor , <factor> ] ][ , algorithm , { cubic | factor } ][ , scale newton step , { yes | no | (bool) <scale_newton_step> }[ , min scale , <min_scale> ] ]1 At present, only few elements that can change the structure of the equations, or at least radically change the Jacobianmatrix, actually issue this request.

99

[ , print convergence info , { yes | no | (bool) <print_convergence_info> } ][ , verbose , { yes | no | (bool) <verbose> } ][ , abort at lambda min , { yes | no | (bool) <abort_at_lambda_min> } ] ;• tolerance_x ≥ 0; default: tolerance_x = 10−7
• tolerance_min ≥ 0; default: tolerance_min = 10−8
• max_iterations ≥ 0; default: max_iterations = 200• alpha ≥ 0; default: alpha = 10−4
• lambda_min ≥ 0; default: lambda_min = 10−2
• 0 < lambda_factor_min < 1; default: lambda_factor_min = 10−1
• max_step ≥ 0; default: max_step = 100• factor ≥ 0; default: factor = 1• 0 ≤ min_scale ≤ 1; default: min_scale = 10−3
Brief description of the solver The line search solver should be used mainly if the Newton
Raphson solver diverges and further reduction of the time step is not possible or not available (forexample in the initial assembly phase). In many situations this solver is able to handle larger time steps
or load increments than the ordinary Newton Raphson solver. However the total number of iterations
can increase for large time steps.
The ordinary Newton Raphson strategy The Newton Raphson Solver solves a problem of theform F (x) = 0 by means of the iteration δx = J −1 F .
δx The increment of the solution x during one iteration.
J The modified Jacobian matrix. For example during the initial assembly phase J = − ∂F
∂x . On the∂Fother hand during the regular solution phase of an initial value problem J = − ∂F∂ ẋ − c ∂x and−1δ ẋ = J F whereas δx = c δ ẋ. But that’s totally transparent to the nonlinear solver.
If the prediction for x is close enough to the solution of the problem, the convergence rate will bequadratic as long as J is exact and F is continuously differentiable in the neighborhood of x. Otherwise
the rate of convergence will be not as good or even worse, the solution could diverge. The standard way
to overcome such problems is to reduce the time step or to use adaptive time step control. If there arestill convergence problems, the line search solver can be used.
The basic idea of line search

The line search solver from [6] uses the following modified strategy:δx = λ J −1 F

(4.1)

0 < λ ≤ 1 a scalar parameterIn other words the direction of the increment δx is the same like with the Newton Raphson solver
but the step size can be optionally reduced by the factor λ in order to avoid divergence.

100How to determine λ The parameter λ is chosen by the algorithm at each iteration in order tominimize the scalar function f = 21 F T F during the line search along the Newton direction δx. Since
the Newton direction δx is a descent direction for f , it is guaranteed that the residual will decrease ateach iteration as long as ∇f 6= 0, J is exact and F (x) is continuously differentiable in the neighborhoodof x.
Local minimum However it could happen that the solver converges to a local minimum of f where∇f = 0 but F 6= 0. The default behavior of the solver is to bail out in such a situation unless zero
gradient, continue, yes has been specified. This flag has been added in order to test the solver but
should not be used in general. If the solver bails out because the gradient ∇f is close to zero, it isrecommended to decrease either <tolerance_min> or to reduce the time step.
Cubic interpolation of f (λ) Two different strategies in order to determine λ have been implemented. The original one published in [6] which uses a cubic interpolation of f (λ) will be used if
algorithm, cubic was specified in the input file. In order to avoid too small increments δx, a value forlambda_factor_min can be specified.
λn+1 ≥ lambda_factor_min λn(4.2)

Multiplication by a constant factor Also a simple algorithm, which multiplies λ by the constantfactor lambda_factor_min at each line search iteration, can be used if algorithm, factor is specified
in the input file.
The condition for backtracking

According to [6] the line search is completed iff< fprev + alpha s

(4.3)

T

s = (∇f ) J −1 F = −F T F < 0 : the initial slope of decrease of f is the projection of the gradient ∇f
to the Newton direction δx.
∇f = −J T F : the gradient of f
fprev : the value of f at the previous iteration
If line search is not successful If λ becomes excessively small during line search, the solution
might be too close to the prediction for x. In that case the solver will bail out unless abort at lambda min, no
has been specified.
How to avoid excessively slow convergence In order to avoid too small increments δx, the minimum value for λ can be specified by lambda_min, or tolerance_x can be increased. In this case a reduction of the residual at each iteration is no longer guaranteed. For that reason abort at lambda min, no
should be specified and factor in divergence check should be increased.
By default also a relative test for λ according to equation 4.4 will be used unless lambda min, <lambda_min>,relative, no has been specified.

101

λ ≥
tλ

=





tolerance_x
max lambda_min, min
,1
tλ
#
"

n
J −1 F imaxmax (|xi | , |ẋi | , 1)



(4.4)

i=1

Equation 4.4 was adapted from [6]. If one wishes only the relative test, lambda_min = 0 should bespecified.
How to avoid too large increments In order to avoid too large increments δx, a scale factor γ
has been introduced in [6].



p
,1
(4.5)
γ = max min_step_scale, min||J −1 F ||pp = max_step_size max
xT x + ẋT ẋ, nδx=γ λ J −1 F

n The dimension of x
p The maximum step size
By specifying smaller values for max_step_size one can force the solver to search in the proximityof the prediction for x. However the rate of convergence could be reduced in that way.
Solver diagnostic Like for other nonlinear solvers, the convergence can be printed to the standard
output by means of a output: iterations statement in the initial value section. Moreover this solver
prints also the line search history if print convergence info, yes was specified. This could be helpful
in order to decide whether to increase or decrease lambda_min or the maximum number of iterations. If
one wants detailed information about the decisions of the solver, verbose, yes should be specified.
General notes If one specifies abort at lambda min, no, scale newton step, no, divergence check, noand lambda_min = 1, one gets the same behavior like Newton Raphson. Moreover if lambda_min < 1
and algorithm, factor was specified, the behavior will be similar to a damped Newton method.
Matrix free. Author: Giuseppe Quaranta<nonlinear_solver_name> ::= matrix free<nonlinear_solver_data> ::= { bicgstab | gmres }[ , tolerance , <tolerance> ][ , steps , <steps> ][ , tau , <tau> ][ , eta , <eta> ][ , preconditioner ,{ full jacobian matrix [ , steps , <steps> ][ , honor element requests ] } ];102

where tolerance is the iterative linear solver tolerance; steps is the maximum number of linear solver
iterations; tau is a measure of the configuration perturbation used to obtain a matrix-free approximation of the product of the Jacobian matrix times the solution vector; it is seldom necessary to change
the default value of this parameter, mainly for very “stiff” problems. By setting eta the convergencerequirements are changed; further reference for this parameter may be found in [7]; do not change it
unless you know what you are doing. The value steps of the steps keyword of the preconditioner
sub-block sets the maximum number of iterations that can be performed without requiring an updateof the preconditioner; this parameter can heavily influence the performance of the matrix-free solver. If
the option honor element requests is selected, the preconditioner is updated also when an elementchanges the structure of its equations. The default behavior is to ignore such requests2. This nonlinear
solver is experimental.
Eigenanalysis<card> ::= eigenanalysis :{ <when> | list , <num_times> , <when> [ , ... ] }[ , { suffix width , { compute | <width> }| suffix format , " <format> "| output [ full ] matrices| output sparse matrices| output eigenvectors| output geometry| matrix output precision, <matrix_precision>,| results output precision, <results_precision>,| parameter , <param>| lower frequency limit , <lower>| upper frequency limit , <upper>| <method> }[ , ... ] ]<method> ::={ use lapack [ , balance , { no | scale | permute | all } ]| use arpack , <nev> , <ncv> , <tol>| use jdqz , <nev> , <ncv> , <tol> }Performs the direct eigenanalysis of the problem. This functionality is experimental; see [8] for theoreticalaspects. Direct eigenanalysis based on the matrices of the system only makes sense when the system isin a steady configuration, so the user needs to ensure this configuration has been reached. Moreover, notall elements currently contribute to the Jacobian matrix of the system, so YMMV. In case of rotating
systems, a steady configuration could be reached when the model is expressed in a relative reference
frame, using the rigid body kinematics card (see Section 5.2.15).
• when indicates at what time the eigenanalysis is performed. The analysis is performed at thefirst time step for which Time ≥ when. If the keyword list is given, num_times values of whenare expected. At most num_times eigenanalyses are performed; the output file name is composedusing the position of the corresponding when in the array of times; if when < initial_time thefirst eigenanalysis is performed before the “derivatives” phase; if when = initial_time the first
eigenanalysis is performed after the “derivatives” phase and before the first regular step;• width is the width of the field that contains the eigenanalysis number in the related output file
2 See note above103

name; the resulting number is prefixed with zeros; when compute is used, the width is set in orderto accommodate the largest number;• format is the format that is going to be used; it must contain exactly one format specification for
an integer; for example, to have zero-prefixed, three digit file names, use "%03d";• param is the value of the coefficient that is used to project the problem in the discrete time domain; it
represents a singularity point in the transformation from the discrete to the continuous eigenvalues,
so it should not coincide with an eigenvalue of the problem; by default it is 1.0;
• output full matrices causes the output of the (full) problem matrices in a .m file, intended to
be loaded by tools like Octave/Matlab. If NetCDF output is enabled with the related card (seeSection 5.2.9), the matrices along with the eigenanalysis parameters are written in an .nc file as
described in Section C.1.5;• output sparse matrices causes the output of the problem matrices in sparse form in a .m file,intended to be loaded by tools like Octave/Matlab, and in the NetCDF .nc file as described in
Section C.1.5, if NetCDF output is enabled;• output eigenvectors causes the output of the eigenvalues and of the eigenvectors in a .m file,intended to be loaded by tools like Octave/Matlab, and/or in the NetCDF .nc file as described in
Section C.1.5, if NetCDF output is enabled;• output geometry causes the output of the reference configuration of structural nodes, if any, andof the indexes that need to be used in order to extract the perturbation of their position andorientation from the eigenvectors;• matrix output precision sets the precision for the text output of the problem matrices in the.m file to matrix_precision;• results output precision sets the precision for the text output of the eigenanalysis results in
the .m file to results_precision;• use lapack performs the eigenanalysis using LAPACK’s dggev() routine (generalized unsymmetric eigenanalysis using the QZ decomposition);• balance performs matrix permutation (permute), scaling (scale), both (all) using LAPACK’s
dggevx() routine, or none (no) using dggev(); by default, matrix permutation is performed, using
dggevx();• use arpack performs the eigenanalysis using ARPACK’s dnaupd() and dneupd() routines (canonical unsymmetric eigenanalysis, using the Implicitly Restarted Arnoldi Method, IRAM). It requires
the additional parameters:– nev, the number of the desired eigenvalues;– ncv, the number of the Arnoldi vectors;– tol, the tolerance (positive; zero means machine error).
• use jdqz performs the eigenanalysis using JDQZ (Jacobi-Davidson QZ decomposition). It requires
the same parameters of ARPACK; actually, it allows a lot of tuning, but its input is not formalizedyet (experimental).
• lower frequency limit only outputs those eigenvalues and eigenvectors that are complex andwhose imaginary part is larger than lower Hz;
104• upper frequency limit only outputs those eigenvalues and eigenvectors that are complex andwhose imaginary part is smaller than upper Hz;
The eigenanalysis functionality is experimental, so the syntax could need adjustments and change
across versions.
Note: in practical cases, the use of lapack with balance appeared to be quite sensitive to the problem
data. In some cases, the use of scale may introduce errors in eigenvalues. The use of permute is usually
beneficial: it allows to directly single out some of those spurious eigenvalues that correspond to constraint
equations.
Note: in practical cases, the usefulness of arpack appeared to be questionable, especially in thosecases where a significant amount of constraints is present. It may be beneficial in those cases where thenumber of deformable components is much larger than the number of constraint equations.
Output A brief summary of the eigenvalues is output in the .out file. Most of the information isdumped in a .m file in a format that is suitable for execution with scientific software like Octave andMatlab. The execution of the file populates the environment of those software with a set of variables
that contains the results of the eigenanalysis.
Binary output in NetCDF format, if supported, is written in the .nc file. Refer to Section 5.2.9 fordetails on how to activate NetCDF output and to Section C.1.5 for a complete description of the binary
output.
According to the options used in the eigenanalysis card, the .m file may contain:• Aplus: matrix J(+c) = f/ẋ + dCoef · f/x , either in full or sparse format;• Aminus: matrix J(−c) = f/ẋ − dCoef · f/x , either in full or sparse format;• dCoef: the coefficient used to build the matrices J(+c) and J(−c) ;• alpha: an array of three columns containing αr = alpha(:, 1), αi = alpha(:, 2) and β =alpha(:, 3), such that the k-th discrete-time eigenvalue Λk isΛk =αr (k) + iαi (k)
.
β(k)

(4.6)

Note that αr , αi and β can be all zero; only a fraction of the eigenvalues may be output; thecorresponding continuous time domain eigenvalue λk is
λk =1 Λk − 1
1 αr (k)2 + αi (k)2 − β(k)2 + i2αi (k)β(k),=2dCoef Λk + 1
dCoef(αr (k) + β(k)) + αi (k)2

(4.7)

where dCoef is defined in the .m file;• VR: the right eigenvectors, solution of the problem J(+c) + ΛJ(−c) VR = 0; only the eigenvectors
corresponding to the selected eigenvalues are output;
T• VL: the left eigenvectors, solution of the problem J(+c) + ΛJ(−c) VL = 0; only the eigenvectors
corresponding to the selected eigenvalues are output;• X0: a vector containing the reference position and orientation of the structural nodes, if any (excluding any dummy node); the vector contains, for each node, the three components of the reference
position and the three components of the Euler vector corresponding to the reference orientation;
all data are referred to the absolute reference frame;• idx: a vector containing the reference row index of each structural node in the eigenvectors;
The contents of this file may change across versions.
105

Example.
# to access the "x" component of each node of each eigenvector
octave:1> VR(idx + 1, :)# to plot the "y" component of each node of each eigenvector,# with respect to the reference "x" component of the position of the nodes
octave:2> plot(X0(1:6:end), VR(idx + 2, :))Abort After<card> ::= abort after :{ input| assembly| derivatives| dummy steps } ;mainly used to cleanly check models and simulations at various phases. When set to input, the simulationends after input is completed; when set to assembly, the simulation ends after initial assembly, if required;when set to derivatives, the simulation ends after the computation of the derivatives, i.e. after thesystem is solved at the initial time to compute initial momentum and momenta moment derivatives
and reaction forces; when set to dummy steps, the simulation ends after the dummy steps execution,
if required. In any case, the output is generated with the system configured as resulting from the lastcomputation phase, so this mode can be useful to check how the system is actually configured after
phases that are not usually output.
Linear Solver<card> ::= linear solver :{ naive | umfpack | klu | y12 | lapack | superlu | taucs | watson }[ , { map | cc | dir } ][ , { colamd | mmdata } ][ , { mt | multithread } , <threads> ][ , workspace size , <workspace_size> ][ , pivot factor , <pivot_factor> ][ , drop tolerance , <drop_tolerance> ][ , block size , <block_size> ][ , scale , { no | always | once | max | sum } ];Umfpack. The default, when available, is umfpack. Since it dynamically allocates memory as required,
the workspace size parameter is ignored. The umfpack linear solver honors the block size keyword,
which refers to an internal parameter. The default value (32) is usually good for most problems; however,it has been observed that a lower value can slightly improve performances on small problems (e.g. a rigid
rotorcraft model with some 180 degrees of freedom showed a 10% speedup with a block size of 4, while arigid robot showed even higher speedups, of the order of 30%, with a block size between 4 and 16). With
respect to scaling, the scale option supports max and sum which respectively scale the matrix according
to each row’s largest absolute value and to the sum of the absolute values of the coefficients in the row(the latter is the default), and always and once which scale the matrix according to Lapack’s dgeequ(3)algorithm respectively all times or with factors computed the first time the matrix is factored.

106

Naive. The naive solver is built-in, so it is always present. When umfpack is not available, it is usedby default. The naive solver uses a full storage but keeps track of the non-zeros. This allows a very
efficient solution of sparse matrices, with a O(1) access cost to the coefficients. It ignores the workspace
size parameter. See [9] for details.
Important note: the naive solver should always be used with some reordering option. The
colamd option is always available (see discussion below), since it is built-in. Other options areexperimental, and should be used with care. If this option is not used, the factorization may not
be robust. If the linear solver statement is not used, and the naive solver is used by default(because no other solver with higher priority is present), no reordering option is set bydefault. In this case, it is safe to explicitly force the linear solver with a valid reordering
option. For example
linear solver: naive, colamd;
The Naive solver supports matrix scaling using Lapack’s dgeequ’s function. Scaling may occur always,
i.e. for each factorization, or once, thus preserving the scaling factors resulting from the analysis of thefirst matrix that is factored.
KLU. The klu solver is provided by University of Florida’s SparseSuite. It is very efficient (usuallyfaster than umfpack), but it should be used with care, because in the current implementation, to exploit
its efficiency, the symbolic factorization is reused across factorizations. Whenever the solver realizes thatthe symbolic factorization needs to be regenerated, because the structure of the matrix changed (e.g.
when using driven elements, but not only in that case), the matrix is already invalidated, and should
be regenerated. This is not handled correctly yet. Matrix scaling can be performed always or once
according to Lapack’s dgeequ(3) algorithm respectively all times or with factors computed the first timethe matrix is factored
Y12. The y12 linear solver is provided for historical reasons and should not be used for practical
purposes. It requires static allocation of the workspace; the optimal size workspace_size is between 3
and 5 times the number of nonzero coefficients of the sparse matrix. By default, twice the size of thefull matrix is allocated (which sounds a bit nonsense, but is conservative enough); then the linear solver
automatically uses an optimal amount of memory based on the results of the previous factorization; this
could result in a failure if the filling of the matrix changes dramatically between two factorizations.
Lapack. The lapack linear solver uses LAPACK’s dgetrf() and dgetrs() functions with a dense
storage, and thus ignores the workspace size parameter. It is fairly inefficient for most practical applications, when compared to sparse solvers, except when problems are very small (less than 60 equations)and very dense.
SuperLU. Finally, superlu is an experimental linear solver that is able to perform the factorization
in a multi-threaded environment. If more than one CPU is available, it automatically uses all the CPUs;
the keyword mt allows to enforce the desired number of threads. See also the threads keyword for moredetails on multi-threaded solution.
Other. Historically, MBDyn supported the meschach and harwell solvers. They are now deprecatedand undocumented. Other linear solvers may be supported for experimental reasons (for example, taucs,
watson); however, they are not documented as they are not intended for general use.

107

Miscellaneous keywords. The keywords map (Sparse Map), cc (Column Compressed) and dir (Direct Access) can be used to modify the way the sparse matrix is handled:• map uses an array of binary trees to store the matrix coefficients; right before the factorization, thematrix is transformed in the form required by each linear solver, usually Column Compressed (alsoknown as Harwell-Boeing format) or Index (as used by y12). The matrix is regenerated each time
an assembly is required.
• cc uses the compact format resulting from the transformation required by the linear solver to store
the coefficients in subsequent assemblies, thus saving the time required to transform the matrix. If
the profile of the matrix changes, the compact form is invalidated, and the matrix is reset to map
form. As a consequence, this matrix form allows faster access and reduced factorization cost, but
in certain cases may require an additional cost.
• dir uses a full index table to grant direct access time to the actual location of each coefficient.
In principle it should be a bit faster than cc, at the cost of some memory waste. However, inpractical applications, the cost of these operations is a very small fraction of the factorization
time. If the problem is quite large, the memory consumption might become unacceptable; if the
problem is quite small, the access time of cc is quite limited (log2 (<nz>), where nz is the numberof non-zeroes in a column) so it is definitely comparable to that of cc.
Only umfpack, klu, y12 and superlu linear solvers allow these settings.
The keyword colamd is honored by the naive and SuperLU linear solvers; it enables the column
rearrangement that minimizes the sparsity of the factored matrix, as implemented in libcolamd (partof University of Florida’s SparseSuite package). The keyword mmdata is honored by the scalar SuperLU
linear solver only; it enables column rearrangement based on the MMD ordering of the symmetric matrix
AT A.
The pivot_factor is a real number, which in a heuristic sense can be regarded as the threshold forthe ratio between two coefficients below which they are switched, so 0.0 means no pivoting, while 1.0
means switch as soon as the norm of the ratio is less than unity.
The keyword drop tolerance enables incomplete factorization. Elements of the factorization whose
absolute value is below the drop_tolerance threshold are discarded. By default it is 0. Only umfpack
allows this setting.
The keyword block size is specific to umfpack. See the related documentation for the meaning.
The keyword scale indicates whether the matrix and the right-hand side must be scaled before linear
solution. By default no scaling takes place (no). Only naive allows this setting. It is experimental; itshould only be used for development purposes.
Table 4.1 summarizes the properties that can be set for each type of linear solver; Table 4.2 summarizes
the memory usage of the linear solvers; Table 4.3 summarizes how each linear solver deals with pivoting
policies.
SolverDeprecated; see linear solver (Section 4.1.1).
Threads<card> ::= threads :{ auto | disable | [ { assembly | solver } , ] <threads> }By default, if enabled at compile time, the assembly is performed in a multi-threaded environment if morethan one CPU is available and the selected solver allows it (e.g. if it supports any form of compressed108

Solver

Map

Naive
Umfpack
KLU
Y12m
LapackSuperLU
TAUCS
Watson√√√Table 4.1: Linear solvers properties
Column Dir
Multi- Worksp.
Compr.
Thread
Size
√
( )
√
√
√
√

√
√

√

√

√

√

?
√

?
√

?
√

?
√

√

?

Pivot
Factor
√
√
√
√
√
√

Block
Size

?
√

Table 4.2: Linear solvers memory usage
SolverWorkspace
Memory Block Size
Size
Allocation
Naive
full
Umfpack
dynamic
default=32
KLU
dynamic
Y12m
default=2 × n2 static
3nz → 5nz
Lapackfull
SuperLU
dynamic
TAUCS?
Watsondynamic

SolverNaive
Umfpack
KLU
Y12m
LapackSuperLU
TAUCS
WatsonTable 4.3: Linear solvers pivot handling
Pivot
Default Description
1.0→0.0
1.e−8
0.0→1.0
0.1
0.0→1.0
0.1
boolean: none=0.0, full=1.0 full
1.0→0.0
0.0→1.0
1.0

109

√

√

matrix handling, cc or dir). However, this behavior can be influenced by the threads directive. The
value auto is the default; the value disable reverts to the usual scalar behavior; otherwise threads,
the desired number of threads, is read and used. If it is prefixed by the keyword assembly, the desired
number of threads is used only in assembly; if it is prefixed by the keyword solver, the desired number of
threads is used only during factorization/solution, if the linear solver supports it (currently, only naive
and superlu solvers do). As an example, on a 4 CPU architecture, to use 2 threads for assembly and 4
threads for solution, use
threads: assembly, 2;
solver: superlu, cc, mt, 4;

4.1.2

Derivatives Data

Data related to the ‘derivatives’ phase. Right after the initial assembly and before the simulation starts,
the so-called derivatives solution is performed. The system is solved with the kinematic unknowns
constrained, in order to properly determine the dynamic unknowns, namely momenta and constraint
reactions. For this purpose, the coefficient that relates the state perturbation to the derivative perturbation must be set to a value that is small enough to allow the determination of accurate derivatives withvery small change in the states. This coefficient should be zero, but this leads to matrix singularity, so
it must be chosen by the user, since it is highly problem dependent. A rule-of-thumb is: if the system
has small stiffness and high inertia, the coefficient can be big, if the system has high stiffness and small
inertia, the coefficient must be small.
The derivatives solution is always performed and cannot be disabled. If for any reason it does notconverge, to practically disable it one can set a very large tolerance. Subsequent time steps may startwith a less than ideal initialization, resulting in a rough transient.
Derivatives Tolerance<card> ::= derivatives tolerance : <tolerance> ;Derivatives Max Iterations<card> ::= derivatives max iterations : <max_iterations> ;Derivatives Coefficient<card> ::= derivatives coefficient : <coefficient>| [ <coefficient> , ] auto
[ , max iterations , <max_iterations> ][ , factor , <factor> ]
;

4.1.3

Dummy Steps Data

Data related to the ‘dummy steps’ phase. The dummy steps are intended as a sort of numerical computation of the second order derivatives of the constraint equations. The displacement constraint equationsin an index three Differential-Algebraic Equations system (DAE) represent the second derivative effect of
the constraints on the kinematic unknowns. Thus, to ensure the proper initial conditions, the constraint
equations should be differentiated twice. To simplify the code, those equations have been differentiatedonce only, in the initial assembly, the second derivation being performed numerically by the dummy steps.
During these steps the system converges to a solution whose error from the sought solution is bounded.

110For this reason, the dummy steps should be performed with a very short time step, to seek accuracy,
and with a high numerical damping, to cancel as quickly as possible the high frequency numerical noise.
Note: no step change, modified Newton-Raphson and so on is allowed during the dummy steps.
Note: in most practical applications, dummy steps should not be used.
Dummy Steps Tolerance<card> ::= dummy steps tolerance : <tolerance> ;Dummy Steps Max Iterations<card> ::= dummy steps max iterations : <max iterations> ;Dummy Steps Number<card> ::= dummy steps number : <number> ;number of dummy steps.
Dummy Steps Ratio<card> ::= dummy steps ratio : <ratio> ;ratio of the time step to be used in the dummy steps to the regular time step.
Dummy Steps Method<card> ::= dummy steps method : <method_data> ;Same as for the normal simulation method.

4.1.4

Output Data

Model output, e.g. nodes and elements output, is handled by the data manager in the control data
block; the solver only deals with simulation-related output, and takes care of some debug output.
OutputThis command requests special output related to the solution phase.
<card> ::= output : <item> [ , ... ] ;<item> ::={ iterations| residual| solution| jacobian matrix| messages| counter| bailout| matrix condition number| solver condition number| cpu time
| none }111

The keyword counter logs on the standard output a string that summarizes the statistics of the time
step just completed. By default it is off; the same information, by default, is logged in the .out file. The
keyword iterations logs on stdout a detailed output of the error at each iteration inside a time step.
The keywords residual, solution and jacobian matrix log to stdout the residual, the solution and
the Jacobian matrix; they are mainly intended for last resort debugging purposes, as the output can be
extremely verbose. The item messages refers to all messaging on the .out file; by default, it is on. The
special item bailout instructs the solver to output the residual (as with residual) only in case of noconvergence, before bailing out. The special item none clears the output flags; the items are additive,
so, for instance, to clear out the default and add the iterations output, use:
output: none, iterations;
Output meter
This command conditions the output selected by the output command to a meter, expressed in termsof a drive caller. Only when the drive caller returns true (!0), the output occurs.
<card> ::= output meter : (DriveCaller) <when> ;4.1.5

Real-Time Execution

Initially implemented by Michele Attolico
Extensively reworked by Pierangelo Masarati
This statement forces MBDyn to be scheduled in real-time, based on the capabilities of the underlyingOS.
<card> ::= real time : [ { RTAI | POSIX } , ]<mode>[ , reserve stack , <stack_size> ][ , allow nonroot ][ , cpu map , <cpu-map> ][ , output , { yes | no } ][ , hard real time ][ , real time log [ , file name , <command_name> ] ]<mode> ::={ [ mode , period , ] time step , <time_step>| mode , semaphore [ , <semaphore_args> ]| mode , IO }where:• the optional RTAI or POSIX keywords indicate whether RTAI (Linux Real-Time Application Interface, http://www.rtai.org/) or POSIX should be used to schedule the execution of MBDyn inreal-time (defaults to RTAI);• when the keyword mode is set to period, the execution is scheduled periodically; when mode is set
to semaphore, the execution waits for an external trigger to start a new step; when mode is set
to IO, the execution assumes synchronization to be provided by waiting on blocking I/O streams(note: semaphore is not implemented yet, so semaphore_args is currently undefined; the default
mode is period);112

• the time_step, required when scheduling is periodic, is the sample rate in nanoseconds (ns);usually, it matches the time step of the simulation, but it can be different for other purposes;• allow nonroot means that the program should be allowed to run as a regular (non-root) user
while performing hard real-time operations with the underlying OS (by default, only the superuser
is allowed to execute in real-time, since this requires the process to acquire the highest priority;
only honored by RTAI);• the keyword reserve stack instructs the program to statically reserve the desired stack size bymeans of the mlockall(2) system call; it should be used to ensure that no page swapping occurs
during the real-time simulation; a minimal default value (1024 bytes) is set in any case;• the keyword cpu map allows the program to force its execution on a specific subset of CPUs on
multiprocessor hardware; the syntax of the cpu_map field is a byte-sized integer (between 0 and255) whose active bits are the desired CPUs (up to 8);• the keyword output determines whether output is entirely disabled or not; this option is only
available to POSIX real-time, and should always be set to no in order to disable any output, so that
I/O only occurs for the purpose of interprocess communication;• the keyword hard real time instructs the program to run in hard real-time; the default is soft
real-time (RTAI only; by default scheduling is in soft real-time);• the keyword real time log enables logging by means of RTAI mailboxes; an optional file nameargument allows to set the command_name of the logging process that is used. It should be a low
priority soft real-time process that communicates with the simulator by means of the RTAI mailbox
called logmb. The log process mailbox may receive a sequence of message consisting in two integers:
the time step number and the amount of nanoseconds that time step overrun the scheduling period.
Note: if no command_name is given, to guarantee the detection of the default log command theprocess PATH environment variable is augmented by prepending ".:BINPATH"; by default, BINPATH
is the ${bindir} directory of the build environment, so it can be set by using the --bindirconfigure switch.
The keywords must be given in the sequence reported above. Real-time simulation is mostly uselesswithout interaction with external programs. The input is dealt with by the stream file drivers describedin Sections 7.1.4 and 7.1.5. The output is dealt with by the stream output elements described in Sections 8.16.1, 8.16.2, and 8.16.3.

4.2

Other Problems

Other types of problems are either possible or being developed. Typically, static problems can be obtainedin terms of a downgrading of the initial value problem, by eliminating time-dependent interactions andtreating time as an ordering parameter.
A special problem that is currently under development is inverse dynamics.

113

Chapter 5

Control Data
This section is read by the manager of all the bulk simulation data, namely the nodes, the drivers andthe elements. It is used to set some global parameters closely related to the behavior of these entities,
to tailor the initial assembly of the joints in case of structural simulations, and to tell the data manager
how many entities of every type it should expect from the following sections. Historically this is due tothe fact that the data structure for nodes and elements is allocated at the beginning with fixed size. Thisis going to change, giving raise to a “free” and resizeable structure. But this practice is to be considered
reliable since it allows a sort of double-check on the entities that are inserted.

5.1

Assembly-Related Cards

The initial assembly related cards are:

5.1.1

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 morethan a simple compliance test; it represents a static preprocessor for models. See the directives use in
Section 5.1.2 and initial stiffness in Section 5.1.3 for more details on performing appropriate initial
joint assembly.

5.1.2

Use

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

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 backward compatibility.

5.1.3

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 structuralnodes during the initial assembly; the default is 1.0 for both. Note that each node can use a specificvalue; see Section 6.1 for details.
Note that the same value is used for the position and the orientation, so this stiffness is dimensionallyinconsistent; It should really be intended as a penalty coefficient. The same considerations apply to thepenalty value for linear and angular velocities.

5.1.4

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.

5.1.5

Tolerance<card> ::= tolerance : <tolerance> ;The tolerance that applies to the initial joint assembly; this tolerance is used to test the norm 2 of theresidual, 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.

5.1.6

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.

5.2

General-Purpose Cards

5.2.1

Title

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

5.2.2

Print

<card> ::= print : <item> [ , ... ] ;<item> ::={ dof stats| [ { dof | equation } ] description115

| [ { element | node } ] connection| all| none }• The keyword dof stats enables printing of all potential dof owner entities at initial assembly andat 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 toprint: dof stats, dof description;
while the statement
print: none;
disables all.

5.2.3

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.
Note: the make restart file statement is experimental and essentially abandoned.

5.2.4

Select Timeout<card> ::= select timeout , { forever | <timeout> } ;exit after timeout minutes when waiting for connections on stream drives or stream output elements.
By default, no timeout is used, so select(2) waits forever.

1165.2.5

Default Output<card> ::= default output : <output_list> ;<output_list> ::= { all | none | <output_item> } [ , ... ]<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 (see Section 6.6.1) and elements (see Section 8.17.4). 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 (see Section 6.1) for details.
Since values are additive, except for none, to select only specific entities use none first, followed by a listof the entities whose output should be activated.
Example.
begin: control data;# ...
# disable all except structural nodes
default output: none, structural nodes;# ...
end: control data;1175.2.6

Output Frequency

This statement is intended for producing partial output.
<card> ::= output frequency : <steps> ;Despite the perhaps 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.2.7).

5.2.7

Output Meter

A drive that causes output to be generated when different from zero, while no output is created whenequal to zero. It is useful to reduce the size of the output file during analysis phases that are not ofinterest.
<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;
When integrating with variable time step, one may want to use the closest next DriveCaller (seeSection 2.6.2); for example,
output meter: closest next, 2., forever, const, 0.01;
causes output to occur at times greater than or equal to multiples of 0.01 s, starting at 2 s.

5.2.8

Output Precision

Sets the desired output precision for those file types that honor it (currently, all the native output except
the .out file). The default is 6 digits; since the output is in formatted plain text, the higher the 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.

5.2.9

Output Results

This deprecated statement was intended for producing output in formats compatible with other software.
See Appendix D for a description of the types of output that MBDyn can provide. Most of them areproduced in form of post-processing, 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 [ , sync ] [ , no text ] ;If the optional keyword no text is present, standard output in ASCII form is disabled.

118

5.2.10

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 enabledifferent formats:<card> ::= default orientation : <orientation_type> ;<orientation_type> ::={ 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 theprevious 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 fully honored throughout the code, yet. Right now, only structuralnodes and selected elements 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, inthe .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.

5.2.11

Default Aerodynamic Output

This statement is used to select the default output of built-in aerodynamic elements.
<card> ::= default aerodynamic output :<custom_output_flag> [ , ... ] ;<custom_output_flag> ::={ position| orientation [ , <orientation_description> ]| velocity| angular velocity| configuration # ::= position, orientation, velocity, angular velocity| force119

| moment| forces| all }

# ::= force, moment# equivalent to all the above<orientation_description> ::= orientation description , <orientation_type>The orientation_type is defined in Section 5.2.10.
Flags add up to form the default aerodynamic element output request. Flags may not be repeated.
Output occurs for each integration point. The kinematics refers to location, orientation, and linear
and angular velocity of the reference point. The forces are actual forces and moments contributing to
the equilibrium of a specific node. By default, only force and moment are output. The custom output isonly available in NetCDF format; see Section C.1.4.

5.2.12

Default Beam Output

This statement is used to select the default output of beam elements.
<card> ::= default beam output : <custom_output_flag> [ , ... ] ;<custom_output_flag> ::={ position| orientation [ , <orientation_description> ]| configuration# ::= position, orientation| force| moment| forces# ::= force, moment| linear strain| angular strain| strains# ::= linear strain, angular strain| linear strain rate
| angular strain rate
| strain rates# ::= linear strain rate, angular strain rate
| all }# equivalent to all the above<orientation_description> ::= orientation description ,<orientation_type>The orientation_type is defined in Section 5.2.10.
Flags add up to form the default beam output request. Flags may not be repeated. Output refers
to the beam’s “evaluation points”. Strain rates are only available from viscoelastic beams; even if set,
elastic beams will not output them.
By default, only forces are output, to preserve compatibility with the original output format. The
custom output is only available in NetCDF format; see Section C.1.4.

5.2.13

Default Scale<card> ::= default scale : <scale_list> ;<scale_list> ::= <scale_pair> [ , <output_list> ]<scale_pair> ::= { all | none | <scale_item> } , <scale_factor>
120

<scale_item> ::={ abstract nodes| electric nodes| hydraulic nodes| structural nodes| thermal nodes }Define the residual scaling factor for all dof owners, or for specific types of dof owners. In principle, all
dof owners should allow to define a scale factor, since they define a set of equations. In practice, only
the above listed types support this option.
Residual scaling is only active when specifically requested by the related option for the tolerance
keyword in the problem-specific section. See Section 4.1.1 for further details.

5.2.14Model<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 beconsidered as forcing terms. See the structural node (Section 6.1) for details.

5.2.15

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 , (TplDriveCaller<Vec3>) <abs_position> ][ , orientation , (TplDriveCaller<Vec3>) <abs_orientation_vector> ][ , velocity , (TplDriveCaller<Vec3>) <abs_velocity> ][ , angular velocity , (TplDriveCaller<Vec3>) <abs_angular_velocity> ][ , acceleration , (TplDriveCaller<Vec3>) <abs_acceleration> ][ , angular acceleration , (TplDriveCaller<Vec3>) <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 anddeformable 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 in121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.

5.2.16

Loadable path<card> ::= loadable path : [ { set | add } , ] " <path> " ;This card allows to either set (optional keyword set) or augment (optional keyword add) the search pathfor 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 user defined or loadable
elements (Section 8.15. See for example the module load statement in Section 2.4.6.

5.3

Model Counter Cards

The following counters can be defined:

5.3.1

Nodes

• abstract nodes• electric nodes• hydraulic nodes• parameter nodes• structural nodes• thermal nodes

5.3.2

Drivers• file drivers

5.3.3

Elements• aerodynamic elements• aeromodals• air properties• automatic structural elements• beams• bulk elements• electric bulk elements122• electric elements• external elements• forces• genels• gravity• hydraulic elements• joints• loadable elements• output elements• rigid bodies• induced velocity elements

123

Chapter 6

Nodes
The nodes section is enclosed in the cards:
begin : nodes ;# ...
end : nodes ;Every node card has the format:<card> ::= <node_type> : <node_label><additional_args>[ , scale , { default | <scale> } ][ , output , { yes | no | (bool)<output_flag> } ][ , <extra_arglist> ] ;where node_type is one of the following:• abstract• electric• hydraulic• parameter• structural• thermal
The data manager reads the node type and the label and checks for duplication. If the node is notdefined yet, the appropriate read function is called, which parses the rest of the card and constructs thenode.
The optional scale keyword is only supported by• abstract• electric• hydraulic• structural• thermal

nodes. See Section 5.2.13 for further details.
124

6.1

Structural Node

Structural nodes can have 6 degrees of freedom (position and orientation), and thus describe the kinematics of rigid-body motion in space, or 3 degrees of freedom (position) and thus describe the kinematics
of point mass motion in space.
The former has been originally implemented in MBDyn; the latter has been added in MBDyn 1.5.0,
mainly to support the implementation of membrane elements.
The 6 dof structural node can be static, dynamic, modal or dummy.
The 3 dof structural node can be static or dynamic.
Elements that only require displacement can be connected to either type of nodes; when connected
to a 6 degree of freedom node, they only make use of position/velocity and only contribute to force
equilibrium equations.
Elements that require both displacement and orientation can only be connected to 6 degree of freedom
nodes.

6.1.1

Static NodeThe static keyword means no inertia is related to that node, so it must be appropriately constrained
or attached to elastic elements. Static nodes are useful when there is no need to apply inertia to them,thus saving 6 degrees of freedom.

6.1.2

Dynamic Node

The dynamic keyword means inertia can be attached to the node, so it provides linear and angularmomenta degrees of freedom, and automatically generates the so-called automatic structural elements.

6.1.3

Modal NodeThe modal node is basically a regular dynamic node that must be used to describe the rigid reference
motion of a modal joint. See Section 8.12.31 for further details.

6.1.4

SyntaxThe syntax of the 6 degrees of freedom rigid-body motion structural node is<additional_args> ::= , { static | dynamic | modal } ,[ position , ](Vec3)<absolute_position> ,[ orientation , ](OrientationMatrix) <absolute_orientation_matrix> ,[ orientation description , <orientation_description> , ][ velocity , ](Vec3)<absolute_velocity> ,<absolute_angular_velocity>[ angular velocity , ] (Vec3)[ , assembly, (real) <position_initial_stiffness>, (real) <velocity_initial_stiffness>, { yes | no | (bool) <omega_rotates?> } ]<orientation_description> ::={ euler123 | euler313 | euler321| orientation vector | orientation matrix }The syntax of the 3 degrees of freedom point mass motion structural node is125

<additional_args> ::= , { static displacement | dynamic displacement } ,[ position , ] (Vec3) <absolute_position> ,[ velocity , ] (Vec3) <absolute_velocity> ,[ , assembly, (real) <position_initial_stiffness>, (real) <velocity_initial_stiffness> ]The stiffness parameters and the omega_rotates? flag override the default values optionally set by
the initial stiffness and omega rotates keywords in the control data block. They are optional,
but they must be supplied all together if at least one is to be input.
The omega_rotates? parameter determines whether the initial angular velocity should follow or not
the node as it is rotated by the initial assembly procedure. It can take values yes or no; a numericalvalue of 0 (no) or 1 (yes) is supported for backward compatibility, but its use is deprecated.
The dynamic and the modal node types allow the optional output keyword accelerations after the
standard node output parameters:<extra_arglist> ::= accelerations , { yes | no | (bool) <value> }to enable/disable the output of the linear and angular accelerations of the node. Since they are computed
as a postprocessing, they are not required by the regular analysis, so they should be enabled only whenstrictly required.
Also note that accelerations may be inaccurate, since they are reconstructed from the momentum
and the momenta moment derivatives through the inertia properties associated to dynamic nodes.
The keyword accelerations can be used for dummy nodes; however, the dummy node will computeand output the linear and angular accelerations only if the node it is connected to can provide them.
Accelerations output can be controlled by means of the default output statement (see Section 5.2.5).
If the static model type is used in the control data block, all dynamic structural nodes are actuallytreated as static. This is a shortcut to ease running static analyses without the need to modify eachnode of a dynamic model.

6.1.5

Dummy Node

The dummy structural node has been added to ease the visualization of the kinematics of arbitrary pointsof the system during the simulation. It does not provide any degrees of freedom, and it must be attached
to another node.
Two dummy structural node types are available.
<additional_args> ::= , dummy , <base_node_label> , <type> , <dummy_node_data>
Dummy nodes take the label base_node_label of the node they are attached to, followed by type,
the type of dummy node, possibly followed by specific data, dummy_node_data. The following types areavailable:• offset:<type> ::= offset<dummy_node_data> ::=(Vec3)<relative_offset> ,(OrientationMatrix) <relative_orientation_matrix>[ , orientation description , <orientation_description> ]It outputs the configuration of a point offset from the base node.
126• relative frame:<type> ::= relative frame<dummy_node_data> ::= <reference_node_label>[ , position , (Vec3) <reference_offset> ][ , orientation , (OrientationMatrix) <reference_orientation_matrix> ][ orientation description , <orientation_description> , ][ , pivot node , <pivot_node_label>[ , position , (Vec3) <pivot_offset> ][ , orientation , (OrientationMatrix) <pivot_orientation_matrix> ] ]It outputs the configuration of the base node in the frame defined by the node of label reference_node_label,
optionally offset by reference_offset and with optional relative orientation reference_orientation_matrix.
If a pivot_node_label is given, the relative frame motion is transformed as if it were expressed in
the reference frame of the pivot node, optionally offset by pivot_offset and with optional relativeorientation pivot_orientation_matrix.
Example.
set: real Omega = 1.;
structural: 1, static, null, eye, null, 0.,0.,Omega;
structural: 1000, dummy, 1, offset, 1.,0.,0., eye;structural: 1001, dummy, 1, relative frame, 1000;
structural: 2000, dynamic,
0.,0.,1.,
1, 1.,0.,0., 2, 0.,0.,1.,
null,
null,
accelerations, yes;
Output. Structural nodes generate two kinds of output files:• the .mov file;• the .ine file.
The output of displacement-only 3 degree of freedom nodes is identical to that of 6 degree of freedom
nodes, with the meaningless fields filled with zeros.
The .mov Output File.
The first refers to the kinematics of the node; its extension is .mov, and for each time step it contains
one row for each node whose output is required. The rows contain:
1
2–4
5–7
8–10
11–13
14–16
17–19

the label of the node
the three components of the position of the node
the three Euler angles that define the orientation of the node
the three components of the velocity of the node
the three components of the angular velocity of the node
the three components of the linear acceleration of the dynamic and modal nodes (optional)
the three components of the angular acceleration of the dynamic and modal nodes (optional)

All the quantities are expressed in the global frame, except for the relative frame type of dummy node,
whose quantities are, by definition, in the relative frame.
127

There exist two variants of this output. The output of the orientation can be modified by requesting
either the three components of the Euler vector, or the nine components of the orientation matrix.
When the Euler vector is requested, columns 5 to 7 contain its components. Beware that it is notpossible to discriminate between the original output and this format without knowing what output typewas requested.
When the orientation matrix is requested, columns 5 to 13 contains the elements of the matrix,
written row-wise, that is: r11 , r12 , r13 , r21 , . . . , r33 . Note that in this case the total column count, if
accelerations are not requested, corresponds to that of a structural node with optional accelerations, so
it might be hard to discriminate as well.
This ambiguity is resolved when results are output in NetCDF format. See Section C.1.3 for details.
Note: actually, the angles denoted as “Euler angles” are the three angles that describe a rotation
made of a sequence of three steps: first, a rotation about global axis 1, followed by a rotation about axis
2 of the frame resulting from the previous rotation, concluded by a rotation about axis 3 of the frame
resulting from the two previous rotations. To consistently transform this set of parameters into someother representation, see the tools eu2rot(1), rot2eu(1), rot2eup(1), rot2phi(1). The functions thatcompute the relationship between an orientation matrix and the set of three angles and vice versa are
MatR2EulerAngles() and EulerAngles2MatR(), in matvec3.h.
The .ine Output File.
The second output file refers only to dynamic nodes, and contains their inertia; its extension is .ine.
For each time step, it contains information about the inertia of all the nodes whose output is required.
Notice that more than one inertia body can be attached to one node; the information in this file refers
to the sum of all the inertia related to the node.
The rows contain:
1
2–4
5–7
8–10
11–13

the label of the node
item the three components of the momentum in the absolute reference frame
item the three components of the momenta moment in the absolute reference frame, withrespect to the coordinates of the node, thus to a moving frame
the three components of the derivative of the momentum
the three components of the derivative of the momentum moment

Private Data.

The following data are available:

all structural nodes:
1. "X[1]" position in global direction 1
2. "X[2]" position in global direction 2
3. "X[3]" position in global direction 3
4. "x[1]" position in direction 1, in the reference frame of the node
5. "x[2]" position in direction 2, in the reference frame of the node
6. "x[3]" position in direction 3, in the reference frame of the node
7. "Phi[1]" orientation vector in global direction 1
8. "Phi[2]" orientation vector in global direction 2
9. "Phi[3]" orientation vector in global direction 3

128

10. "XP[1]" velocity in global direction 1
11. "XP[2]" velocity in global direction 2
12. "XP[3]" velocity in global direction 3
13. "xP[1]" velocity in direction 1, in the reference frame of the node
14. "xP[2]" velocity in direction 2, in the reference frame of the node
15. "xP[3]" velocity in direction 3, in the reference frame of the node
16. "Omega[1]" angular velocity in global direction 1
17. "Omega[2]" angular velocity in global direction 2
18. "Omega[3]" angular velocity in global direction 3
19. "omega[1]" angular velocity in direction 1, in the reference frame of the node
20. "omega[2]" angular velocity in direction 2, in the reference frame of the node
21. "omega[3]" angular velocity in direction 3, in the reference frame of the node
22. "E[1]" Cardan angle 1 (about global direction 1)
23. "E[2]" Cardan angle 2 (about local direction 2)
24. "E[3]" Cardan angle 3 (about local direction 3)
25. "E313[1]" Cardan angle 1 (about global direction 3)
26. "E313[2]" Cardan angle 2 (about local direction 1)
27. "E313[3]" Cardan angle 3 (about local direction 3)
28. "E321[1]" Cardan angle 1 (about global direction 3)
29. "E321[2]" Cardan angle 2 (about local direction 2)
30. "E321[3]" Cardan angle 3 (about local direction 1)
31. "PE[0]" Euler parameter 0
32. "PE[1]" Euler parameter 1
33. "PE[2]" Euler parameter 2
34. "PE[3]" Euler parameter 3
dynamic nodes only:
35. "XPP[1]" acceleration in global direction 1
36. "XPP[2]" acceleration in global direction 2
37. "XPP[3]" acceleration in global direction 3
38. "xPP[1]" acceleration in direction 1, in the reference frame of the node12939. "xPP[2]" acceleration in direction 2, in the reference frame of the node
40. "xPP[3]" acceleration in direction 3, in the reference frame of the node
41. "OmegaP[1]" angular acceleration in global direction 1
42. "OmegaP[2]" angular acceleration in global direction 2
43. "OmegaP[3]" angular acceleration in global direction 3
44. "omegaP[1]" angular acceleration in direction 1, in the reference frame of the node
45. "omegaP[2]" angular acceleration in direction 2, in the reference frame of the node
46. "omegaP[3]" angular acceleration in direction 3, in the reference frame of the nodeNote: Euler parameters actually do not take into account the whole orientation of a node, since
they are post-processed from the orientation matrix. As a consequence, they only parametrize theminimum norm orientation that yields the current orientation matrix of the node. The same applies tothe orientation vector ϕ.
Note: if accelerations are requested using the string form, their computation is enabled even if it
was not explicitly enabled when the node was instantiated. However, if the index form is used, their
computation must have already been explicitly enabled.
Note: dummy nodes based on dynamic nodes inherit the capability to provide access to linear andangular accelerations.

6.2

Electric Node<additional_args> ::= [ , value , <initial_value>[ , derivative , <derivative_initial_value> ] ]Note: the keywords value and derivative have been introduced recently; value is not mandatory,
resulting in a warning, while derivative is required. The same applies to the abstract node and tothe hydraulic node; the latter is an algebraic node, so only value is allowed.
Private Data.

The following data are available:

1. "x" value
2. "xP" derivative value

6.3

Abstract Node<additional_args> ::= , { algebraic | differential }[ , value , <initial_value>[ , derivative , <derivative_initial_value> ] ]Note: abstract nodes are ancestors of all scalar node types. Many genel and electric elements can beconnected to abstract nodes as well, since they directly use the ancestor class.

130

Output. The value of abstract nodes is output with file extension .abs; for each time step the outputof the required nodes is written. The format of each row is• the label of the node
• the value of the node
• the value of the node derivative, when differential (the default)
Private Data.

The following data are available:

1. "x" value
2. "xP" derivative value

6.4

Hydraulic NodeThe hydraulic node represents the pressure at a given location of a hydraulic circuit. It is derived fromthe generic scalar algebraic node; as a consequence, it can be connected to all elements that operate on
generic scalar nodes.
The syntax is<additional_args> ::= [ , value , <initial_value> ]Private Data.

The following data are available:

1. "x" value

6.5

Parameter NodeNOTE: parameter nodes are essentially obsolete; in most cases their purpose can be better fulfilled byelement and node drive callers.
<additional_args> ::= { [ , value , <initial_value> ]| , element| , sample and hold , (NodeDof) <signal> , <sample_time>| , beam strain gage , <y> , <z> }The parameter node is derived from the class scalar algebraic node, but it is used in a rather peculiar
way: it doesn’t own any degree of freedom, so it does not participate in the solution; it is rather used as asort of placeholder for those elements that require to be connected to a scalar node that is not otherwise
significant to the analysis. Thanks to the availability of the parameter node, these elements do notneed be reformulated with a grounded node, while the parameter node value can be changed during thesolution by several means, listed in the following.
Element. When the argument list starts with the keyword element, the parameter node expects tobe bound to an element, and to access bulk element data (see the bind statement, Section 8.17.1).
Sample and Hold. When the argument list starts with the keyword sample and hold, followed bya NodeDof specification and a sample time, the parameter node contains the value of the input signal,
namely the value of the node, for the duration of the sample_time. This may be useful to preserve thevalue of some signal across time steps.
131Beam Strain Gage. When the argument list starts with the keyword beam strain gage, followed by
the coordinates of a point on the section of a beam, the parameter node expects to be bound to a beam
element, and to access the measure of the axial strain at point x, y in the section plane as a combinationof section strains and curvatures:ε = νx + z · κ y − y · κ z ,
(6.1)
where
• νx is the axial strain of the beam;• κy is the bending curvature of the beam about the y axis;• κz is the bending curvature of the beam about the z axis.
The span-wise location of the point where the strain is evaluated is set in the bind statement (seeSection 8.17.1).
Note: measuring strains by means of derivatives of interpolated positions and orientations may leadto inaccurate results; force summation should be used instead.

6.6

Miscellaneous

6.6.1

OutputThere is an extra card, that is used to modify the output behavior of nodes:<card> ::= output : <node_type> , <node_list> ;<node_list> ::= { <node_label> [ , ... ]| range , <node_start_label> , <node_end_label> }node_type is a valid node type that can be read in the nodes block. In case the keyword range is used,
all nodes of that type with label between node_start_label and node_end_label are set.
Note: if a node should never (no) or always (yes) be output, its output flag should be set directly on
the node card. The global behavior of all the nodes of a type can be set from the control data block byadding the node type to the item list in the default output card. Then, the specific output flag of setsof nodes can be altered by means of the output card in the nodes block. This allows high flexibility inthe selection of the desired output. The same remarks apply to the output of the elements.
If node_type is structural, the optional keyword accelerations can be used right after thenode_type to enable the output of the accelerations.

132

Chapter 7

Drivers
The drivers section is enclosed by the cards:
begin : drivers ;# ...
end : drivers ;Every driver card has the format:<card> ::= <driver_type> : <arglist> ;At present the only type driver_type of drivers supported is file.

7.1

File Drivers

The file drivers are defined by the statement
file : <file_arglist> ;A comprehensive family of file drivers is available; their syntax is:<file_arglist> ::= <label> , <normal_arglist>
The following file drivers are supported:

7.1.1

Fixed Step

<normal_arglist> ::= fixed step ,{ count | <steps_number> } ,<columns_number> ,initial time , { from file | <initial_time> } ,time step , { from file | <time_step> } ,[ interpolation , { linear | const } , ][ { pad zeroes , { yes | no }| bailout , { none | upper | lower | any } } , ]" <file_name> "133

If the keyword count is used instead of the steps_number, the number of time records provided by thefile is obtained by counting the valid records.
If the keyword from file is used instead of either initial_time or time_step, the value is readfrom the file. In this case, comment lines of the form
# initial time: <initial_time># time step: <time_step>
are expected; the corresponding values are parsed and checked. A valid value provided in the input filealways overrides any corresponding value provided in the corresponding comment line.
The value at an arbitrary time is interpolated from the available data. If the requested value is out oftime bounds, zero is returned, unless pad zeroes is set to no, which means that the first or the last setof values is respectively used. As an alternative, if bailout is set to upper, lower or any, the simulationis stopped as soon as the time goes out of the respective ”time“ bounds.
If interpolation is linear (the default), a linear interpolation is used. Otherwise, if interpolationis const, the value at the beginning of the time step that includes the current time is used.
The file format is# an arbitrary number of comment lines starting with ‘#’## comment lines may provide special parameters# like "initial time", "time step" as indicated above; for example## initial time: 0# time step: 0.01#
# channel #1 channel #2 ... channel #n
1.
2.
... 100.
...
Example.
begin: drivers;
file: 100,
fixed step,100,# n. steps
1,# n. channels
0,# initial_time
0.01,# time_step"input.dat";
file: 200,
fixed step,
count,# n. steps
1,# n. channels
from file, # initial_time
from file, # time_step"input.dat";
end: drivers;134

7.1.2

Variable Step

<normal_arglist> ::= variable step ,<channels_number> ,[ interpolation , { linear | const } , ][ { pad zeroes , { yes | no }| bailout , { none | upper | lower | any } , } , ]" <file_name> "The same considerations of the fixed step type apply.
The file format is# an arbitrary number of lines starting with ‘#’## time channel#1 channel#2 ... channel#n0.
1.
2.
... 100.
0.01 1.2
1.8... 90.
...
The number of available records is computed as the number of non-comment lines (lines not starting witha hash mark ‘#’). The first column contains the time, while the remaining channels_number columns
contain the values of the input channels at that time. Time values must grow monotonically.

7.1.3

Socket<normal_arglist> ::= socket ,<columns_number> ,[ initial values , <value #1> , ... , ]{ local , " <file_name> "| [ port , <port_number> , ] (AuthenticationMethod) <authentication> }The driver binds to a socket listening on port port_number (defaults to 9011) or on the named pipe
file_name; at the beginning of each time step, in case of connection, the driver expects some input datain text format, consisting in an authentication token (if required). The authentication token is usuallyin the form
user: <user_name> NEWLINE
password: <user_password> NEWLINE
where NEWLINE is a literal ‘newline’ (i.e. ‘\n’). White-spaces may be significant in user_name, and surely
are in user_password.
The identification is followed by a label token, in the form
label: <label> NEWLINE
indicating the column being edited, followed by the desired changes; the connection is terminated by asingle mark followed by a newline:. NEWLINE
The permitted operations, at present, are:value: <value> NEWLINE
sets the value the drive will assume from the current step on135

inc: { yes | no } NEWLINE
tells whether to switch on or off the increment mode, resulting in subsequent value commands being“set” rather than “add”
imp: { yes | no } NEWLINE
tells whether to switch on or off the impulse mode; when on, subsequent value commands to be applied
for one step only. At present, impulse mode supersedes any incremental mode, namely the value of thedrive is reset to zero after one step. This behavior may change in the future.

7.1.4

RTAI Mailbox

This special drive is a variant of the Socket Stream (Section 7.1.5; under development yet) that reads
the input data from a RTAI mailbox in non-blocking mode. It is intended as a means of communication
between different processes running in real-time. The syntax is:<normal_arglist> ::= RTAI input ,stream drive name , " <stream_name> " ,[ create , { yes | no } , ][ host , " <host_name> " , ][ { [ non ] blocking } , [ ... ] ]<columns_number> ;where• stream_name is the name of the mailbox (a unique string no more than 6 characters long);• the create keyword determines whether the mailbox must be created or looked-up as alreadyexisting on the system;• host_name is the name or the IP of the remote host where the mailbox resides; note that if thisfield is given, create must be set to no and the mailbox must be already defined on the remotehost;• the number of channels columns_number determines how many columns can be accessed via thefile drive caller mechanism of Section 2.6.13, as for all the other file drivers.
This part of the program is rapidly evolving, so do please not expect too much documentation andbackward compatibility.
Note: at present, these elements require that the simulation be run in real-time mode (see Section 4.1.5); future development will allow to emulate the use of these elements also when the simulation
is not run in real-time, e.g. for modeling or model debugging purposes.

7.1.5

Stream<normal_arglist> ::= stream ,name , " <stream_name> " ,create , { yes | no } ,[ { local , " <path> " ,| [ port , <port_number> , ] [ host , " <host_name> " , ] } ][ socket type , { tcp | udp } , ][ { [ no ] signal| [ non ] blocking } , [ ... ] , ]136

[ input every , <steps> , ][ receive first , { yes | no } , ][ timeout , <timeout> , ][ echo , " <echo_file_name> "[ , precision , <precision> ][ , shift , <shift> ] , ]{ <columns_number>[ , initial values , <value #1> , ... ][ , modifier , <content_modifier> ]| <user_defined> }<user_defined> ::= <user_defined_type> [ , ... ]<content_modifier> ::=copy| copy cast ,[ swap ,{ <cast_type> [ , ... ]| detect| { yes | no | (bool) <swap> } } , ]{ all , <cast_type> | <one_cast> [ , ... ] }[ , size , (int)<buffer_size> ]<one_cast> ::=<cast_type>| skip , (int)<num_bytes><cast_type> ::=int8_t| uint8_t| int16_t| uint16_t| int32_t| uint32_t| float# assuming float is 4 bytes# assuming double is 8 bytes| double
The stream drive allows MBDyn to receive streamed inputs from remote processes both during regularsimulations and during real-time simulations under RTAI. If the simulation is run in real-time, it uses
RTAI mailboxes, otherwise regular UNIX sockets are used, either in the local or in the internet
namespace.
This drive type is intended to allow the development of real-time models by running regular simulations for the purpose of debugging the model and the control process without the overhead andthe potential problems of running in real-time. Then the same model can be run in real-time withoutchanging the details of the communication with the controller process.
Non real-time simulation During non real-time simulations, streams operate in blocking mode. The
meaning of the parameters is:137• stream_name indicates the name the stream will be known as; it is mostly useless, and must be no
more than 6 characters long, since it is only allowed for compatibility with RTAI’s mailboxes;• the instruction create determines whether the socket will be created or looked for by MBDyn; ifcreate is set to no, MBDyn will retry for 60 seconds and then give up;• the keyword local indicates that a socket in the local namespace will be used; if create is set toyes, the socket is created, otherwise it must exist.
• either of the keywords port or host indicate that a socket in the internet namespace will be used;
if create is set to yes, host_name indicates the host that is allowed to connect to the socket; it
defaults to any host (0.0.0.0); if create is set to no, host_name indicates what host to connect to;
the default is localhost (127.0.0.1); the default port is 9011;• socket type defaults to tcp;
• the keyword no signal disables raising a SIGPIPE in case the stream is read after it was closed by
the peer;• the keyword input every allows to read new driver values every steps time steps;• the keyword receive first allows to enable/disable receiving data at the initial time (defaults toyes, thus data are expected at the initial time, during derivatives);• the keyword timeout allows to set a timeout for each read operation; the timeout is expressed inseconds as a floating point number, with a theoretical micro-second resolution (the actual resolutionis left to the OS);• the keyword echo allows to echo the streamed data into file echo_file_name, using the optional
precision and a shift for the time, to make sure step changes are captured correctly (a small
negative value is recommended); the resulting file is suitable to re-execute the simulation using avariable step file driver, using a const value for the interpolation option;• the keyword initial values, followed by columns_number real values, allows to set the initialvalues of each channel; this is useful for example if the initial value of a channel is needed duringinitial assembly, before the first set of values is read from the peer.
• the keyword modifier installs a data modification layer.
• The copy case leaves data unaltered. The copy cast case performs data casting for each channel
according to the subsequent rules.
– the optional keyword swap instructs MBDyn to swap bytes in order to make transmitted values
platform-independent with respect to endianness, under the assumption that endianness is thesame for all data types. The keyword swap may be followed by a list of the types that must be
swapped, included in those defined in cast_type. Alternatively, the keyword detect causes
the endianness of the platform to be detected and data converted in big endian form if needed.
Otherwise, conversion is either forced for all types in case of yes or non-zero value of swap,
or ignored in case of no or zero value of swap.
– if the keyword all is present, a single one_cast cast rule is applied to all channels. Otherwise,a one_cast rule is read for each channel. Only the types listed above are recognized. The
special value skip actually causes num_bytes to be skipped before the subsequent one_cast
rule is applied.

138

– the optional keyword size is used to provide the entire size of the buffer, in case only a portionof it is going to be used.
If no socket type is specified, i.e. none of the local, port and host keywords are given, a socket is opened
by default in the internet namespace with the default IP and port; the create keyword is mandatory.
Real-time simulation During real-time simulations, streams wrap non-blocking RTAI mailboxes.
The meaning of the parameters is:• the parameter stream_name indicates the name the stream will be known as in RTAI’s resource
namespace; it must no more than 6 characters long, and actually represents the mailbox name;• the instruction create determines whether the mailbox will be created or looked for by MBDyn;• the keyword local is ignored;• the keyword host indicates that a mailbox on a remote host will be used; it is useless when createis set to yes, because RTAI does not provide the possibility to create remote resources; if none isgiven, a local mailbox is assumed;• the keyword port is ignored.
The parameter columns_number determines how many channels will be used. A channel is a double
typed number; a stream drive can read an arbitrary number of simultaneous channels.

139

Chapter 8

Elements
The elements section is enclosed in the cards:
begin : elements ;# ...
end : elements ;Every element card has the following format:<card> ::= <elem_type> :<arglist>[ , output , { yes | no | (bool)<output_flag> } ][ , <extra_arglist> ] ;where elem_type is one of the following:• structural elements:– automatic structural– beam– body– couple– gravity– joint– joint regularization– plate• aerodynamic elements:– aerodynamic beam2– aerodynamic beam3– aerodynamic body– aeromodal– aircraft instruments– air properties140

– induced velocity• electric elements:– electric• hydraulic elements:– hydraulic• thermal elements:– TODO . . .
• output elements:– RTAI output– stream output– stream motion output• generic elements:– bind– bulk– force– genel– loadable– user defined• miscellaneous element cards
In case of elements that can be instantiated only once, like the gravity or the air properties
elements, the arglist does not contain any label; otherwise, a label is expected first, to allow for checks
on duplicated elements, namely:<arglist> ::= <label> , <normal_arglist>
The data manager reads the element type and the label and checks for duplication. If the element is
not defined yet, the proper read function is called, which parses the rest of the card and constructs theelement. The elements are read as follows.

8.1

Aerodynamic Elements

8.1.1

Aerodynamic Body/Aerodynamic Beam2/3

These elements share the description of the aerodynamics. The former assumes the aerodynamic surface
to be rigid, and takes its configuration from a single node, while the latter respectively relies on a twoor three-node beam and use the same interpolation functions of the beam to compute the configuration
at an arbitrary point.
The input format is:141

<elem_type> ::= { aerodynamic body | aerodynamic beam2 | aerodynamic beam3 }<normal_arglist> ::= <connectivity> ,(Shape<1D>)<surface_chord> ,(Shape<1D>)<surface_aerodynamic_center> ,(Shape<1D>)<surface_b_c_point> ,<surface_twist> ,(Shape<1D>)[ tip loss , (Shape<1D>) <tip_loss> , ]<integration_points>[ , control , (DriveCaller) <control_drive> ][ , <airfoil_data> ][ , unsteady , { bielawa } ][ , jacobian , { yes | no | <bool> } ][ , <custom_output> ]<extra_arglist> ::= { std | gauss | node }
where<connectivity> ::= { <body_conn> | <beam2_conn> | <beam3_conn> }# <elem_type> ::= aerodynamic body
<body_conn> ::= <node_label>[ , [ user defined ] induced velocity , <induced_velocity_label>[ , passive ] , ]<relative_surface_offset> ,(Vec3)(OrientationMatrix) <relative_surface_orientation> ,(real)<surface_span># <elem_type> ::= aerodynamic beam2<beam2_conn> ::= <beam2_label>[ , [ user defined ] induced velocity , <induced_velocity_label>[ , passive ] , ]<relative_surface_offset_1> ,(Vec3)(OrientationMatrix) <relative_surface_orientation_1> ,(Vec3)<relative_surface_offset_2> ,(OrientationMatrix) <relative_surface_orientation_2> ,# <elem_type> ::= aerodynamic beam3<beam3_conn> ::= <beam3_label>[ , [ user defined ] induced velocity , <induced_velocity_label>[ , passive ] , ](Vec3)<relative_surface_offset_1> ,(OrientationMatrix) <relative_surface_orientation_1> ,(Vec3)<relative_surface_offset_2> ,(OrientationMatrix) <relative_surface_orientation_2> ,(Vec3)<relative_surface_offset_3> ,(OrientationMatrix) <relative_surface_orientation_3> ,<airfoil_data> ::={ naca 0012
142

| rae 9671
| [ theodorsen , ] c81 , <c81_data> }and<c81_data> ::={ <c81_label>| multiple , <airfoil_number> ,<c81_label> , <end_point>[ , ... ]| interpolated , <airfoil_number> ,<c81_label> , <position>[ , ... ] }The custom_output optional data consists in<custom_output> ::= custom output ,<custom_output_flag> [ , ... ]The values of custom_output_flag are defined in Section 5.2.11.
Flags add up to form the custom output request. Flags may not be repeated. By default, only forces
are output. The custom output is only available in NetCDF format; see Section C.1.4.
The field induced_velocity indicates the label of the induced velocity element that this element islinked to. This means that the element can get information about the induced velocity and should supply
information about the forces it generates. If the keyword user defined induced velocity is used, theninduced_velocity refers to a user defined element. Note: if the keyword induced velocity is usedand no induced velocity element is found with the label induced velocity a user defined elementwith that label is looked up.
An arbitrary relative orientation and offset is allowed for all elements with respect to the nodes they
are linked to. This means that the aerodynamic beam offsets refer to the position of the beam’s nodes,
and have nothing to do with offsets related to the structural beam element.
The Shape<1D> entities are used to compute the physical chord, aerodynamic center, velocity measurement point (the point where the kinematic boundary conditions are evaluated) and twist, in radians,
as functions of the dimensionless abscissa along the span.
The optional tip loss keyword allows to define an additional shape, tip_loss, whose value is used
to scale the value of the normal aerodynamic force. By default, the scale factor is 1. The tip_loss
shape should have a value comprised between 0 and 1.
In any case, the user must be aware of the fact that Gauss integration will be used over the span of theelement. This consists in evaluating forces at specific spanwise stations. This assumes that the function
to be integrated over the spanwise domain is regular. Sharp variations, like tip loss concentrated in theoutermost 2% of a rotor blade span, might be entirely missed when using too little spanwise elementswith too little integration points.
The span of the aerodynamic body element is set by the user; the offset vector points to the centerspan of the element. The span of the aerodynamic beam2 and aerodynamic beam3 elements is computed
based on the metric of the beam, from the first to the last node.
The aerodynamic center and the velocity measurement points are measured relative to the centerlineof the elements, that is the line in direction 3 of the local frame from the end of the offset vector. Thisline is assumed to be at the 25% of the airfoil chord when steady aerodynamic coefficients are used
(unsteady_flag = 0). The direction 1 is assumed to be the “reference” line of the airfoil, from thetrailing edge to the leading edge (points “forward”), while direction 2 is normal to the other two and goesfrom the lower to the upper side of the airfoil (points “up”). Figure 8.1 shows the arrangement of the
airfoil geometry and properties.
143

2
3
chord

1
twist
aerodynamic center

velocity measurement point

Figure 8.1: Airfoil geometry
The airfoil_data defaults to a built-in NACA 0012 semi-analytical model (FIXME: the unsteadycorrection is buggy; use the c81 mode instead).
The multiple mode of the c81 data allows to specify more than one airfoil for an aerodynamic element;
the transition between airfoils is sharp. The integer airfoil_number indicates how many airfoils are
expected; the real end_point indicates where the influence zone for that airfoil ends, expressed in termsof a non-dimensional abscissa spanning (−1, 1) along the reference line, roughly along axis 3 of the
aerodynamic reference frame; end_point must not lie outside the element. So, for example, if airfoil
NACA 0015 is used in the leftmost part of an element up to 1/4 span, NACA 0012 is used from 1/4 to
3/4 span, and NACA 0009 is used in the remaining rightmost 1/4, the syntax is:
set: integer naca0015 = 15;
set: integer naca0012 = 12;
set: integer naca0009 = 9;c81 data: naca0015, "naca0015.c81";
c81 data: naca0012, "naca0012.c81";
c81 data: naca0009, "naca0009.c81";# beginning of aerodynamic element definition...
multiple, 3,
naca0015, -0.5,# from -1.0 to -0.5
naca0012, 0.5,
# from -0.5 to 0.5
naca0009, 1.0,
# from 0.5 to 1.0# ...rest of aerodynamic element definition
The interpolated mode of the c81 data allows to specify a smooth transition between different
airfoils inside an element. The interpolation occurs at the integration points where the aerodynamic
data are required, and it is performed once for all at the beginning of the analysis. Since this operation
is time consuming, and essentially unnecessary, the interpolated data can be generated once for all withthe utility util/c81merge once the position of the integration point is known, and the multiple modecan be used to directly provide the interpolated data to the aerodynamic element.
The theodorsen aerodynamic data uses C81 data, and superimposes Wagner’s approximation of the
Theodorsen incompressible unsteady correction of 2D lift and moment coefficients. It is experimental.
The extra_arglist allows to define the style of the output. The std style (the default), the gauss
and the node styles are illustrated in the output section.
OutputAerodynamic elements, both bodies and beams, write their output with file extension .aer; for eachtime step the required elements are output. In any case the label of the element is output first. Three144

different formats are available: std (the default), gauss and node.
std (or Coefficients at Gauss points): the output consists in a set of 8 numbers for each block, that
describe data at each Gauss integration point; multiple blocks for a single element are written on
the same line. The format is:– the angle of attack at that station, in degrees (namely, the angle between the component of
the airfoil velocity, evaluated at the velocity measurement point, that in the airfoil plane anda reference line on the airfoil)– the local yaw angle, in degrees (namely, the angle whose tangent is the ratio between the axial
and the inplane components of the airfoil velocity)– the local Mach number– the local lift coefficient– the local drag coefficient– the local aerodynamic moment coefficient– a private number– another private number
When aerodynamic beam2 and aerodynamic beam3 elements are considered, the output is repeated for each portion of the beam; so, for example, a two-node beam is split in two portions,so the output contains 2 × integration_points data blocks, while a three-node beam is split inthree portions, so the output contains 3 × integration_points data blocks.
node: the format is:– the label of the node
– the three components of the force applied to the node
– the three components of the couple applied to the node
When aerodynamic beam2 and aerodynamic beam3 elements are considered, the output is repeated on the same line for each node the element is connected to.
gauss (or Forces at Gauss points): the output consists in the forces and moments per unit length at each
Gauss integration point; the format is:– the direction of the wind velocity relative to the element frame– the lift,– the drag,– and the aerodynamic moment per unit length
When aerodynamic beam2 aerodynamic beam3 elements are considered, the output is repeatedon the same line for each portion of beam.

145

8.1.2

Aeromodal Element

Note: implemented by Giuseppe Quaranta; documented by Alessandro Scotti.
This element is used to model an aerodynamic modal element, i.e. an unsteady aerodynamic model that
inherits the structural motion from a modal joint element. Its definition is very similar to that of themodal element, but it also includes some data representing unsteady aerodynamics in the time domain
trough the residualization matrices. This element is defined as follows:<elem_type> ::= aeromodal<normal_arglist> ::=<reference_modal_joint> ,(OrientationMatrix) <orientation> ,<reference_chord> ,<number_of_aerodynamic_states> ,[ rigid , ][ gust , ]" <modal_matrices_file> "With this formulation, anytime an aeromodal element is defined, the user needs to declare the numberof modal aerodynamic elements in use in the control data section. An air properties card definitionis also required.
The label reference_modal_joint indicates the modal joint associated to the aeromodal element.
The modal joint must be connected to a modal node; clamped modal joints are not supported.
The keyword rigid indicates that the generalized aerodynamic forces provided by the model include
global forces and moments associated to the rigid body motion of the underlying modal element (FIXME:
untested).
The keyword gust activates an optional gust model, which is totally undocumented; for further
information, please contact the Author(s).
The modal_matrices_file file is an ASCII file that contains the matrices A, B, C, D0 , D1 andD2 , of a state space model according to the representationẋ = Ax + Bqcf = q Cx + D0 q +D1 q̇ +
2V∞



c
2V∞

2

D2 q̈

!

where x are the number_of_aerodynamic_states (na) aerodynamic state variables, q are the ns modal
variables that describe the structural motion as defined in the related modal joint, c is the reference2
length, V∞ is the free airstream velocity, q = ρV∞/2 is the dynamic pressure, and f are the unsteady
aerodynamic forces applied to the structural dynamics equations.
When the keyword rigid is present, the number of modal variables ns includes the modes provided
by the modal joint plus 6 rigid-body modes corresponding to rigid-body displacement and rotation of
the modal node.
The file is formatted as follows:*** MATRIX A(<na> x <na> coefficients)*** MATRIX B(<na> x <ns> coefficients)*** MATRIX C(<ns> x <na> coefficients)146

*** MATRIX D0(<ns> x <ns> coefficients)*** MATRIX D1(<ns> x <ns> coefficients)*** MATRIX D2(<ns> x <ns> coefficients)
Example.
aeromodal: WING, WING_JOINT,
eye,
131.25, 10, "ha145b.fea";
The aeromodal element is declared with the label WING. This element is attached to a modal joint
named WING_JOINT. The orientation of the aerodynamic reference with respect to the nodal referenceis here expressed by the identity matrix (eye). The aerodynamic element chord is 131.25 inches. Thisquantity must be consistent with the system chosen to define the whole model (SI, for example; in thiscase, British Units). The next field, 10, indicates the number of states needed to use the aerodynamic
model. ha145b.fea is the name of the file that contains the state space model matrices, obtainedwith an approximation chosen by the user. In this particular case, a 10 states Padé approximation has
been chosen. This example is taken from the Bisplinghoff Ashley Halfman (BAH) Jet Transport Wing
cantilevered wing with modal aerodynamic frequency response, computed by a double-lattice method
at Mach 0.0. Data were extracted from the MSC-NASTRAN aeroelastic example file, named ha145b,
while the aerodynamic state-space fitting has been computed using a Padé polynomial approximation(by Pasinetti & Mantegazza, [10]). All quantities are expressed in inches and pounds.

8.1.3

Aircraft Instruments<elem_type> ::= aircraft instruments<normal_arglist> ::= <aircraft_node>[ , orientation , { flight mechanics | aeroelasticity| (OrientationMatrix) <relative_orientation> } ]The aircraft_node represents the aircraft; it is assumed that the positive x direction of the node is
tail to nose of the aircraft, the positive z direction of the node is top to bottom of the aircraft, and thepositive y direction of the node is to the right of the pilot. The node representing the aircraft is intended
in a “world” reference frame whose positive z direction points upward and whose positive x direction
points north (note that currently the world is flat).
An optional orientation can be added to change the orientation of the aircraft with respect to thenode. This is useful, for example, with aeroelasticity, in which conventionally the positive directionof the x axis is nose to tail, and the positive direction of the z axis is bottom to top. The keyword
flight mechanics indicates that the node representing the aircraft is oriented according to the default
orientation of the element, whereas the keyword aeroelasticity indicates that the node representing
the aircraft is oriented accordingly. Arbitrary orientations can be dealt with by providing an appropriate
relative_orientation matrix.

147

flight mechanics
x

y
z
z
x
aeroelasticityy

The available measures are accessed during the simulation by defining appropriate parameter nodes,
and by binding the aircraft instruments element private data to the nodes by means of the bindmechanism, or directly by means of the element drive (see Section 2.6.11).
Private Data

The following data are available:• "airspeed": the airspeed as seen by the reference point on the aircraft, i.e. the absolute value ofthe combination of the airstream speed and of the node speed• "groundspeed": the absolute value of the projection of the node speed in the xy plane of the“world”• "altitude": the z component of the node position with respect to the “world”• "attitude": tan−1 (r31 , r11 )• "bank": − tan−1 (r32 , r22 )• "turn": (FIXME: not implemented yet)• "slip": (FIXME: not implemented yet)• "verticalspeed": the z component of the node velocity in the “world” reference system• "angleofattack": the angle between the local z and x components of the velocity (airstream plusnode), expressed in the reference frame of the aircraft• "heading": the angle between the x axis of the aircraft and the “north” (the global x axis) about
the global z axis; note: heading wraps about South (+180 deg from East, -180 deg from West).
• "longitude": (FIXME: not implemented yet)• "latitude": (FIXME: not implemented yet)• "rollrate": the component of the angular velocity of the node representing the aircraft along thex axis of the node itself (positive when the right wing moves downward)• "pitchrate": the component of the angular velocity of the node representing the aircraft along
the y axis of the node itself (positive when the nose pitches upward)• "yawrate": the component of the angular velocity of the node representing the aircraft along thez axis of the node itself (positive when the right wing moves backward)
148

Example.
# expose heading using a parameter node
# ...
structural: AIRCRAFT, dynamic, ...
parameter: HEADING, /* bound to */ element;# ...
aircraft instruments: AIRCRAFT, AIRCRAFT, orientation, aeroelasticity;bind: AIRCRAFT, aircraft instruments, HEADING, string, "heading";# implement a minimal SCAS on roll & yaw# ...
structural: AIRCRAFT, dynamic, ...
# ...
aircraft instruments: AIRCRAFT, AIRCRAFT, orientation, flight mechanics;
couple: AIRCRAFT, follower,
AIRCRAFT,
position, null,component,element, AIRCRAFT, aerodynamic element, string, "rollrate",
linear, 0., -ROLL_GAIN,
0.,element, AIRCRAFT, aerodynamic element, string, "yawrate",
linear, 0., -YAW_GAIN;
Note: this element is eXperimental.

8.1.4

Air Properties

The properties of the airstream are made of the physical properties of the air plus the description of theairstream velocity direction and amplitude. The former can be expressed in different forms, while thelatter are based on three-dimensional drive callers, TplDriveCaller<Vec3>.
<elem_type> ::= air properties<arglist> ::={ (DriveCaller) <air_density> , (real) <sound_celerity>| std , { { SI | British }[ , temperature deviation , <delta_T> ]| <p0> , (DriveCaller) <rho0> ,<T0> , <dT/dz> , <R> , <g0> , <z1> , <z2> }[ , reference altitude , <z0> ] } ,(TplDriveCaller<Vec3>) <air_speed>[ , gust , <gust_model> [ , ... ] ]The first form consists in the bare input of the air density, in form of a drive caller, and of the soundcelerity, e.g.:
air properties: 1.225, 340.,
1.,0.,0., 150.;
The second form uses standard air properties, both in the international system (SI) or in British units.
A temperature deviation and an altitude offset can be defined, e.g.:
149air properties: std, SI, temperature deviation, -55,
reference altitude, 1000.,
1.,0.,0., 150.;
where standard properties in SI are used, with a temperature deviation of -55 K and a reference altitude of1000 m. The air properties are computed based on the z position of the point where the air propertiesare requested (plus the optional altitude offset). The last possibility lets the user input all the parameters
required to compute the air properties based on the z position of the point where they are requested,
namely the reference pressure p0, the reference density rho0, the reference temperature T0, the initial
temperature gradient dT/dz, the gas constant R, the initial gravity acceleration g0, the bottom and top
altitudes of the null temperature gradient region z1 and z2; e.g., for SI units:
air properties: std,101325.,/* Pa, 1 bar */1.2250,/* kg/m^3 */288.16,/* K, ISA: 15 C */-6.5e-3,/* K/m */287.,/* J/kgK */9.81,/* m/s^2 */11000.,/* m */
25000.,/* m */
temperature deviation, -55,
reference altitude, 1000.,
1.,0.,0., 150.;
The air properties are defined according to the formulas

T = T0 + dT/dz · zg0!− dT/dz·R



T


p = p0
T0
g0!−( dT/dz·R

+1) 


T



ρ = rho0
T0
T0 + dT/dz · z1 
T =



g0
!− dT/dz·R



T
z−z1

−g0 dT/dz·R




e
p = p0
T0
g0!−( dT/dz·R

+1)



T
z−z1
−g0 dT/dz·R ρ = rho0eT0z < z1(8.1a)

z1 ≤ z < z2

(8.1b)

The case of z > z2 is not currently handled; the formulas for z ≥ z1 are actually used. The value of z
is computed by adding the z component of the position where the air properties are computed to thereference altitude z0.
The asymptotic air properties are characterized by air_speed, the TplDriveCaller<Vec3> of the air
speed, expressed in the global reference frame. The possibility to vary the density and the airspeed usinga driver has little physical meaning, especially the former; is intended as a practical means to gradually
introduce the desired air properties, and the related airloads, in the analysis.

150

Gust
If the optional gust keyword is used, a gust model can be added. Note that a very elementary gustmodel, represented by a uniform change in airstream speed and direction can be implemented by using
a time-dependent airstream drive.
Gusts can also be appended later to the air properties element by using the statement
gust : <gust_model> ;Front 1D Gust The syntax of the front 1D gust model is:<gust_model> ::= front 1D ,(Vec3)<front_direction> ,<perturbation_direction> ,(Vec3)<front_velocity> ,(real)(DriveCaller) <front_profile>
This model consists in a uniform front, defined asv (x, t) = ng (f · x + Vref · t)
where
• v is the velocity perturbation;• x is the position of the point whose airstream velocity is being computed;• t is the current time;• n is the unit vector perturbation_direction that defines the direction of the velocity perturbation;• g (·) is the function front_profile that defines the gust profile;• f is the unit vector front_direction that defines the direction of propagation of the front;• Vref is the velocity front_velocity of propagation of the front in direction f .
As an example, a transverse cosine-shaped gust, with a wavelength of 100 m and a peak velocity of 5
m/s moving downstream at the airstream speed, 100 m/s, in standard air, is presented:
set: real waveLength = 100.; # m
set: real V_inf = 100.;# m/s
set: real V_g = 5.;# m/s
air properties: std, SI,
1.,0.,0., const, V_inf, # reference airstream along X
gust, front 1D,
1.,0.,0.,# front moving along X
0.,0.,1.,# gust along Z
V_inf,# front moving at V_inf
cosine, 0., pi/waveLength, V_g/2., one, 0.;151

Scalar Function Wind Profile The syntax of the scalar function wind profile, implemented as agust model within the air properties, is:<gust_model> ::= scalar function ,reference position , (Vec3) <X0> ,reference orientation , (OrientationMatrix) <R0> ,(ScalarFunction) <sf>
It yields a uniform velocity profile along the x axis of the reference orientation as a function of the z axis
component of the relative position; namely, given the relative positionz = e3 · (x − X0) ,(8.2)

v = e1 · sf(z),(8.3)

the velocity iswhere ei is the i-th axis of the reference orientation R0.
Power Law Wind Profile The syntax of the power law wind profile, implemented as a gust model
within the air properties, is:<gust_model> ::= power law ,reference position , (Vec3) <X0> ,reference orientation , (OrientationMatrix) <R0> ,reference elevation , <z_ref> ,reference velocity , (DriveCaller) <v_ref> ,exponent , <exponent>
It yields a uniform velocity profile along the x axis of the reference orientation as a function of the z axis
component of the relative position; namely, given the relative positionz = e3 · (x − X0) ,(8.4)

the velocity iszv = e1 · v_ref
z_refexponent

,

(8.5)

where ei is the i-th axis of the reference orientation R0. Typical values of exponent are about 0.1.
Logarithmic Wind Profile The syntax of the logarithmic wind profile, implemented as a gustmodel within the air properties, is:<gust_model> ::= logarithmic ,reference position , (Vec3) <X0> ,reference orientation , (OrientationMatrix) <R0> ,reference elevation , <z_ref> ,reference velocity , (DriveCaller) <v_ref> ,surface roughness length , <z_0>152

It yields a uniform velocity profile along the x axis of the reference orientation as a function of the z axis
component of the relative position; namely, given the relative positionz = e3 · (x − X0) ,(8.6)

the velocity isv = e1 · v_ref ·log(z/z_0) − ψm,log(z_ref/z_0) − ψm

(8.7)

where ei is the i-th axis of the reference orientation R0.
The surface roughness length describes the typical roughness of the surrounding surface. It is a verysmall number in case of smooth surface (e.g. 0.01m for grass), or 1/20 to 1/30 of the typical obstacle’s
size (e.g. 1m for woods).
Output The output occurs in the .air file, which contains:• a fake label, always set to 1
• the air density• the sound celerity• the three components of the reference air speed with respect to the inertial reference frame
Private Data

The following data are available:• "vxinf" the x component of the airstream speed (without any gust contribution)• "vyinf" the y component of the airstream speed (without any gust contribution)• "vzinf" the z component of the airstream speed (without any gust contribution)• "vinf" the module of the airstream speed (without any gust contribution)

8.1.5

Generic Aerodynamic ForceThis element computes generalized aerodynamic forces parametrized on dynamic pressure and angle ofattack and sideslip angle.
<elem_type> ::= generic aerodynamic force<normal_arglist> ::= <node_label> ,[ position , <relative_position> , ][ orientation , <relative_orientation> , ][ reference surface , <reference_surface> , ][ reference length , <reference_length> , ][ alpha first , { no | yes } , ]{ <data_file_specification> | reference , <gaf_data_label> }<data_file_specification> ::= file ,[ { angle units , { radians | degrees }| scale angles , <angle_scale_factor> } , ][ scale lengths , <length_scale_factor> , ]" <data_file_name> "153

This element computes aerodynamic forces and moments fa , ma proportional to the dynamic pressureq = ρv T v/2 and to empirical coefficients tabulated as functions of the angle of attack α and the sideslip
angle β. The angles are computed from the relative airstream velocity v expressed in the reference frameof the body. The velocity is computed at the reference point, optionally offset from the node node_label
by the offset relative_position (defaults to null), in a reference frame optionally oriented from thatof the node node_label by the orientation matrix relative_orientation (defaults to eye), namelyo = (Vec3) relative_position
Rh = (OrientationMatrix) relative_orientationv = RTh RTn (ẋn + ωn × Rn o) ,(8.8a)(8.8b)(8.8c)

where xn and Rn are the position and orientation of the node, and ẋn and ωn are its linear and angularvelocity. By default the angles are computed from the components of v according to the formulas!
v3
α = atan(8.9a)
kv1 k!
v2p
β = −atan;(8.9b)
sign(v1 ) v12 + v22

as a consequence, −π/2 ≤ α ≤ π/2 and −π ≤ β ≤ π. If the optional keyword alpha first is set toyes, the alternative formulas!
v3
p(8.10a)α = atansign(v1 ) v12 + v22!
v2.
(8.10b)β = −atan
kv1 k
are used; as a consequence, −π ≤ α ≤ π and −π/2 ≤ β ≤ π/2. In both cases, they assume that the
body reference system is loosely aligned as:• axis 1 goes from tail to nose of the aircraft;• axis 2 points “to the right”;• axis 3 points towards the ground when the aircraft is in level flight.
Force and moment are consistently applied to the node as
fn = Rn Rh fa(8.11a)mn = Rn Rh ma + Rn (o × (Rh fa ))(8.11b)Note: this element does not contribute to the Jacobian matrix of the problem; as such, it may deteriorate the convergence properties of the solution when aerodynamic forces dominate the problem. Moreover,
it is not suitable for the direct computation of the eigenvalues of a problem about a steady solution.
Note: this element, by itself, may not be adequate to model the rigid body aerodynamics of an aircraft,
since it does not account for the dependence of force and moment on angle rates.

154

Output The following output is available:
1. column 1: element label
2. column 2: the angle of attack α
3. column 3: the sideslip angle β
4. columns 4–6: the components of force fa in local x, y and z directions
5. columns 7–9: the components of moment ma in local x, y and z directions, about the reference
point (node plus offset)
6. columns 10–12: the components of force fn in global x, y and z directions
7. columns 13–15: the components of moment mn in global x, y and z directions, about the node
Private Data

The generic aerodynamic force element outputs the following private data:• "Fx", "Fy", "Fz": force components in the global reference frame;• "Mx", "My", "Mz": moment components in the global reference frame, about the node;• "fx", "fy", "fz": force components in the local reference frame;• "mx", "my", "mz": moment components in the local reference frame, about the reference point;• "alpha": angle of attack (in radian)• "beta": sideslip angle (in radian)
The values computed during the last residual assembly are returned.
Generic Aerodynamic Element Data
Data is stored in ASCII format in a file.
An arbitrary number of comment lines is allowed at the beginning. Comment lines start with either
a percent ‘%’ or a hash mark ‘#’ in the first column. Their content is discarded until the end of the line.
The first non-comment line must contain two integers separated by whitespace. The integers represent
the expected number of angle of attack and sideslip angle values, Nα and Nβ .
Another arbitrary number of comment lines is allowed.
A set of Nα · Nβ lines is expected. No comments or empty lines are allowed in between. Each line
contains:• column 1: the angle of attack, α• column 2: the sideslip angle, β• columns 3–5: the force coefficients fx/q , fy/q , fz/q
• columns 6–8: the moment coefficients mx/q , my/q , mz/q
Notes:
1. lines are sorted as follows: all values of α are defined for each value of β; the same values of α are
expected for each value of β;155

2. the angle ranges are −π/2 ≤ α ≤ π/2 and −π ≤ β ≤ π; or, if alpha first is yes, they are−π ≤ α ≤ π and −π/2 ≤ β ≤ π/2;
3. the angles are expected in radians; use the mutually exclusive optional keywords angle units, tospecify either radians or degrees, or scale angles, to specify the angle_scale_factor. The
angle_scale_factor is the factor that when multiplied by the angle transforms it into radians;
for example, if angles are provided in degrees then angle_scale_factor = π/180;
4. q = 1/2ρV 2 is the local reference dynamic pressure, where V is the norm of the velocity at thereference point;
5. the coefficients express forces and moments in the reference frame attached to the body;
6. the coefficients are either expected in dimensional or non-dimensional form. In the former case,the force coefficients represent areas, while the moment coefficients represent volumes, since theyneed to be multiplied by the dynamic pressure to become forces and moments. In the latter
case, they are pure numbers; a reference_surface and reference_length must be defined in
the configuration of the corresponding generic aerodynamic force element. When dimensionalcoefficients are specified, they can be rescaled by using the optional keyword scale lengths to
specify the length_scale_factor.
Example. The content of the file example.dat is# This is an example of data for the "generic aerodynamic force" element# 5 values of angle of attack (alpha) and 4 values of sideslip angle (beta)# are provided
5 4# alpha beta fx/q fy/q fz/q mx/q my/q mz/q
-90 -180 0 0 0 0 0 0-20 -180 0 0 0 0 0 0
0 -180 0 0 0 0 0 0
20 -180 0 0 0 0 0 0
90 -180 0 0 0 0 0 0-90 -20 0 0 0 0 0 0-20 -20 0 0 0 0 0 0
0 -20 0 0 0 0 0 0
20 -20 0 0 0 0 0 0
90 -20 0 0 0 0 0 0-90
20 0 0 0 0 0 0-20
20 0 0 0 0 0 0
0
20 0 0 0 0 0 0
20
20 0 0 0 0 0 0
90
20 0 0 0 0 0 0-90 180 0 0 0 0 0 0-20 180 0 0 0 0 0 0
0 180 0 0 0 0 0 0
20 180 0 0 0 0 0 0
90 180 0 0 0 0 0 0The corresponding statement in the input file is156

set: integer GAF_NODE = 10;
set: integer GAF_ELEM = 20;
generic aerodynamic force: GAF_ELEM, GAF_NODE,
file, angle units, degrees, "example.dat";

8.1.6

Induced velocity

The induced velocity element is used to associate the aerodynamic elements that model the lifting
surfaces of an aircraft, or the blades of a helicopter rotor, when some inflow related computations are
required.
By means of different inflow models, and by means of the aerodynamic load contributions supplied by
the aerodynamic elements, the induced velocity element is able to compute the induced velocity at anarbitrary point on the lifting surface or rotor disk. This velocity term in turn is used by the aerodynamic
elements to determine a better estimate of the boundary conditions.
The syntax of the induced velocity elements is:<elem_type> ::= induced velocity<normal_arglist> ::= <induced_velocity_type> , <induced_velocity_data>
Rotor
Currently, induced velocity models are only implemented for helicopter and cycloidal rotors. For thelatter, see Section B.1.3. Originally, this type of element was known as rotor, and the original syntax ispreserved for backwards compatibility.
The syntax of the helicopter rotor induced velocity element is:<induced_velocity_type> ::= rotor<induced_velocity_data> ::= <craft_node> ,[ orientation , (OrientationMatrix) <rotor_orientation> , ]<rotor_node> ,induced velocity , <induced_velocity_model>
The optional rotor_orientation is required when axis 3 of the craft_node is not aligned with therotor axis; axis 3 of the rotor_node must be aligned with the rotor axis.
There are five models of induced velocity. The first is no induced velocity; the syntax is:<induced_velocity_model> ::= noThere is no argument list. This element does not compute any induced velocity, but still computes therotor traction for output purposes, if output is required. The others have a fairly common syntax. The
first three are uniform, glauert and mangler induced velocity models:<induced_velocity_model> ::={ uniform | glauert [ , type , <glauert_type> ] | mangler } ,<reference_omega> , <reference_radius>[ , <option> [ , ... ] ]<glauert_type> ::= { glauert | coleman | drees| payne | white and blake | pitt and peters | howlett }157

<option> ::={ ground , <ground_node>| delay , (DriveCaller) <memory_factor>| max iterations , <max_iterations>| tolerance , <tolerance>| eta , <eta>| correction , <hover_correction_factor>, <ff_correction_factor> }• The reference_omega field is used to decide whether the induced velocity computation must be
inhibited because the rotor speed is very low.
• The reference_radius field is used to make the rotor related parameters non-dimensional.
• The ground parameter is used to inform the rotor about the proximity to the ground; the z
component of the distance between the rotor and the ground nodes, in the ground node reference
frame (direction 3, positive), is used for an approximate correction of the axial inflow velocity [11].
• The memory_factor, the hover_correction_factor and the ff_correction_factor (forward
flight) are used to correct the nominal induced velocity, according to the formula
Ueffective = (1 − memory_factor) Unominal+ memory_factor Uprevious

withT

Unominal =2ρAVtip

s

2

λ
µ2
+
hover_correction_factor4 ff_correction_factor2

The delay parameter is used to linearly combine the current reference induced velocity with theinduced velocity at the previous step; no delay means there is no memory of the previous value.
The memory factor behaves like a discrete first-order low-pass filter. As a consequence, its behavior depends on the integration time step. The memory_factor parameter defaults to 0. The
hover_correction_factor and ff_correction_factor parameters default to 1.
• The max_iterations, tolerance and eta parameters refer to the iteration cycle that is performed
to compute the nominal induced velocity. After max_iterations, or when the absolute value ofthe difference between two iterations of the nominal induced velocity is less than tolerance, thecycle ends. Only a fraction eta of the difference between two iterations of the nominal induced
velocity is actually used; eta defaults to 1. The default is to make only one iteration, which isbackward-compatible with the original behavior.
The last induced velocity model uses a dynamic inflow model, based on [12], with 3 inflow states.
The syntax is:<induced_velocity_model> ::= dynamic inflow ,<reference_omega> ,<reference_radius>[ , <option> [ , ... ] ]<option> ::={ ground , <<ground_node>158

| initial value , <const_vel> , <cosine_vel> , <sine_vel>| max iterations , <max_iterations>| tolerance , <tolerance>| eta , <eta>| correction , <hover_correction_factor> , <ff_correction_factor> }Most of the parameters are the same as for the previous models. The optional delay parameter is nolonger allowed. The three states, corresponding to uniform, fore-aft and lateral inflow, can be explicitly
initialized by means of the optional initial value parameter.
Output The following output is available for all rotor elements:
1. column 1: element label
2. columns 2–4: rotor force in x, y and z directions (longitudinal, lateral and thrust components)
3. columns 5–7: rotor moment about x, y and z directions (roll, pitch and torque components)
4. column 8: mean inflow velocity, based on momentum theory
5. column 9: reference velocity at rotor center, sum of airstream and craft_node node velocity
6. column 10: rotor disk angle
7. column 11: advance parameter µ
8. column 12: inflow parameter λ9. column 13: advance/inflow angle χ = tan−1 (µ/λ)
10. column 14: reference azimuthal direction ψ0 , related to rotor yaw angle
11. column 15: boolean flag indicating convergence in reference induced velocity computation internal
iterations
12. column 16: number of iterations required for convergence
The dynamic inflow model adds the columns
13. column 17: constant inflow state
14. column 18: sine inflow state (lateral)
15. column 19: cosine inflow state (longitudinal)
Rotor force and moment (columns 2–4 and 5–7) are the aerodynamic force and moment exerted by therotor aerodynamics on the rotor_node, projected in the reference frame of the craft_node, optionallymodified by the rotor_orientation matrix. The conventional naming of longitudinal (or drag), lateraland thrust force, and roll, pitch and torque moment, refer to a rotorcraft whose x axis is the longitudinal(nose to tail) axis, whose y axis is the lateral (portside) axis, and whose z axis is the vertical (bottom totop) axis.

159

Private Data

The following data are available:

1. "Tx" rotor force in x direction (longitudinal force)
2. "Ty" rotor force in y direction (lateral force)
3. "Tz" rotor force in z direction (thrust)
4. "Mx" rotor moment about x direction (roll moment)
5. "My" rotor moment about y direction (pitch moment)
6. "Mz" rotor moment about z direction (torque)
The rotor force and moment components are expressed in the same reference frame described in the
Output Section above.

8.1.7

Rotor

Deprecated; see induced velocity (Section 8.1.6).

8.2

Automatic structural

The so called automatic structural element is automatically generated when a dynamic structuralnode is instantiated. As such, when defined in the elements block, the element already exists. The only
reason to repeat its definition is to modify the values of the momentum and of the momenta moment,
and to initialize their derivatives. The label must match that of the node it refers to.
<elem_type> ::= automatic structural# for 6 dof structural nodes<normal_arglist> ::=(Vec3) <momentum> ,(Vec3) <momenta_moment> ,(Vec3) <momentum_derivative> ,(Vec3) <momenta_moment_derivative># for 3 dof structural nodes<normal_arglist> ::=(Vec3) <momentum> ,(Vec3) <momentum_derivative>
All the provided values are recomputed during the initial derivatives phase, so they should be intended as
initial values for the Newton iteration. In general, there is no need to provide this data; they can speed
up initial convergence in case of systems that are not at rest in the initial configuration, with kinematicconstraints that strongly affect the motion.
Private Data

The following data are available:

1. "beta[1]" momentum in global direction 1
2. "beta[2]" momentum in global direction 2
3. "beta[3]" momentum in global direction 3160

4. "gamma[1]" momenta moment in global direction 1
5. "gamma[2]" momenta moment in global direction 2
6. "gamma[3]" momenta moment in global direction 3
7. "betaP[1]" momentum derivative in global direction 1
8. "betaP[2]" momentum derivative in global direction 2
9. "betaP[3]" momentum derivative in global direction 3
10. "gammaP[1]" momenta moment derivative in global direction 1
11. "gammaP[2]" momenta moment derivative in global direction 2
12. "gammaP[3]" momenta moment derivative in global direction 3
13. "KE" kinetic energy

8.3

Beam Elements

The family of finite volume beam elements implemented in MBDyn allows to model slender deformablestructural components with a high level of flexibility.
The beam is defined by a reference line and by a manifold of orientations attached to the line. It is
assumed that the direction 1 of the orientations lies along the reference line, but it is not strictly required
to be tangent to it even in the reference configuration.
The beam element is defined by its nodes; currently, 2 and 3 node beam elements are implemented.
Each node of the beam is related to a structural node by an offset and an optional relative orientation,
to provide topological flexibility.
The beam element is modeled by means of an original Finite Volume approach [13], which computes
the internal forces as functions of the straining of the reference line and orientation at selected points
along the line itself, called evaluation points, which lie somewhere between two pairs of beam nodes.
At each evaluation point, a 6D constitutive law must be defined, which defines the relationshipbetween the strains, the curvatures of the beam and their time derivatives and the internal forces andmoments at the evaluation points.
The strains and curvatures and their time derivatives are obtained from the nodal positions andorientations by differentiating the interpolation functions.
The 6D constitutive laws are defined as

 



ε̇x 
εx 
Fx 










 






γ̇y 
γy 
Fy 




















 γz
γ̇z
Fz


,
=f
κ̇
κ
M

 x 
 

 x 
 x 




 






 κ̇y   κy  My 







 



κ̇z
κz
Mz
where, if the convention of using x as beam axis is followed:• Fx is the axial force component;• Fy and Fz are the shear force components;• Mx is the torsional moment component;161• My and Mz are the bending moment components;• εx is the axial strain component;• γy and γz are the shear strain components;• κx is the torsional curvature component;• κy and κz are the bending curvature component;• f is an arbitrary function that defines the constitutive law.

8.3.1

Beam Section Constitutive Law

Typically, linear elastic or viscoelastic constitutive laws are used, although one may want to implement
specific nonlinear elastic or elastic-plastic constitutive laws.
Beam Section Characterization
MBDyn allows the broadest generality in defining what a linear elastic constitutive law contains, since
the entire 6 × 6 constitutive matrix can be input. This means that internal forces and moments can bearbitrarily related to generalized strains and curvatures. However, to make sense, a constitutive matrix
at the section level, must satisfy some constraints, e.g. it is expected to be symmetric, although this is
not strictly enforced by the code.
However, most of the info about the extra-diagonal terms of the stiffness matrix are not usuallyavailable. One easy way to work this around is to resort to any so-called composite beam section
characterization analysis available in the literature.
For details, the reader is referred to [14] for a review of the topic, to [15] for an early work on thesubject, and to [16] for a more recent review of the original formulation. The software that implements
this type of analysis is called ANBA++. It is not free software, so far. Prospective users can contact
the authors, through MBDyn developers.
Disclaimer
The following paragraphs are intended as a means to help users preparing data for MBDyn models ina consistent manner. By no means they indicate that the beam section stiffness properties must be
provided in a specific reference frame. On the contrary, MBDyn allows as much generality as possible,
and actually the variety of choices is redundant, since equivalent properties can be input in different
ways.
This is intended to allow the code to suit the users’ needs regardless of the original format of the
input data. As such, all the transformations reported in the following are only intended as suggestions
and should not be taken literally. For instance, rotations and offsets of reference points could be reversed,changing the values of the offsets, without affecting the final result.
The most important aspect of MBDyn notion of beam section properties is that the reference point
and orientation, although arbitrary, must be unique, and the common notions of center of axial strain,
shear center (and center of mass) have no special meaning.
Equivalent 6 × 6 Section of Isotropic Beam
When an isotropic beam section is considered, the 6× constitutive matrix, referred to an arbitrary pointin the section, with an arbitrary orientation, can always be written in terms of elementary stiffness andgeometrical properties. These are the properties that are usually available in tabular form either from162

simplified beam section analysis or by experiments. A sketch of a generic section is shown in Figure 8.3,
where the arbitrary reference frame indicated by axes x, y and z originates from an arbitrary reference
point on the section.
Isotropic uniform beam sections allow to group the internal forces and moments in two sets, together
with their conjugated generalized strains: those related to shear stress and strain, and those related toaxial stress and strain, as illustrated in Figure 8.2. There is no direct coupling between the two groups,
Fx
Fy
Fz
Mx
My
Mz

εx
A

γy

γz

κx

S
S
S

S
S
S

S
S
S

A
A

κy
A

κz
A

A
A

A
A

Figure 8.2: Constitutive coefficients grouping (S: shear, A: axial)
at the section level, so the corresponding coupling coefficients are always zero. This is no longer true
when material anisotropy must be taken into account.
The 3 × 3 sub-blocks can be separately transformed in diagonal form by referring the corresponding
properties to appropriate separate points in the beam section, and by applying an appropriate rotation
about the axis of the beam.
Axial Stress and Strain Properties
This section considers the submatrix represented by the coefficients marked as A in Figure 8.2, under
the assumption that it is symmetric.
First, the problem of obtaining axial stiffness properties referred to a generic point in a genericorientation is considered, when the properties referred to the axial strain center in the principal reference
frame are known.
Then, the problem of extracting the location of the axial strain center and of the principal reference
frame, and the principal bending stiffnesses from generic data is presented as well.
The two problems are complementary. Usually, the first one needs to be considered when engineering
properties are available and the generic constitutive properties required by MBDyn need to be computed.
Diagonal to Generic Properties. First the transformation from diagonal to generic properties is
considered. This transformation consists in rotating the section properties and then in referring them to
a common reference point in the blade section.
The diagonal properties are described by the constitutive matrix

† 
EA
0
 Fx 
My
EJy
=


Mz
sym.



0
 εx 
κy
0 
.


EJz
κz

(8.12)

This constitutive matrix is expressed in a reference frame that is centered in the center of axial strain,indicated with the subscript as, and oriented according to the bending principal axes.
A rotation α about axis x is used to transform the properties into the common reference frame of the163beam section. The internal forces and moments are thus transformed according to

∗

†
 Fx 
 Fx 
= [R]axial
My
My




Mz
Mz
†


1
0
0
 Fx 
=  0 cos α − sin α 
,
My


Mz
0 sin α cos α

while the strains and curvatures are transformed according to


∗
†
 εx 
 εx 
−Tκyκy= [R]axial




κz
κz

†
 εx 
= [R]axial
.
κy


κz

As a consequence, the constitutive relationship becomes


∗
∗
 Fx 
 εx 
Myκy= [R]axial [A]† [R]Taxial




Mz
κz
∗


EA
0
0
 εx κy
EJy cos2 α + EJz sin2 α (EJy − EJz ) cos α sin α 
.
=


κz
sym.
EJz cos2 α + EJy sin2 α

An offset of the reference point results from the internal force and moment transformation∗ Fx 
 Fx 
= [T ]axial
My
My




Mz
Mz
∗


1
0 0  Fx My=  zas 1 0 .
Mz−yas 0 1

Similarly, the strains and curvatures are transformed according to the relationship∗ εx 
 εx 
−Tκyκy= [T ]axial
.




κz
κz

(8.13)(8.14)(8.15)(8.16)(8.17)

The constitutive relationship becomes Fx 
 εx ∗TMy
κy= [T ]axial [A] [T ]axial




Mz
κz



 εx 
κy= [T ]axial [R]axial [A]† [R]Taxial [T ]Taxial


κz



A11 A12 A13  εx .
κy=
A22 A23 


κz
sym.
A33
164

(8.18)

The values of the coefficients are
A11 = EA

(8.19a)A12 = zas EA
A13 = −yas EA(8.19b)(8.19c)2
A33 = EJz cos2 α + EJy sin2 α + yas
EA(8.19f)2
A22 = EJy cos2 α + EJz sin2 α + zas
EA
A23 = (EJy − EJz ) cos α sin α − yas zas EA(8.19d)(8.19e)Generic to Diagonal Properties. Consider now a generic axial portion of the constitutive properties,
symmetric and usually positive-definite. The constitutive matrix can be transformed to diagonal formby moving the reference point by an offset in the plane of the section, and then by rotating the properties
about axis x.
The offset is applied by the internal forces and moments transformation∗ Fx 
 Fx −1
My
My= [T ]axial




Mz
Mz



1
0 0  Fx My=  −zas 1 0 .
(8.20)
Mz
yas 0 1
The corresponding strains and curvatures transformation is∗ εx 
 εx 
Tκyκy= [T ]axial
.




κz
κz

The transformed constitutive relationship is∗ εx 
 Fx 
−T−1
κyMy= [T ]axial [A] [T ]axial




κz
Mz

A11
A12 − zas A112
A22 − 2zas A12 + zas
A11
=
sym.

(8.21)

∗
A13 + yas A11
 εx 
κyA23 − zas A13 + yas A12 − yas zas A11 
.


2
κz
A33 + 2yas A13 + yas
A11(8.22)The location that decouples the axial force from the bending moments is
yas = −
zas =

A13
A11

A12
A11

165

(8.23a)(8.23b)

When the location of Eq. (8.23) is considered, Eq. (8.22) becomes

∗ 
∗

A11
0
0
 Fx 
 εx =
My
A22 − A212 /A11 A23 − A12 A13 /A11 
κy




Mz
sym.
A33 − A213 /A11
κz
∗
 ∗

A11
0
0
 εx 
κyA∗22 A∗23 
=
.


κz
sym.
A∗33

(8.24)

When a rotation about axis x is considered, the internal forces and moments are transformed according
to the relationship

†

∗
 Fx 
 Fx TMyMy= [R]axial,(8.25)




Mz
Mz

and the strains and curvatures are transformed according to


†
∗
 εx 
 εx 
Tκyκy= [R]axial
.




κz
κz

The constitutive relationship becomes
†

†

 εx 
 Fx 
κyMy= [R]Taxial [A]∗ [R]axial




κz
Mz
†

 †
0
0
A11
 εx κy,=A†22 A†23 


κz
sym.
A†33

(8.26)(8.27)

withA†11 = A∗11

(8.28a)A†22 = A∗22 cos2 α + A∗33 sin2 α + 2A∗23 cos α sin αA†23 = (A∗33 − A∗22 ) cos α sin α + A∗23 cos2 α − sin2 αA†33 = A∗33 cos2 α + A∗22 sin2 α − 2A∗23 cos α sin α.

(8.28b)

The constitutive relationship is diagonal when A†23 = 0, namely ∗1
A22 − A∗33
α = tan−1
2
2A∗23


1
A11 (A22 − A33 ) − A212 + A213
= tan−1.
2
A11 A23 − A12 A13(8.28c)(8.28d)(8.29)

Shear Stress and Strain Properties
Consider now the submatrix represented by the coefficients marked as S in Figure 8.2, under the assumption that it is symmetric, as indicated in Equation (8.30):

 


S11 S12 S13  γy  Fy Fz
S22 S23 γz=
(8.30)




Mx
sym.
S33
κx
166

The orientation of the shear force components about the section axis can be selected in order to decouple
them; by applying the transformation
∗ Fy 
 Fy 
Fz
Fz= [Rshear ]




Mx
Mx



cos β − sin β 0  Fy Fzcos β 0 
=  sin β(8.31)


Mx
0
0
1

The angle that decouples the shear forces is
β=

1
tan−1
2



2S12
S22 − S11

representing a rotation about the axis x of the beam with respect to the origin of the initial reference
frame as shown in Figure 8.3, and the resulting coefficients areGAyGAz
the shear block becomes∗ Fy FxMx

S11 cos2 β + S22 sin2 β − 2S12 sin β cos β

=

2

=

2

S11 sin β + S22 cos β + 2S12 sin β cos β



GAy

= 

sym.

= 

sym.



GAy

0
GAz
0
GAz

(8.32)(8.33)

∗
S13 cos β − S23 sin β  γy 
S13 sin β + S23 cos β 
γz


S33
κx



∗
∗
S13
 γy 
∗ 
S23
γz


S33
κx

The transformation of Equation (8.34) moves the point of application of the shear force of an arbitraryamount {y, z} in the beam section, with respect to the reference frame rotated by β about the axis x of
the beam, as indicated in Figure 8.3:

†

∗
 Fy 
 Fy Fz
Fz= [Tshear ]




Mx
Mx
∗


1 0 0  Fy Fz
=  0 1 0 (8.34)Mx
z −y 1

So the transformed shear block of the constitutive matrix becomes

†

∗
 Fy 
 Fy Fz
Fz= [Tshear ]




Mx
Mx

†
 γy 
Tγz= [Tshear ] [A] [Tshear ](8.35)


κx
†


∗
GAy
0
S13
+ zGAy γy ∗GAz
S23− yGAz
γz
= 


∗
∗
∗
∗
sym.
S33 − yS23 + zS13 + z (S13+ zGAy ) − y (S23− yGAz )κx167

If the position of the point is selected in such a manner that the shear force and the torsional moment
are decoupled, i.e., according to the definition of center of shear force (the point in a beam section where
the application of a transverse force results in no twist)yz
the shear block becomes† Fy 
Fx


Mx



GAy

= 

sym.

= 

sym.



0
GAz

GAy

0
GAz

∗
S23
GAz
S∗
= − 13
GAy

=

†

0
 γy 

0
γz


∗ 2
∗ 2
κx
S33 − S13 /GAy − S23 /GAz



†
0
 γy 
γz
0 


κx
GJ

When the shear and torsional stiffnesses, and the position of the shear strain center and the orientationof the shear axes are available, the shear portion of the stiffness matrix can be computed by reversing
the order of the transformations described in Equations (8.31–8.34), i.e.:




GAy
0
0
S11 S12 S13
S22 S23  = [Rshear ]T [Tshear ]−1  0GAz
0  [Tshear ]−T [Rshear ](8.36)
0
0
GJ
sym.
S33

This expression implies that the stiffness properties are referred to an arbitrary point at {−y, −z} fromthe shear center, in the shear reference frame, followed by a rotation into the section reference frame byan amount −β. The resulting coefficients are
S11= GAy cos2 β + GAz sin2 β

S12= (GAz − GAy ) sin β cos β

S13
S22

= yGAz sin β − zGAy cos β= GAz cos2 β + GAy sin2 β

S23
S33

= yGAz cos β + zGAy sin β= GJ + z 2 GAy + y 2 GAz

Note that the order of the rotation and reference point transportation is reversed with respect to the axial
properties; this is mostly done for convenience in computing the coefficients, because the opposite would
result in more complicated formulas; however, their development the other way ’round is straightforward.
Generic Anisotropic Beam Section
When a generic anisotropic beam section is considered, the partitioning of axial and shear constitutive
properties of Figure 8.2 is no longer possible. The axial and shear straining can be completely andarbitrarily coupled, resulting in a full constitutive matrix of the beam section,


f
m

†

=



Kf ν
Kmν

168

Kf κ
Kmκ

† 

ν
κ

†

,

(8.37)

zas
z
zsc
β
yas

ysc

α
s.c.
a.s.

y

x
Figure 8.3: Beam section169where f and m are the internal force and moment vectors, while ν and κ are the linear and angularstrains. Usually, Kmν ≡ KfTκ , while Kf ν and Kmκ are symmetric.
The reference point or the reference orientation of the constitutive matrix can be changed by asequence of transformations consisting in a rotation and an offset.
The internal force and moment, after a rotation defined by the rotation matrix R, become

∗ 

†
f
R 0
f
=
.
(8.38)
m
0 R
m
Similarly, the strains become


ν
κ

∗

=



R
0

0
R

−T 

=



R
0

0
R



ν
κ

ν
κ
†

†
.

As a consequence, the re-oriented constitutive relationship is

∗ 

† 
T 
∗
f
R 0
Kf ν Kf κ
R 0
ν
=
m
0 R
0 R
κ
Kmν Kmκ

∗

†
†
T
T
ν
RKf ν R
RKf κ R
=
†
†
κ
RKmν
RT RKmκ
RT
∗ 
∗

ν
Kf ν Kf κ.
=κKmν Kmκ(8.39)(8.40)T

The internal moment, after considering an offset o = [0, y, z] of the reference point of the constitutive
properties, becomes m = m∗ + o × f ∗ . The internal force and moment then becomes

 

∗
f
I
0
f
=
.
(8.41)mo× I
mSimilarly, the linear and angular strain vectors become

 
−T 
∗
ν
I
0
ν
=
.
κ
o× I
κ

(8.42)As a consequence, the offset constitutive relationship becomes

∗ 
 



f
I
0
I o×T
ν
Kf ν Kf κ
=
m
o× I
0
I
κ
Kmν Kmκ



∗
∗
T
Kf ν
Kf ν o × + Kf∗ κ
ν
=
∗
∗
∗
o × T + o × Kf∗ κ + Kmκ
o × Kf∗ ν o × T + Kmν
o × Kf∗ ν + Kmν
κ

∗

ν
Kf ν Kf κ=.
(8.43)
κKmν KmκIt might be tempting to find what offset and rotation allows to decouple the force and moment
constitutive properties. This can be sought by defining a generic transformation

 

†
f
I 0
f
=
,
(8.44)
m
T I
m170

such that


f
m



=
=



"

I
T

0
I



Kf ν
Kmν

Kf† ν
†
†
T Kf ν + Kmν

† 

Kf κ
Kmκ

I
0

TT
I



ν
κ



Kf† ν T T + Kf† κ†††
T Kf ν T T + Kmν
T T + T Kf† κ + Kmκ

#

ν
κ



.

(8.45)The expected decoupling results from

−1
†
.
T = −KmνKf† ν(8.46)

However, the resulting transformation T is not guaranteed to have the skew-symmetric structure of o × ,thus the decoupling may not be reducible to an offset.
The reverse transformation is relatively straightforward, after noticing that, according to Eq. (8.41),


f
m

∗

=
=





I
o×

I
−o ×

0
I

−1 

0
I



f
m
f
m





.

(8.47)

So, as expected, it is sufficient to revert the sign of the offset to revert the transformation. The signs of
the constitutive relationship change accordingly.
Locking Correction for Two-Node Beam
The three-node finite volume element has been implemented first, and uses conventional polynomial
parabolic interpolation of the nodal displacements and orientations; the two-node finite volume element
has been introduced later. This latter element presents some shear-locking, which, for linear elastic constitutive laws, may be overcome by correcting the section stiffness matrix in a relatively straightforward
form:
−1

L2
T
TFT
,
(8.48)
K̂ = F +12
where F = K −1 is the compliance matrix of the section, L is the length of the beam, i.e. the distance
between the two reference points obtained by adding the optional offset to the nodes, and
0 ex ×T =00
is the “arm” matrix that appears in the differential equilibrium equation
ϑ/x − T T ϑ + φ = 0,T
where ϑ = f T mT
are the internal forces and moments, while φ are the external forces and moments
per unit span.
There are no provisions to automatically apply the correction when defining the constitutive law of
the section. The two-node beam has been re-implemented using a helicoidal interpolation of the nodal
positions and orientations, to improve its capability to undergo large displacements and relative rotations.
It is activated by using the keyword hbeam2 instead of beam2. However, to reduce the shear-locking effect,
the stiffness properties still need to be manually corrected according to Equation (8.48). The hbeam2
element is experimental, and should be used only for development purposes.
171node 2

3
o2
1

2

RI

3
1

o1

point I

RII
2

node 1point IIo3node 3Figure 8.4: Geometry of the three-node beam element.

8.3.2

Three-node beam element

The three-node beam element is described in detail in [13]. Each of the three points the beam element
connects is referred to a structural node but can have an arbitrary offset to allow high generality inlocating the structural reference line of the beam. Figure 8.4 illustrates the geometry of the three-node
beam element.
The finite volume formulation presented in [13] is used. As a consequence, the internal forces andmoments are evaluatedat two points that are√√ at about midpoint between nodes 1 and 2, and nodes 2
and 3 (at ξ = −1/ 3 ∼= −0.57735 and ξ = 1/ 3 ∼= 0.57735 of a non-dimensional abscissa ξ running fromξ = −1 at node 1 to ξ = 1 at node 3).
So the constitutive properties must be supplied in these points, as well as the orientation matrices RIand RII , that express the orientation of the reference system the constitutive properties are expressedin with respect to the global frame (the axial force is conventionally defined in direction 1). Any of
the supported 6D constitutive laws can be supplied to define the constitutive properties of each beam
section.
The traditional input format is<elem_type> ::= beam3<normal_arglist> ::=<node_1_label> , (Vec3) <relative_offset_1> ,<node_2_label> , (Vec3) <relative_offset_2> ,<node_3_label> , (Vec3) <relative_offset_3> ,(OrientationMatrix) <orientation_matrix_section_I> ,(ConstitutiveLaw<6D>) <constitutive_law_section_I> ,{ same | (OrientationMatrix) <orientation_matrix_section_II> } ,{ same | (ConstitutiveLaw<6D>) <constitutive_law_section_II> }[ , <custom_output> ]The relative_offset_<i>, with i=1,2,3, are the vectors oi , with i=1,2,3, of Figure 8.4.
The orientation matrices orientation_matrix_section_<j>, with j=I,II, are the section orientation
matrices Rj , with j=I,II, of Figure 8.4.
172

The first keyword same, alternative to the orientation_matrix_section_II, means that the sameorientation defined for the first point will be used for the second point.
The second keyword same, alternative to the constitutive_law_section_II, means that the same
constitutive law defined for the first point will be used for the second point.
If any of the constitutive laws is either viscous or viscoelastic, the viscoelastic variant of the beam
element is used. Otherwise, the elastic variant is used.
A more complete input format is<elem_type> ::= beam3<normal_arglist> ::=<node_1_label> ,[ position , ] (Vec3) <relative_offset_1> ,[ orientation , (OrientationMatrix) <relative_orientation_1> , ]<node_2_label> ,[ position , ] (Vec3) <relative_offset_2> ,[ orientation , (OrientationMatrix) <relative_orientation_2> , ]<node_3> ,[ position , ] (Vec3) <relative_offset_3> ,[ orientation , (OrientationMatrix) <relative_orientation_3> , ]{ (OrientationMatrix) <orientation_matrix_section_I>| from nodes } ,(ConstitutiveLaw<6D>) <constitutive_law_section_I> ,{ same| (OrientationMatrix) <orientation_matrix_section_II>| from nodes } ,{ same| (ConstitutiveLaw<6D>) <constitutive_law_section_II> }[ , <custom_output> ]This format is a superset of the traditional one, which is extended by adding the possibility to set relative
node orientations that can be subsequently used to interpolate the orientation matrices at the evaluation
points, by providing the keyword from nodes instead of the matrix. If the keyword same is used for thesecond evaluation point, the same method is used to compute the orientation matrix.
The custom_output optional data consists in<custom_output> ::= custom output , <custom_output_flag> [ , ... ]The values of custom_output_flag are defined in Section 5.2.12.
Flags add up to form the custom output request. Flags may not be repeated. Strain rates are only
available from viscoelastic beams. By default, only forces are output, to preserve compatibility with theoriginal output format. The custom output is only available in NetCDF format; see Section C.1.4.
As an example, a simple beam element, with diagonal section stiffness matrix is presented:
set: integer beam_label = 1000;
set: integer beam_node1 = 2001;
set: integer beam_node2 = 2002;
set: integer beam_node3 = 2003;
set: real EA = 1e6;
# N
set: real GAy = .6e6; # N
set: real GAz = .6e6; # N
set: real GJ = 1.e3; # Nm^2
173

set: real EJy = 2.e3; # Nm^2
set: real EJz = 1.e4; # Nm^2
beam3: beam_label,beam_node1, reference, node, null,
beam_node2, reference, node, null,
beam_node3, reference, node, null,eye,linear elastic generic, diag,
EA, GAy, GAz, GJ, EJy, EJz,
same,
same;
A not-so-simple beam section, where the center of axial strain and the shear center are not coincident,
is illustrated below. The node offset is used to align the reference line with the shear center, and theaxial strain center offset is used in the constitutive matrix:
set: integer beam_label = 1000;
set: integer beam_node1 = 2001;
set: integer beam_node2 = 2002;
set: integer beam_node3 = 2003;
set: real EA = 1e6;
# N
set: real GAy = .6e6; # N
set: real GAz = .6e6; # N
set: real GJ = 1.e3;# Nm^2
set: real EJy = 2.e3; # Nm^2
set: real EJz = 1.e4; # Nm^2
set: real yas = 2.e-2; # m
set: real zas = 1.e-2; # m
set: real ysc = 4.e-2; # m
set: real zsc = 2.e-2; # m
set: real y = yas-ysc; # compute the axial strain center
set: real z = zas-zsc; # wrt/ the shear center
beam3: beam_label,beam_node1, reference, node, 0.,ysc,zsc,
beam_node2, reference, node, 0.,ysc,zsc,
beam_node3, reference, node, 0.,ysc,zsc,
eye,linear elastic generic, sym,
EA, 0., 0., 0., z*EA,-y*EA,
GAy, 0., 0., 0.,0.,GAz, 0., 0.,0.,
GJ, 0.,
0.,
EJy+z^2*EA, -z*y*EA,
EJz+y^2*EA,
same,
same;
A piezoelectric actuator beam element is available; an arbitrary linear piezoelectric actuation matrix
is required, together with the labels of the abstract nodes that represent the input signal tensions, as
follows:174<normal_arglist> ::=<node_1_label> , (Vec3) <relative_offset_1> ,<node_2_label> , (Vec3) <relative_offset_2> ,<node_3_label> , (Vec3) <relative_offset_3> ,(OrientationMatrix) <orientation_matrix_section_I> ,(ConstitutiveLaw<6D>) <constitutive_law_section_I> ,{ same | (OrientationMatrix) <orientation_matrix_section_II> } ,{ same | (ConstitutiveLaw<6D>) <constitutive_law_section_II> } ,piezoelectric actuator ,<electrodes_number> ,<abstract_node_label_list> ,(Mat6xN) <piezoelectric_matrix_I> ,{ same | (Mat6xN) <piezoelectric_matrix_II> }[ , <custom_output> ]where the abstract_node_label_list is the list of the labels of the abstract nodes that represent theelectrodes.
Private Data

The following data are available:

1. "ex" axial strain
2. "ey" shear strain (local axis 2)
3. "ez" shear strain (local axis 3)
4. "kx" curvature about local axis 1 (torsional)
5. "ky" curvature about local axis 2 (bending)
6. "kz" curvature about local axis 3 (bending)
7. "Fx" axial force
8. "Fy" shear force (direction 2)
9. "Fz" shear force (direction 3)
10. "Mx" moment about local axis 1 (torsional)
11. "My" moment about local axis 2 (bending)
12. "Mz" moment about local axis 3 (bending)
13. "Xx" absolute position component 1
14. "Xy" absolute position component 2
15. "Xz" absolute position component 3
16. "Phix" absolute orientation vector component 1
17. "Phiy" absolute orientation vector component 2
18. "Phiz" absolute orientation vector component 3
19. "Omegax" absolute angular velocity component 1
175node 2
3
o2

1

2

RI
o1

point I
node 1Figure 8.5: Geometry of the two-node beam element.
20. "Omegay" absolute angular velocity component 2
21. "Omegaz" absolute angular velocity component 3
22. "ePx" axial strain rate
23. "ePy" shear strain rate (local axis 2)
24. "ePz" shear strain rate (local axis 3)
25. "kPx" curvature rate about local axis 1 (torsional)
26. "kPy" curvature rate about local axis 2 (bending)
27. "kPz" curvature rate about local axis 3 (bending)
Each string is prefixed by "pI." or "pII." to specify data related to either the first or the second point:"pI.Fx""pII.kz"# axial force at point I# bending curvature about local axis 3 at point II

Private data related to point I are numbered from 1 to 27; private data related to point II are numberedfrom 28 to 54.

8.3.3

Two-node beam element

Similar considerations apply to the two-node beam. Its geometry is illustrated in Figure 8.5.
The syntax is<elem_type> ::= beam2<normal_arglist> ::=<node_1_label> , (Vec3) <relative_offset_1> ,<node_2_label> , (Vec3) <relative_offset_2> ,(OrientationMatrix) <orientation_matrix_section_I> ,(ConstitutiveLaw<6D>) <constitutive_law_section_I>[ , piezoelectric actuator ,<electrodes_number> ,<abstract_node_label_list> ,(Mat6xN) <piezoelectric_matrix_I> ][ , <custom_output> ]176

A more complete form is<elem_type> ::= beam2<normal_arglist> ::=<node_1_label> ,[ position , ] (Vec3) <relative_offset_1> ,[ orientation , (OrientationMatrix) <relative_orientation_1> , ]<node_2_label> ,[ position , ] (Vec3) <relative_offset_2> ,[ orientation , (OrientationMatrix) <relative_orientation_2> , ]{ (OrientationMatrix) <orientation_matrix_section_I>| from nodes } ,(ConstitutiveLaw<6D>) <constitutive_law_section_I>[ , piezoelectric actuator ,<electrodes_number> ,<abstract_node_label_list> ,(Mat6xN) <piezoelectric_matrix_I> ][ , <custom_output> ]Private Data. The same private data indicated for the beam3 element is available (see Section 8.3.2).
No prefix must be specified ("pI." is implicit).
Example.

As an example, a simple beam element, with diagonal section stiffness matrix is presented:

set: integer beam_label = 1000;
set: integer beam_node1 = 2001;
set: integer beam_node2 = 2002;
set: real L = .4;# m
set: real EA = 1e6;
# N
set: real GAy = .6e6; # N
set: real GAz = .6e6; # N
set: real GJ = 1.e3; # Nm^2
set: real EJy = 2.e3; # Nm^2
set: real EJz = 1.e4; # Nm^2
beam2: beam_label,beam_node1, reference, node, null,
beam_node2, reference, node, null,eye,linear elastic generic, diag,
EA, 1./(1./GAy+L^2/12./EJz), 1./(1./GAz+L^2/12./EJy),
GJ, EJy, EJz;
Note that the shear terms have been naı̈vely inverted to eliminate shear locking, according to Equation (8.48).

8.3.4

OutputThe output related to beam elements is contained in a file with extension .act; for each time step, theoutput is written for those element it was requested. The internal forces and moments are computed

177from the interpolated strains along the beam by means of the constitutive law, at the evaluation points.
The format is:• column 1: the label of the beam;• columns 2–4: the three components of the force at the first evaluation point, oriented according to
the reference frame of that beam section;• columns 5–7: the three components of the moment at the first evaluation point, oriented according
to the reference frame of that beam section.
The three-node beam element generates six additional columns:• columns 8–10: the three components of the force at the second evaluation point, oriented according
to the reference frame of that beam section;• columns 11–13: the three components of the moment at the second evaluation point, oriented
according to the reference frame of that beam section.
More detailed output is allowed when using NetCDF; see Section C.1.4 for details.

8.3.5

Notes

Two-node beam elements should be used with care.

8.4

Body

The body element describes a lumped rigid body when connected to a regular, 6 degree of freedom
structural node, or a point mass when connected to a rotationless, 3 degree of freedom structural node.
<elem_type> ::= body<normal_arglist> ::= <node_label> ,{ <one_body>| <one_pointmass>| variable mass , <one_vm_body>| condense , <num_masses> , { <one_body> | <one_pointmass> } [ , ... ] }<one_body> ::=(real) <mass> ,(Vec3)<relative_center_of_mass> ,(Mat3x3) <inertia_matrix>[ , inertial ,{ node | (OrientationMatrix) <orientation_matrix> } ]<one_pointmass> ::=(real) <mass># when <node_label> is a displacement node

<one_vm_body> ::=<mass> ,(DriveCaller)(TplDriveCaller<Vec3>) <relative_center_of_mass> ,(TplDriveCaller<Mat3x3>) <variable_mass_inertia_matrix> ,(TplDriveCaller<Mat3x3>) <variable_geometry_inertia_matrix>178

If only one mass is defined, the first method should be used. Otherwise, many masses can be referredto the same element by means of the keyword condense, followed by the number of expected masses
num_masses. The format of each sub-mass is the same as for the single mass input (actually, whencondense is not supplied, num_masses is assumed to be 1).
The inertia_matrix is always referred to the center of mass of the mass that is being added. It
can be rotated locally by means of the extra orientation_matrix supplied after the (optional) keyword
inertial. The keyword node corresponds to the default, i.e. the inertia matrix is assumed to be input
in the node reference frame.
Note: in many commercial finite element software, the off-diagonal elements of the inertia matrix aredefined with a minus sign; for instance, NASTRAN’s CONM2 lumped inertia card expects the values as
indicated in Figure 8.6. However, the matrix is reconstructed as


M


M
symmetric




M


NASTRAN ::= 

I11




−I21
I22
−I31 −I32 I33
see for instance NASTRAN V70.5 Quick Reference Guide for details.
On the contrary, MBDyn directly reads the matrix that will be used in the computation, i.e. without
the minus signs in the off-diagonal terms, as reported below:
i11 i12 i13i22 i23 
MBDyn ::= 
sym.
i33

So:

i11 = I11
i22 = I22
i33 = I33
i12 = −I21
i13 = −I31
i23 = −I32
The variable mass variant requires the mass, mass, the location of the center of mass with respect
to the node in the reference frame of the node, relative_center_of_mass, and the inertia matrix about
the center of mass must be provided in form of differentiable drive callers of the specific dimension. The
inertia matrix is logically split in two contributions: the first one, variable_mass_inertia_matrix, isrelated to the variation of mass; the second one, variable_geometry_inertia_matrix, is related to thechange of geometry at fixed instantaneous value of the mass. The instantaneous inertia matrix with$.......2.......3.......4.......5.......6.......7.......8.......
CONM2
EID
G
CID
M
X1
X2
X3
I11
I21
I22
I31
I32
I33
Figure 8.6: NASTRAN CONM2 card

179

respect to the node, in the reference frame of the node, is computed as
J˜n = variable_mass_inertia_matrix+ variable_geometry_inertia_matrix+ mass · relative_center_of_mass × relative_center_of_mass × T .

(8.49)(8.50)(8.51)

See the technical manual for more details.
The inertia properties of the model can be logged and verified by means of the inertia keyword, as
detailed in Section 8.17.3.
Private Data

The following data are available:

1. "E" kinetic energy
2. "V" potential (i.e. gravitational) energy
3. "m" mass
Example.
set: integer NODE_LABEL = 100;
set: integer BODY_LABEL = 100;# single mass example
body: BODY_LABEL, NODE_LABEL,
8.,
reference, node, 0., 0., 0.,diag, 4.8, 4.8, .4;# mass# c.m. offset# inertia tensor# three masses example (equivalent to the previous one)body: BODY_LABEL, NODE_LABEL,
condense, 3,4.,# mass 1 (mid)reference, node, 0., 0., 0.,# c.m. offset 1
diag, .4, .4, .2,# inertia tensor 1
2.,# mass 2 (top)reference, node, 0., 0., 1.,# c.m. offset 2
diag, .2, .2, .1,# inertia tensor 2
2.,# mass 3 (bottom)
reference, node, 0., 0., -1., # c.m. offset 3
diag, .2, .2, .1;# inertia tensor 3

8.5

Bulk Elements

The bulk element is intended as a sort of NASTRAN’s CELAS card, that can be used to apply a stiffness
term on an arbitrary degree of freedom. Extensions are planned to different kind of elements. The syntaxof the bulk element is:<elem_type> ::= bulk
<normal_arglist> ::= <bulk_type> , <bulk_arglist>
At present only the stiffness spring type is available.
1808.5.1

Stiffness spring<bulk_type> ::= stiffness spring<bulk_arglist> ::=(NodeDof) <dof> ,(DriveCaller) <stiffness_drive>
The equation related to the desired dof of the linked node is added a contribution based on the value ofthe desired degree of freedom (even the derivative can be used) multiplied times the stiffness.
Note: this family of elements has been partially superseded by the genel elements, which allow moregenerality.

8.6

CoupleA variant of force; see Section 8.8 for details.

8.7Electric Elements

electric elements are those elements that model electric and electronic devices, dealing with abstract
degrees of freedom more than with electric ones (from the program’s point of view they are exactly thesame, the difference is only semantic). The true electric elements, such resistors, switches and so on, areclassified as electric bulk elements. The syntax for electric elements is:<normal_arglist> ::= <electric_type> , <electric_arglist>
The electric elements implemented at present are:• accelerometer• displacement• motor• discrete control
The syntax is described in the following.

8.7.1

Accelerometer<electric_type> ::= accelerometer<electric_arglist> ::={ translational | rotational } ,<struct_node_label> ,<abstract_node_label> ,((Unit)Vec3) <measure_direction>[ , position , (Vec3) <position> ]The position is optional; it is meaningless for rotational accelerometers. The measure is taken alongor about direction measure_direction; the vector is internally normalized to unity.
Legacy element: accelerometer with built-in transfer function181

<electric_type> ::= accelerometer<electric_arglist> ::= <struct_node_label> ,<abstract_node_label> ,((Unit)Vec3) <measure_direction> ,(real) <omega> ,(real) <tau> ,(real) <csi> ,(real) <kappa>
The label struct_node_label defines the node whose acceleration is being measured; the label abstract_node_label
defines the abstract node that will receive the output signal. An electric node can be used as well(?). The measure is taken along direction measure_direction; the vector is internally normalized tounity. The transfer function of the accelerometer is:e0
tau · s= kappa ·a(1 + tau · s) (1 + 2 · csi · (s/omega) + (s/omega)2 )where e0 is the output signal, a is the input (the acceleration) and s is Laplace’s variable.

8.7.2

Displacement<electric_type> ::= displacement<electric_arglist> ::=<struct_node_1_label> , (Vec3) <relative_offset_1> ,<struct_node_2_label> , (Vec3) <relative_offset_2> ,<abstract_node_label>d = xb + o b − xa − o a√x = dT d
The value x is added to the right-hand side of the equation of the abstract node.

8.7.3

Motor

<electric_type> ::= motor<electric_arglist> ::=<struct_node_1_label> ,<struct_node_2_label> ,((Unit)Vec3) <direction_relative_to_node_1> ,<abstract_node_1_label> ,<abstract_node_2_label> ,(real) <dG>,(real) <dL>,(real) <dR>
[ , initial current , <i_0> ]182(8.52a)(8.52b)ω = eT (ω2 − ω1 )(8.53a)V = V2 − V1di
V = dL + dR i + dG ω
dt
c1 = −e dG ic2 = e dG i

(8.53b)i1 = −ii2 = i(8.53f)(8.53g)(8.53c)(8.53d)(8.53e)The motor applies an internal torque about direction e = direction_relative_to_node_1 to both thestructural nodes it is connected to. The direction e is internally normalized to unity. It also applies acurrent to both the electrical nodes it is connected to.
The element assumes that the relative orientation between nodes 1 and 2 can only change by rotating
about direction e, so appropriate joints must be in place.

8.7.4

Discrete control

This element implements a discrete equation that can be used to represent the behavior of a discrete
linear controller. The control matrices can be either provided, or identified during the simulation byrecursive least squares.
Assume the original system consists in a generic nonlinear process that depends on a set of measuresy and a set of inputs u at a finite number of time steps past the current time, tk , namelyf (yk−i , uk−j ) = 0,(8.54)

with i = 0, p and j = 0, q. Only yk is unknown, and thus represents the output of the process. It is
assumed that uk is known, and represents an input to the process.
This element implements a controller of the form
XX
Acj yk−j ,(8.55)
Bci uk−i +
uck =
j=1,q

i=1,p

where uck is the control input that must be applied at time tk in addition to any exogenous input uek ,so that uk = uek + uck . The control input uck can only depend on the measures and the inputs at
previous time steps.
Note that the symbols commonly used for discrete systems are here reversed, since the element isintended to compute the control signals at time tk , uck , based on the previous value of the controls,
uk−i = ue(k−i) + uc(k−i) , and on the previous value of the motion of the original system, yk−j ; ue
indicates a generic measured exogenous input to the system to be controlled.
The order p and q of the auto-regressive and exogenous portions of the system can differ. In detail,the order p can be zero; in that case, the system implements a finite impulse response function.
This element is not self-starting; it assumes that both inputs and outputs at times before the start
time are zero.
The so-called “output” signals, indicated with y, can be instances of either NodeDof or DriveCaller
objects. The so-called “input” signals, indicated with u, must be instances of NodeDof object. Thisimplies that instances of NodeDof objects need the corresponding equations to be (at least) staticallydefined. In fact, the discrete control element uses the “output” NodeDof values, the y, to compute thecorresponding “inputs”, the u. The latter are substantially added as a right-hand side to the equations of
the corresponding NodeDof objects. As a consequence, other elements must contribute to the left-handside of all the NodeDof equations in order to make them defined.
183

uk−2

yk−2

uk−1

yk−1
B

uk

A

uc

yk

ue

f

111
000
000
111

K=1

111
000
000
111

K=1

Figure 8.7: Discrete control layout.
Note that other elements may also contribute to the right-hand side of the “input” NodeDof object. Specifically, other abstract forces may contribute to their value. In that case, the additional
forces represent the exogenous inputs. They are considered as part of the input used by the discrete
control element, since the value uk to be used in the control equation is extracted from the value of thecorresponding NodeDof objects.
Figure 8.7 illustrates the behavior of the element. The typical suggested approach is illustrated laterin an example.
The syntax is<electric_type> ::= discrete control<electric_arglist> ::= <num_outputs> , <num_inputs> ,<order_A> [ , fir , <order_B> ] ,<num_iter> ,<control_data> ,outputs ,(ScalarValue) <output_value>[ , scale , (DriveCaller) <scale> ][ , ... ] ,inputs ,(NodeDof) <input_dof>[ , ... ]<output_value> ::={ [ node dof , ] (NodeDof) <output_dof>| drive , (DriveCaller) <output_drive> }The lists of the output and input dofs follows. The inputs do not require the order_A and order_B
fields, since they are simply used to compute the control forces, and thus identify an equation. order_B184

defaults to order_A unless a fir control is chosen.
The control_data has the syntax:<control_data> ::= <control_type> , <control_arglist>
At present only a simple form of control is implemented. Other types to come are system identification,
both recursive and one-shot, and adaptive control, with different models and schemes, all based on
Generalized Predictive Control (GPC) and Deadbeat Control. The control_data syntax is:<control_data> ::={ control , " <control_matrices_file> "| identification , <identification_data>| adaptive control , <adaptive_control_data> }Control
The file control_matrices_file must contain the matrices ac , bc of the control in plain text (as generated by Matlab, for instance):
ac1 ,
...,
acp ,
bc1 ,
...,
bcp
where p is the order_A of the controller and the matrices ac have num_inputs rows and num_outputs
columns, while the matrices bc have num_inputs rows and num_inputs columns.
Identification<identification_data> ::={ arx | armax }[ , <forgetting_factor> ][ , <persistent_excitation> ][ , file , " <output_file_name> " ]The forgetting factor is defined as<forgetting_factor> ::=forgettingfactor ,{ const , <d>| dynamic , <n1> , <n2> , <rho> , <fact> , <kref> , <klim> }The default is a const forgetting factor with d = 1.
The persistent_excitation is defined as<persistent_excitation> ::=excitation , (DriveCaller) <excitation_drive> [ , ... ]where num_inputs instances of excitation_drive must be defined. By default, no persistent excitation
is defined.

185

Adaptive control
The adaptive_control_data card is<adaptive_control_data> ::=[ { arx | armax } , ][ periodic , <periodic_factor> , ]{ gpc ,
<prediction_advancing_horizon> ,<control_advancing_horizon> ,<prediction_receding_horizon> ,[ prediction weights , <Wi> [ , ... ] , ][ control weights , <Ri> [ , ... ] , ](DriveCaller) <weight_drive>| deadbeat ,<prediction_advancing_horizon> ,<control_advancing_horizon> }[ , <forgetting_factor> ][ , <persistent_excitation> ][ , trigger , (DriveCaller) <trigger_drive> ][ , desired output , (DriveCaller) <output_drive> [ , ... ] ][ , file , " <file_name> " ]The default is arx.
The meaning of the keywords is:• the periodic_factor defaults to 0;• if the keyword prediction weights is present, a number of weights Wi equal to(prediction_advancing_horizon − prediction_receding_horizon)
must be supplied. If the keyword control weights is present, a number of weights Ri equal tocontrol_advancing_horizon must be supplied. If the keywords are not defined, the corresponding
weights default to 1;• the desired output option requires num_outputs drives to be defined.
Private Data
The following data are available:
1. "u[<idx>]" value of the idx-th control output.
ExamplesConsider the case of a discrete controller that computes a set of control signals uk by adding to theirvalue at the previous step, uk−1 , a contribution coming from some measure yk−1 . The control matricesare
a11 a12(8.56a)Ac1 =a21 a22


1 0
Bc1 =
(8.56b)0 1
They are defined in the control data file discretecontrol.dat as186a_11 a_12
a_21 a_22
1.0 0.0
0.0 1.0
The model consists in two abstract nodes for the control input NodeDof objects. They need to be
grounded. This can be formulated by using a spring support genel for each abstract node, characterized by a unit spring coefficient, such that1 · xu1 = u1

1 · xu2 = u2

(8.57a)(8.57b)Moreover, assume that the first measure, y1 , comes from a NodeDof object, while the second one, y2 ,comes from a DriveCaller object. The equation corresponding to y1 must be appropriately grounded
as well, for example by means of yet another spring support genel. This is outside the scope of thepresent example, so it will assume the output nodes are defined appropriately.
The model isset: integer U_1 = 1;
set: integer U_2 = 2;
set: integer Y_1 = 11;# ...
abstract: U_1;
abstract: U_2;
# ...
genel: U_1, spring support,
U_1, abstract, algebraic,
linear elastic, 1.;
genel: U_2, spring support,
U_2, abstract, algebraic,
linear elastic, 1.;
electric: 99, discrete control,
2,# number of ‘outputs’ y
2,# number of ‘inputs’ u
1,# order of output matrices A (same for input matrices B)
1,# update every iteration
control, "discretecontrol.dat",
outputs,
node dof, Y_1, abstract, algebraic, scale, 1.e-3,
drive, sine, .5, 2*pi, 1., forever, 0, scale, 1.e-3,
inputs,
U_1, abstract, algebraic,
U_2, abstract, algebraic;

8.8

Force

The force element is a general means to introduce a right-hand side to the equations, i.e. an explicit
contribution to the equations. There is a basic distinction between abstract and structural forces: abstract forces apply to arbitrary equations, while structural forces (and couples) are specific to structuralnodes and have a spatial characterization. Essentially, structural forces have three components that may
187depend on arbitrary parameters (usually the simulated time), and a location in space. Structural couples
have three parameter-dependent components. The syntax of the force element is:<elem_type> ::= { force | couple }<normal_arglist> ::= <force_type> , <force_arglist><force_type> ::={ abstract [ internal ]| { absolute | follower | total } [ internal ]| modal| external { structural | modal } [ mapping ] }# force# force, couple# force# force

The abstract force_type applies to generic equations;
The structural force types (absolute, follower, total) only apply to equilibrium equations related
to structural nodes. The couple element can only be structural. It is discussed in this section becauseof its input syntax commonality with the structural force elements.
The modal force_type applies to equations related to a modal element.
The external structural and the external modal types are essentially used to provide an easy to
use interface for coupling with external software in a loose or tight manner.

8.8.1

OutputThe output is discussed according to the types of forces. The label of the element is output first in all
the cases.

8.8.2

Abstract force<elem_type> ::= force<force_type> ::= abstract<force_arglist> ::=(NodeDof)<dof> ,
(DriveCaller) <force_magnitude>
the dof field is a normal NodeDof; no order is required since the force simply applies to the equation
related to the node, regardless of the order.
Output
The format is:• the label of the element;• the label of the node1 the force is applied to;• the value of the force.

1 Since the abstract force type can connect to NodeDof, information provided here can be partial if the NodeDof actually

represents a component of a node with more than one degree of freedom.

188

8.8.3

Abstract reaction force<elem_type> ::= force<force_type> ::= abstract internal<force_arglist> ::=(NodeDof)<dof_1> ,<dof_2> ,(NodeDof)(DriveCaller) <force_magnitude>
the dof_1 and dof_2 fields are normal NodeDof but no order is required since the force simply applies
to the equations related to the nodes, regardless of the order, with opposite magnitudes.
Output
The format is:• the label of the element;• the label of the first node2 the force is applied to;• the value of the force applied to the first node;• the label of the second node3 the force is applied to;• the value of the force applied to the second node (opposite to that applied to the first node).

8.8.4

Structural force<elem_type> ::= force<force_type> ::= { absolute | follower }<force_arglist> ::=<node_label> ,position , (Vec3) <relative_arm> ,(TplDriveCaller<Vec3>) <force_value><force_type> ::= total<force_arglist> ::=<node_label>[ , position , (Vec3) <relative_arm> ][ , force orientation , (Mat3x3) <force_orientation> ][ , moment orientation , (Mat3x3) <moment_orientation> ][ , force , (TplDriveCaller<Vec3>) <force_value> ][ , moment , (TplDriveCaller<Vec3>) <moment_value> ]2 See footnote 1.
3 See footnote 1.

189

The vector relative_arm defines the offset with respect to the node of the point where the force isapplied. The drive force_value defines the value of the force as a function of time. The total force isintrinsically follower. See also the total joint (Section 8.12.46).
The force and the moment applied to node node_label are thus
• absolute force element:f = force_value(8.58a)m = (R · relative_arm) × force_value;(8.58b)• follower force element:
f = R force_value(8.59a)m = R (relative_arm × force_value) ;(8.59b)• total force element:
f = R force_orientation · force_valuem = R (relative_arm × (force_orientation · force_value)+ moment_orientationmoment_value) ;R is the orientation matrix of the node node_label.
Example.
force: 10, absolute,
1000,
position, .5, 0., 0.,
1., 0., 0.,const, 25.;
force: 20, follower,
2000,
position, null,component,
const, 0.,
ramp, 10., 0., 1., 0.,file, 5, 2;
force: 30, total,
2000,
position, .5, 0., 0.,force orientation, eye,moment orientation, eye,1., 0., 0.,const, 25.,component,
const, 0.,
ramp, 10., 0., 1., 0.,file, 5, 2;

190(8.60a)(8.60b)Known issues. The direction of a force (a TplDriveCaller<Vec3>) by default is interpreted in thereference frame of the node the force acts upon. When using the single style of TplDriveCaller<Vec3>,
one can refer to another reference system (the direction specified by the user is automatically transformed
from that reference frame to the one of the node). However, this causes an ambiguity when the default
single specifier is omitted, rather than explicitly written. A reference system different from the default
one can be specified using the syntax
single , reference , <reference_frame> ,(Vec3) <force_value>
Note that1., 0., 0.

# equivalent to single, 1., 0., 0.

single, 1., 0., 0.

# equivalent to 1., 0., 0.

andare equivalent. However,reference, global, 1., 0., 0.

# incorrect!

is incorrect; the correct form issingle, reference, global, 1., 0., 0.

# correct

Currently, a reference frame different from that of the node cannot be specified for other styles of templatedrive caller (e.g. the component style).
Output
The format is:• the label of the element;• the label of the node the force is applied to;• the three components of the force;• the arm of the force, in the global frame (i.e. referred to point {0, 0, 0} and oriented as the global
frame)

8.8.5

Structural internal force<elem_type> ::= force<force_type> ::= { absolute | follower } internal<force_arglist> ::=<node_1_label> ,position , (Vec3) <relative_arm_1> ,<node_2_label> ,position , (Vec3) <relative_arm_2> ,(TplDriveCaller<Vec3>) <force_value>191

<force_type> ::= total internal<force_arglist> ::=<node_1_label> ,[ position , (Vec3) <relative_arm_1> , ][ force orientation , (Mat3x3) <force_orientation_1> , ][ moment orientation , (Mat3x3) <moment_orientation_1> , ]<node_2_label>[ , position , (Vec3) <relative_arm_2> ][ , force orientation , (Mat3x3) <force_orientation_2> ][ , moment orientation , (Mat3x3) <moment_orientation_2> ][ , force , (TplDriveCaller<Vec3>) <force_value> ][ , moment , (TplDriveCaller<Vec3>) <moment_value> ]The format is basically identical to the previous case, except for the definition of the second node.
Output
The format is:• the label of the element;• the label of the first node the force is applied to;• the three components of the force applied to the first node;• the arm of the force with respect to the first node, in the global frame (i.e. referred to point {0, 0, 0}
and oriented as the global frame).
• the label of the second node the force is applied to;• the three components of the force applied to the second node (opposite to that applied to the firstnode);• the arm of the force with respect to the second node, in the global frame (i.e. referred to point{0, 0, 0} and oriented as the global frame).
Example.
# constant structural force
force: 1, absolute,
10, position, null,0., 0., 1.,const, 100.;# constant structural internal force
force: 1, absolute internal,
10, position, null,
20, position, null,
0.,0.,1.,
const, 100.;192

8.8.6Structural couple

The structural couple is defined by using couple as elem_type.
<elem_type> ::= couple<force_type> ::= { absolute | follower }<force_arglist> ::=<node_label> ,[ position , (Vec3) <relative_arm> , ](TplDriveCaller<Vec3>) <couple_value>
The vector relative_arm defines the offset with respect to the node of the point where the couple isapplied. It is not used in the analysis (since it makes no sense), but it can be optionally provided for
future reference (e.g. for the visualization of the couple). The drive couple_value defines the value ofthe couple as a function of time.
The moment applied to node node_label is thus
• absolute couple element:m = couple_value(8.61)

m = R · couple_value(8.62)• follower couple element:

R is the orientation matrix of the node node_label.
Output
The format is:• the label of the element;• the label of the node the couple is applied to;• the three components of the couple.

8.8.7

Structural internal couple

The structural couple is defined by using couple as elem_type.
<elem_type> ::= couple<force_type> ::= { absolute | follower } internal<force_arglist> ::=<node_1_label> ,[ position , (Vec3) <relative_arm_1> , ]<node_2_label> ,[ position , (Vec3) <relative_arm_2> , ](TplDriveCaller<Vec3>) <couple_value>
The format is basically identical to the previous case, except for the definition of the second node.
193

Output
The format is:• the label of the element;• the label of the first node the couple is applied to;• the three components of the couple applied to the first node;• the label of the second node the couple is applied to;• the three components of the couple applied to the second node (opposite to that applied to thefirst node);
Note: by using a dof, a node or an element drive, a simple feedback control can be easily implemented.
Note however that the dependence of a force on some internal state does not result in adding thecorresponding contribution to the Jacobian matrix: the force remains explicit. Their improper use may
result in missing convergence, or singularity of the Jacobian matrix of the problem.

8.8.8

Modal

This element allows to define a set of generalized forces acting on the equations related to the generalized
variables of a modal joint element.
<elem_type> ::= force<force_type> ::= modal<force_arglist> ::=<modal_label> ,[ list , <number_of_modes> , <mode1> [ , ... ] , ](DriveCaller) <force1>[ , resultant , (Vec3) <f> , (Vec3) <m> ][ , ... ]It requires the label of the modal joint it is connected to, modal_label. If the optional keyword list
is given, the number of excited modes number_of_modes and the list of the excited modes is expected,
otherwise it assumes all modes of the modal_label modal joint will be excited.
A list of drive callers (see Section 2.6). that provide the excitation value for each mode is required
last. If the keyword list was given, the drive callers must be number_of_modes, otherwise they must
be as many as the modes of the excited modal joint element.
If the modal joint element is connected to a modal node instead of being clamped to the ground, theoptional keyword resultant is allowed for each mode drive caller. The keyword resultant is followedby two 3 × 1 vectors containing the resultant force and moment associated to the related mode.
If the keyword list was given, the mode numbers must be the actual mode numbers defined in the
FEM model.
Example. In this example, all the modes available in the FEM data file are used by the modal joint,
and all the modes are excited by the modal force

194joint: MODAL_JOINT, modal, MODAL_NODE,
5,# number of modes
from file,"model.fem",0;# no interface nodes
force: MODAL_FORCE, modal, MODAL_JOINT,
const, 5.,const, 10.,
const, 1.,const, -1.,
const, -3.;
In this example, only three modes of the same FEM data file of the previous example are used by
the modal joint; only the last mode is excited by the modal force
joint: MODAL_JOINT, modal, MODAL_NODE,
3,# number of modes
list, 1, 3, 5,
from file,"model.fem",0;# no interface nodes
force: MODAL_FORCE, modal, MODAL_JOINT,
list, 1,# only one mode is excited5,# it is mode #5 in "model.fem"
const, -3.;Note that the mode is indicated by its number in the FEM data file.

8.8.9

External forces

External forces are elements that allow to communicate with an external software that computes forces
based on information on the kinematics of the model.
Different communication schemes are supported. By default, communication occurs via files. Currently supported communication schemes are<external_force_communicator> ::= { <file> | <edge> | <socket> }<file> ::=# the default" <input_file_name> " [ , unlink ] ," <output_file_name> " [ , no clobber ][ , <common_parameters> ]<edge> ::= edge ," <flag_file_name> " ," <data_file_name> "[ , <common_parameters> ]<socket> ::= socket ,[ create , { yes | no } , ]{ path , <path> | port , <port> [ , host , <host> ] }[ , <common_parameters> ]195

<common_parameters> ::= <common_parameter> [ , ... ]<common_parameter> ::={ sleep time , <sleep_time>| precision , { default | <digits> }# not valid for socket| coupling , { staggered | loose | tight | <coupling_steps> }| send after predict , { yes | no } }File communicator
input_file_name is the name of the file MBDyn expects to find with the values of the force. The
content depends on the purpose it is used for. The optional keyword unlink indicates that MBDyn is
supposed to unlink the file as soon as it is ready to read another one, as a primitive form of inter-process
communication.
output_file_name is the name of the file MBDyn creates each time it intends to communicate thekinematics of the model to the external software. The contents depend on the purpose it is used for.
The option no clobber indicates that MBDyn is supposed to wait until the external software removed
the file before generating a new one, as a primitive form of inter-process communication.
EDGE communicator
This communicator has been developed in cooperation with Luca Cavagna, to support communication
with FOI’s EDGE.
The file flag_file_name is used to synchronize the communication between the processes. The same
file is truncated and reused by both processes. The syntax of the file changed since EDGE 5.1; this change
is reflected from MBDyn 1.3.16 on. The file contains a two lines header, followed by a line containing asingle digit. The header is
UPDATE,N,0,0,1
FLAG,I,1,1,0
The digit indicates the command. Its meaning is:
0 : external software is initializing; MBDyn must wait;
1 : external software is busy; MBDyn must wait;
2 : external software is ready to read kinematics; MBDyn can start reading forces and writing kinematics;
3 : MBDyn finished writing kinematics; external software can start reading kinematics and writing
forces (written by MBDyn when data file is ready);
4 : external software converged; MBDyn should go to convergence, advance to the next time step, andstart writing new step kinematics;
5 : external software decided to quit; MBDyn should stop communicating.
So far, there are no provisions for re-executing a time step, nor for communicating either the time or thetime step, so adaptive time stepping cannot be implemented.
data_file_name is the name of the file used to actually send data between the two processes. Its
contents depend on the purpose it is used for, as described in the subsequent sections.

196

Socket communicator
The optional parameter create, when set to yes, indicates that MBDyn will create the socket, and thepeer will have to connect to it. Otherwise, when set to no, it indicates that MBDyn will try to connect
to an already existing socket created by the peer. Connecting to a peer is attempted while reading the
input file. Sockets are created when the input file has been read. MBDyn waits until all sockets havebeen connected to by peers before the simulation is started.
MBDyn supports local (unix) sockets, defined using the path parameter, and inet sockets, definedusing the port parameter. When create is set to yes, the optional keyword host allows to define what
interface MBDyn will listen on. When create is set to no, the optional keyword host indicates whathost to connect to. It defaults to ‘localhost’.
Common parameters
The optional parameter sleep_time determines how long MBDyn is supposed to sleep while waiting for
a new input file to appear or for an old output file to disappear.
The optional parameter precision determines the precision used in writing the output file; thedefault is 16 digits. This is only meaningful for communicators based on textual files.
The optional parameter coupling determines whether the coupling will be staggered (communicate
each time step, with one step delay), loose (communicate each time step, no delay, the default) or tight(communicate each iteration); otherwise, if coupling_steps is provided, the communication occurs every
coupling_steps.
The optional parameter send after predict allows to indicate whether MBDyn must send thepredicted motion or not when playing a tight coupling loop.
Staggered Coupling.

When the coupling is staggered, the communication pattern is:

1. MBDyn receives a set of forces sent by the external peer the first time the residual is assembled
within time step k; the external peer generated that set of forces based on the kinematics at stepk − 1;
2. MBDyn sends a set of kinematic parameters related to step k after convergence.
As a consequence, MBDyn solves the kinematics at the current time step, k, using forces evaluated forthe kinematics at the previous time step, k − 1. Something likef (yk , ẏk , uk−1 ) = 0.

(8.63)

Note: not implemented yet.
Loose Coupling.

When the coupling is loose, the communication pattern is:

1. MBDyn sends a set of kinematic parameters related to step k after predict.
2. MBDyn receives a set of forces sent by the external peer the first time the residual is assembled
within time step k; the external peer generated that set of forces based on the predicted kinematics
at step k;
As a consequence, MBDyn solves the kinematics at the current time step, k, using forces evaluated forthe predicted kinematics at the current time step, k. Something like
(0)
f yk , ẏk , uk
= 0.
(8.64)
197

Tight Coupling.

When the coupling is tight, the communication pattern is:

1. MBDyn sends the predicted kinematics for step k during the “after predict” phase (unless send
after predict is set to no);2. MBDyn receives a set of forces sent by the external peer each time the residual is assembled; thoseforces are computed based on the kinematics at iteration j
3. as soon as, while reading the forces, MBDyn is informed that the external peer converged, it
continues iterating until convergence using the last set of forces it read.
As a consequence, MBDyn solves the kinematics at the current time step, k, at iteration j, using forces
evaluated for the kinematics at the same time step, k, but at iteration j − 1. Something like


(j)
(j)
(j−1)
f yk , ẏk , uk
= 0.
(8.65)

8.8.10External Structural

This element allows to communicate with an external software that computes forces applied to a poolof nodes and may depend on the kinematics of those nodes. Communication occurs by means of thecommunicators illustrated earlier.
<elem_type> ::= force<force_type> ::= external structural<force_arglist> ::= <external_force_communicator> ,[ reference node , <ref_node_label> , ][ { labels , { yes | no }| sorted , { yes | no }| orientation ,{ none | orientation matrix | orientation vector | euler 123 }| accelerations , { yes | no }| use reference node forces , { yes | no }[ , rotate reference node forces , { yes | no } ] }[ , ... ] , ]<num_nodes> ,<node_label> [ , offset , (Vec3) <offset> ][ , ... ][ , echo , <echo_file_name> ]• use reference node forces only meaningful when reference node is used. It assumes theexternal solver is sending the forces and moments related to the reference node. They correspondto the rigid-body forces and moments applied to the whole system. As such, the forces and moments
applied to each node are removed accordingly. If it is set to no, reference node forces and moments
will be ignored.
• The orientation style none implies that only positions, velocities and accelerations will be output(the latter only if accelerations is set to yes).
• echo causes the output of the reference configuration to be produced in a file called echo_file_name.
If the file exists, it is overwritten, if allowed by file system permissions. The format is that of thecommunicator in stream form.
198

File communicator
The forces are read from the input file in textual form, each line formatted as follows:• a label (if labels is set to yes);• three components of force in the global frame;• three components of moment in the global frame, referred to the node as the pole.
The label indicates what node the force and the moment apply to; each force is applied in a point that
may be optionally offset from the corresponding node location according to offset. If optional keyword
sorted is set to no, the forces might be read in arbitrary order, so they need to be recognized by thelabel. The option sorted is only meaningful when labels is set to yes.
The kinematics are written to the output file in textual form, each line formatted as follows:• a label (if labels is set to yes);• the position in the global frame;• the orientation of the node with respect to the global frame:– if orientation is set to orientation matrix, the orientation matrix in the global frame,
row-oriented: R11 , R12 , R13 , R21 , . . . , R32 , R33 ;– if orientation is set to orientation vector, the orientation vector’s components;– if orientation is set to euler 123, the three Euler angles, in degrees, according to the 1,2,3
convention;• the velocity with respect to the global frame;• the angular velocity with respect to the global frame.
If the optional keyword accelerations is set to yes, at the end of each line the following optional fields
will appear:• the acceleration with respect to the global frame;• the angular acceleration with respect to the global frame.
The label indicates what node the kinematics is related to; the position and the velocity refer to a pointthat may be optionally offset from the node location according to offset.
If a reference node was given, the first record is related to the reference node itself. The following
records contain forces and moments in the reference frame of the reference node.
EDGE communicator
TBD
Socket communicator
TBD

199

Example.

The following defines an external structural force with the file communicator

set: integer FORCE_LABEL = 1000;
set: integer NODE_1 = 10;
set: integer NODE_2 = 20;
force: FORCE_LABEL, external structural,"IN.dat", unlink,"OUT.dat", no clobber,sleep time, 10,precision, 12,
coupling, loose,
2, # number of nodes
NODE_1,
NODE_2, offset, 0.,0.,.5;
OutputAn external structural element writes one line for each connected node at each time step in the .frc file.
Each line contains:• in column 1 the label of the element and that of the corresponding node; the format of this field iselement_label@node_label;• in columns 2–4 the three components of the force;• in columns 5–7 the three components of the moment.
If a reference node is defined, a special line is output for the reference node, containing:• in column 1 the label of the element and that of the corresponding node; the format of this field iselement_label#node_label;• in columns 2–4 the three components of the force applied to the reference node, as received fromthe peer;• in columns 5–7 the three components of the moment applied to the reference node, as received
from the peer.
• in columns 8–10 the three components of the force that are actually applied to the reference node,in the global reference frame;• in columns 11–13 the three components of the moment with respect to the reference node that are
actually applied to the reference node, in the global reference frame;• in columns 14–16 the three components of the force resulting from the combination of all nodal
forces, in the global reference frame;• in columns 17–19 the three components of the moment with respect to the reference node resulting
from the combination of all nodal forces and moments, in the global reference frame;2008.8.11External structural mappingThis element allows to communicate with an external software that computes forces applied to a poolof nodes and may depend on the kinematics of those nodes through a linear mapping. Communication
occurs by means of the communicators illustrated earlier.
<elem_type> ::= force<force_type> ::= external structural mapping<force_arglist> ::= <external_force_communicator> ,[ reference node , <ref_node_label> , ][ { labels , { yes | no }| orientation ,{ none | orientation matrix | orientation vector | euler 123 }| accelerations , { yes | no }| use reference node forces , { yes | no }[ , rotate reference node forces , { yes | no } ] }[ , ... ] , ]<num_points> ,<node_label> , offset [ , <point_label> ] , (Vec3) <offset>[ , ... ][ , echo , " <echo_file_name> "[ , { precision , <digits>| surface , " <surface_file_name> "| output , " <output_file_name> "| order , <order>| basenode , <basenode>| weight , { inf | (real) <weight> } }[ , ... ] ][ , stop ] ][ , mapped points number , { from file | <mapped_points> } ,{ full | sparse } mapping file , " <mapping_file_name> "[ , threshold , <threshold> ][ , { mapped labels file , " <mapped_labels_file_name> "| <mapped_label> [ , ... ] } ] ]A set of num_points points is generated first, by computing the kinematics of the points originating fromthe rigid-body motion of the structural nodes node_label according to the specified offset. Multiple
offset blocks can appear for each node_label.
The echo keyword causes the positions of those points to be written in a file named echo_file_name.
If the keyword stop is present, the simulation ends here. This is useful to generate the bulk data that isneeded to compute the linear mapping matrix. The optional keyword precision allows to set precision
digits in the logged data; the other optional keywords refer to values that are written verbatim to thefile. In detail, surface_file_name is the name of the file that contains the coordinates of the peer’s
points, output_file_name is the name of the file that will contain the mapping matrix, order is an
integer (1 ≤ order ≤ 3), basenode is the number of nodes for each region (basenode > 0), weight is aweighting coefficient (weight ≥ −2 or inf)
When the reference node keyword is present, the kinematics of the points is formulated in the reference frame of node ref_node_label. The forces are expected in the same reference frame. In this case,if use reference node forces is set to yes, the force and moment related to node ref_node_label
201

returned by the external solver are used; if rotate reference node forces is set to yes, they are firstrotated in the global reference frame.
When the mapped points number keyword is present, a mapping matrix is read from the file named
mapping_file_name (same as output_file_name when the echo keyword is used). If the keyword fromfile is used, the number of mapped_points is computed from the number of rows of the matrix in filemapping_file_name. The matrix must be (3 × mapped_points) × (3 × num_points). If the mapped
points number keyword is not present, the element behaves as if the mapping were the identity matrix,
namely the position and the velocity of the points rigidly offset from MBDyn’s nodes are directly passed
to the peer solver. See the modal variant for a description of the mapping file format.
The labels of the original points, indicated as point_label, and the labels of the mapped points,
either contained in the mapped_labels_file_name, or directly listed as mapped_label, must be provided
when labels is set to yes.
Mapping. The mapping consists in a constant matrix that allows to compute the position and thevelocity of the mapped points (subscript ‘peer’) as functions of a set of points rigidly offset from MBDyn’s
nodes (subscript ‘mbdyn’),
xpeer = Hxmbdyn
ẋpeer = H ẋmbdyn(8.66a)(8.66b)The same matrix is used to map back the forces onto MBDyn’s nodes based on the preservation of thework done in the two domains,δxTmbdynfmbdyn = δxTpeerfpeer = δxTmbdynH T fpeer(8.67)

fmbdyn = H T fpeer(8.68)

which implies

To compute matrix H one needs to:
1. gather the coordinates of the set of points used by the peer process (subscript ‘peer’ in the formulas
above) in a file, formatted as<num_points><x_1> <y_1> <z_1>...
<x_n> <y_n> <z_n>
If reference node is defined, the points need to be expressed in a reference frame coincident withthat of node ref_node_label.
2. execute MBDyn’s input file after uncommenting the echo line in the definition of the external structural mapping force element, terminated by the stop keyword, to generate the echo_file_namefile with MBDyn’s points coordinates (subscript ‘mbdyn’ in the formulas above).
3. start octave
4. make sure the folder contrib/MLS/ is in octave’s path
addpath(’/path/to/contrib/MLS’)
5. execute the create_mls_interface function202create_mls_interface(’echo_file_name’);This generates the mapping matrix H, using the files echo_file_name and surface_file_name(the latter is written in echo_file_name by the surface keyword). The matrix is stored in thefile output_file_name. The sparse storage is recommended, since for usual problems the matrix
is significantly sparse.
NOTE: this operation can take minutes when the mapped domains consist of thousands of points.
6. comment the echo line in the definition of the external structural mapping force element.
From this point on, when MBDyn is executed it loads the mapping matrix from file output_file_nameusing sparse storage, automatically ignoring coefficients whose absolute value is below threshold (defaults to 0).
The parameters of the mapping, as documented in create_mls_interface, are% function create_mls_interface([inputfilename])%
inputfilename [optional argument] string that contains the name%of the file created by the MBDyn external mapping force element%
using the "echo" option%
Additional rows must be either added in the comment section of the file%or can be enforced using the appropriate options of the "echo" keyword%
if input values different from default are required. In detail%%# surface: ...
%used to indicate the name of the file that contains%
the external element grid data. Default: ’surface.dat’%%# order: used to indicate the polynomial order of the base used by MLS%
The value must be in the range [1,3]. Default is 2%%
# basenode: number of nodes included in the local MLS support%should be higher than 0%%# weight: continuity order of the RBF weight function%
The value must be in the range [-2,inf]%-1 means constant weight == 1 in the support%-2 means a special weight function == 0 @ the query point%
default 2%%# output: name of the file where the interface matrix is saved in sparse format
Example.
force: 100, external structural mapping,socket,create, yes,
path, "/tmp/mbdyn.sock",no signal,
coupling, tight,
reference node, 0,
points number, 9,

203

10,
offset, null,# centered at node
offset, 0., 1., 0., # y offset
offset, 0., 0., 1., # z offset
20,
offset, null,# ...
offset, 0., 1., 0.,offset, 0., 0., 1.,30,
offset, null,
offset, 0., 1., 0.,offset, 0., 0., 1.,# NOTE: uncomment the line below to generate data required for the mapping# echo, "points.dat", surface, "surf.dat", output, "mapping.dat", stop,
mapped points number, 27,
sparse mapping file, "mapping.dat";
File communicator
TBD
EDGE communicator
TBD
Socket communicator
TBD
The format of the socket communicator is relatively simple; however, implementors may exploit thepeer library libmbc, whose C API is defined in mbc.h. A C++ wrapper is defined in mbcxx.h. A python
wrapper is also available.
OutputTBD

8.8.12External modalThis element allows to communicate with an external software that computes forces applied to a modal
joint element, and may depend on the values of the corresponding generalized variables. Communication
occurs by means of the communicators illustrated earlier.
<elem_type> ::= force<force_type> ::= external modal<force_arglist> ::= <external_force_communicator> ,<modal_label>[ , accelerations ][ , type , { rigid | modal | all } ]204modal_label is the label of the modal joint element the force element is connected to.
If the optional keyword accelerations is present, the output will also contain the modal accelerations.
If the optional keyword type is present, the mutually exclusive keywords rigid, modal or all inform
MBDyn about whether only the rigid or the modal portions of the force are expected. The default isall, but some communicators might require a specific value. If rigid or all are used, the modal joint
element must be connected to a modal node. The number of modes of the modal force must match thatof the active modes in the modal joint element.
File communicator
If type is rigid or all, the first line of the input file must contain:• the label of the modal node the modal joint element is connected to, or 0 if the element is grounded;• three components of force in the modal node reference frame;• three components of moment in the modal node reference frame.
If the modal joint element is grounded, the force and moment are ignored. If type is modal or all, eachof the following lines contains the value of the generalized force for the respective mode.
The output file file is written in textual form. If type is rigid or all, the first line contains:• the label of the modal node the modal joint element is connected to, or 0 if the element is grounded;• the position in the global frame;• the orientation matrix in the global frame;• the velocity with respect to the global frame;• the angular velocity with respect to the global frame.
If the optional keyword accelerations is present, at the end of each line the following optional fields
will appear:• the acceleration with respect to the global frame;• the angular acceleration with respect to the global frame.
If the modal joint element is grounded, all the data corresponds to that of the origin of the global reference
frame. If type is modal or all, each of the following lines contains, for each mode:• the value of the generalized variable;• the value of the first derivative of the generalized variable.
If the optional keyword accelerations is present, at the end of each line the following optional field
will appear:• the value of the second derivative of the generalized variable.
EDGE communicator
When the edge communicator is used, the accelerations keyword is ignored. type must be either
rigid or modal. If both need to be used, two external modal forces must be instantiated: one with
type set to rigid and the other with type set to modal.
205

Rigid.

When type is rigid, the data file written by the external software is expected to contain:* this is a comment
body_forces,R,1,6,0<fx> <fy> <fz> <mx> <my> <mz>
where fx, fy, fz, mx, my, mz respectively are the force and moment components oriented according to
the global reference frame. The moments are referred to the point that represents the origin of the FEmodel reference frame, or to either of the origin position or the origin node of the modal element,
if defined.
The data file written by MBDyn contains:* this is a comment
body_dynamics,N,0,0,3* Body linear velocity in body axes
VRELV,R,1,3,0<vx> <vy> <vz>
* Body angular velocity in body axes
VRELM,R,1,3,0<omegax> <omegay> <omegaz>* Body reference frame cosines (listed by columns)
OMGMAN,R,3,3,0<R11> <R21> <R31><R12> <R22> <R32><R13> <R23> <R33>
where:• vx, vy, vz are the components of the velocity of the rigid body, in body axes;• omegax, omegay, omegaz are the components of the angular velocity of the rigid body, in body axes;• R11, R12, R13, R21, R22, R23, R31, R32, R33 are the components of the orientation matrix.
Modal.

When type is modal, the external software is expected to write a data file containing:* this is a comment
modal_force_flow,R,<n>,1,0<f1> ... <fn>where n is the number of modes (must match the number of active modes in the modal joint element),
while f1 to fn are the amplitudes of the modal forces.
The data file written by MBDyn contains:* this is a comment
modal_state,N,0,0,2
modal_coordinate,R,1,<n>,0<q1> ... <qn>modal_velocity,R,1,<n>,0<qp1> ... <qpn>
where:• n is again the number of modes;206• q1 to qn are the amplitudes of the modal coordinates;• qp1 to qpn are the amplitudes of the derivatives of the modal coordinates.
Each field can be separated by an arbitrary amount of whitespace, and by at most one “comma” (“,”).
Although specifically developed for ease of interfacing with EDGE, this format is open, and thus can be
implemented by other software in order to easily couple with MBDyn.
Socket communicator
When the socket communicator is used, the communication layer is established according to the definition provided at page 197. For a single external modal force with socket communicator, type can be
any of rigid, modal, or all.
Example.
force: 10, external modal,
socket,create, yes,
path, "/tmp/mbdyn.sock",no signal,
coupling, tight,2;# modal joint label
OutputAn external modal element writes multiple lines at each time step in the .frc file.
If type is ridig or all, the line contains:• in column 1 the label of the element and that of the corresponding node; the format of this field iselement_label#node_label;• in columns 2–4 the three components of the force;• in columns 5–7 the three components of the moment.
If type is modal or all, each line contains:• in column 1 the label of the element and the corresponding mode; the format of this field iselement_label.mode_number;• in column 2 the amplitude of the corresponding modal force.

8.8.13External modal mappingThis element allows to communicate with an external software that computes forces applied to a setof structural nodes, and may depend on the values of the corresponding variables. Modal forces are
actually computed, based on the value of modal variables. The element thus projects the motion of theset of structural nodes in the space of a set of modes before communicating it to the peer. Similarly, it
receives generalized forces that are projected back in the space of the structural nodes before assembly.
Communication occurs by means of the communicators illustrated earlier for the external modal case.

207

<elem_type> ::= force<force_type> ::= external modal mapping<force_arglist> ::= <external_force_communicator> ,[ reference node , <ref_node_label> , ][ use rigid body forces , { yes | no } ,[ rotate rigid body forces , { yes | no } , ] ][ accelerations , { yes | no } , ][ type , { rigid | modal | all } , ]nodes number , <num_nodes> ,<node_1_label> [ , ... ] ,modes number , { from file | <num_modes> } ,{ full | sparse } mapping file , " <mapping_file_name> "[ , threshold , <threshold> ]ref_node_label is the label of the reference node if the modes express the motion relative to a specificnode.
The mapping file contains the matrix that maps the nodal and modal displacements, velocities andforces. When full mapping file is used, a file containing num_modes × (6 × num_nodes) coefficients is
expected. When sparse mapping file is used, a file containing<row> <col> <value>
triplets is expected, with 1 ≤ row ≤ num_modes and 1 ≤ col ≤ 6 × num_nodes. Both files may startwith an arbitrary number of lines beginning with a hash mark (‘#’). They are treated as comments
and ignored. If a threshold is given, only elements whose absolute value is larger than threshold areretained. The value of threshold defaults to 0. The mapping matrix is internally stored and handled
as sparse, regardless of the file format. When the keyword from file is used, the number of modes
num_modes is computed from the matrix contained in the file mapping_file_name.
If the optional keyword accelerations is present, the output will also contain the modal accelerations.
If the optional keyword type is present, the mutually exclusive keywords rigid, modal or all inform
MBDyn about whether only the rigid or the modal portions of the force are expected. The default isall, but some communicators might require a specific value. If rigid or all are used, the reference
node must be defined.
File communicator
Same as external modal.
EDGE communicator
Same as external modal.
Socket communicator
Same as external modal.
Example.

208force: 10, external modal mapping,socket,create, yes,
path, "/tmp/mbdyn.sock",no signal,
coupling, tight,
send after predict, no,# comment for absolute test
reference node, 0,
nodes number, 3,
1, 2, 3,modes number, 3,# full mapping file, "Hp_full.dat",sparse mapping file, "Hp_sparse.dat",
type, modal;
where file Hp_sparse.dat contains# Created by Octave 3.0.1, Mon Dec 14 22:20:31 2009 CET <mbdyn@mbdyn.aero.polimi.it># name: Hps# type: sparse matrix# nnz: 7# rows: 3# columns: 18
3 4 0.3333333333333332
2 8 0.2352941176470588
1 9 0.4
3 10 0.3333333333333333
2 14 0.9411764705882351
1 15 0.7999999999999999
3 16 0.3333333333333333
corresponding to0.0
Hps =  0.0
0.0

0.0
0.0
0.0

0.0
0.0
0.0

0.0
0.0
0.333

0.0
0.0
0.0

0.0
0.0
0.0

0.0
0.0
0.0

0.0
0.235
0.0

0.4
0.0
0.0

0.0
0.0
0.333

0.0
0.0
0.0

0.0
0.0
0.0

0.0
0.0
0.0

0.0
0.941
0.0

0.8
0.0
0.0

0.0
0.0
0.333

0.0
0.0
0.0

OutputAn external modal mapping element writes multiple lines at each time step in the .frc file.
If type is ridig or all, the line contains:• in column 1 the label of the element and that of the corresponding node; the format of this field iselement_label@node_label;• in columns 2–4 the three components of the force, as received from the peer;• in columns 5–7 the three components of the moment, as received from the peer;• in columns 8–10 the three components of the force, in the global reference frame;

209


0.0
0.0 
0.0

• in columns 11–13 the three components of the moment with respect to the reference node, in the
global reference frame;• in columns 14–16 the three components of the force, in the global reference frame, resulting fromthe combination of the mapped forces;• in columns 17–19 the three components of the moment with respect to the reference node, in the
global reference frame, resulting from the combination of the mapped forces and moments.
If type is modal or all, two types of output are generated:• a line for each node participating in the mapping, containing:– in column 1 the label of the element and the corresponding node; the format of this field iselement_label#node_label;– in columns 2–4 the three components of the corresponding nodal force, in the global reference
frame;– in columns 5–7 the three components of the corresponding nodal moment, in the global reference frame;– in columns 8–10 the three components of the nodal displacement, either in the global reference
frame, or in that of the reference node, if any;
– in columns 11–13 the three components of the nodal orientation, either in the global reference
frame, or in that of the reference node, if any;
– in columns 14–16 the three components of the nodal velocity, either in the global reference
frame, or in that of the reference node, if any;
– in columns 17–19 the three components of the nodal angular velocity, either in the global
reference frame, or in that of the reference node, if any.
• a line for each mode the motion is mapped to, containing:– in column 1 the label of the element and the corresponding mode; the format of this field iselement_label.mode_number;– in column 2 the amplitude of the corresponding modal force;– in column 3 the amplitude of the corresponding modal variable;– in column 4 the amplitude of the corresponding modal variable derivative.

8.9

Genel Element

Genel is the compact form for General element. Those elements that cannot in general be classified
in a precise way, or are just under development and thus are not collected in a class of their own until
their configuration is stabilized, usually are classified as Genel. The syntax of the Genel elements is:<elem_type> ::= genel<normal_arglist> ::= <genel_type> , <genel_arglist>
The output goes in a file with extension .gen; only few elements actually generate output.
At present, the Genel class contains very basic general elements and some elements specifically developed
for rotorcraft analysis. The latter could be moved to a more specific class in future releases.
210

8.9.1

General Purpose Elements

Clamp<genel_type> ::= clamp<genel_arglist> ::=(NodeDof) <clamped_node> ,(DriveCaller) <imposed_value>
This element simply forces one arbitrary degree of freedom to assume a value depending on the drive.
Output The format is:• the label of the element• the value of the reaction unknown
Distance<genel_type> ::= distance<genel_arglist> ::=(NodeDof) <node_1> ,(NodeDof) <node_2> ,(DriveCaller) <imposed_distance>
This element forces the difference between two arbitrary degrees of freedom to assume the value dictatedby the driver.
Output The format is:• the label of the element• the value of the reaction unknown
Spring<genel_type> ::= spring<genel_arglist> ::=(NodeDof) <node_1> ,(NodeDof) <node_2> ,(ConstitutiveLaw<1D>) <const_law>
The constitutive law must be elastic, but the distance genel can apply to arbitrary order degrees of
freedom, even between degrees of freedom of different order.

211

Spring support<genel_type> ::= spring support<genel_arglist> ::=(NodeDof) <node> ,(ConstitutiveLaw<1D>) <const_law>
The spring support must use the algebraic value of a differential node, but it can use an arbitrary
constitutive law, i.e. an elastic constitutive law for a spring, or a viscous constitutive law for a damper,and so on.
Cross spring support<genel_type> ::= cross spring support<genel_arglist> ::=(NodeDof) <row_node> ,(NodeDof) <col_node> ,(ConstitutiveLaw<1D>) <const_law>
It writes a term depending on the col_node degree of freedom in an arbitrary manner (given by theconst_law) to the row_node equation.
The cross spring support must use the algebraic value of a differential node, but can use anarbitrary constitutive law, i.e. an elastic constitutive law for a spring, or a viscous constitutive law for adamper, and so on.
Mass<genel_type> ::= mass<genel_arglist> ::=(NodeDof) <node> ,(DriveCaller) <mass>
The mass must use the algebraic value of a differential node. The derivative of the differential
value of the dof is differentiated in a state-space sense, and an inertial driven term is applied to theequation related to the dof:mu̇ + . . . = f
u − ẋ

= 0

Scalar filter<genel_type> ::= scalar filter<genel_arglist> ::=(NodeDof) <output_node> ,{ [ node dof , ] (NodeDof) <input_node>| drive , (DriveCaller) <input_value> } ,[ canonical form , { controllable | observable } , ]<output_order> [ , <output_coef_list> ] ,212

<input_order> [ , <input_coef_list> ][ , gain , <gain> ][ , balance , { yes | no } ]This element models a scalar filter of the form
A (s) y = B (s) uwhere A, B are polynomials of arbitrary order, namelyy (s) =

b0 snn + b1 snn −1 + . . . + bnn
u (s)a0 snd + a1 snd −1 + . . . + and

The filter must be proper, namely the output_order nd must be greater than or at most equal to the
input_order, nn . The polynomial A is assumed to be monic, so the coefficient a0 = 1 and only thecoefficients from a1 to and must be input, while all the coefficients of polynomial B are required, i.e.
from b0 to bnn .
If a gain is supplied, all the coefficients of B are multiplied by the gain.
Originally, the input needed to be taken from a ScalarDof; now, it can also be taken from a drive,
which can completely replace the original form (e.g. by means of the dof, the node and the element
drives) and requires much less effort because no auxiliary node needs to be set up.
The filter is internally rewritten as a state space SISO element. By default, the controllable
canonical form is used, namely

 
 


ẋ1 
−a1 −a2 −a3 . . . −and 
x1 
1






 

 





0
0
0 

 ẋ2   1
 x2 
  0 




ẋ3
1
0
0 
x3
= 0
+  0  u (t)








.
.
.
.
.
..

..  
 .. 
  ..
 .. 
  .. 
.












ẋnd
0
0
0
...
0
xnd
0


x1 






x2 






x3
y = b1 b2 b3 . . . bnd

.. 



. 






xnd

Otherwise, a observable canonical form can be used, namely

 
 


−a1 1 0 . . . 0 b1
 ẋ1 
 x1   −a2 0 1
 x2 0  ẋ2    b2 




ẋ3
0 
x3
=  −a3 0 0+  b3  u (t)








.
.
.
.
.
..

.. 
.. 




 ..
 .. 
. ..  












ẋnd
−and 0 0 . . . 0
xnd
bnd


x1 




 x2 







x
3
y = 1 0 0 ... 0 .. 





 . 



xnd
213

In case the filter is not strictly proper, because nn = nd = n, it is turned into a strictly proper one by
the transformation
B (s)
A (s)
b0 sn + b1 sn−1 + . . . + bn
= ns + a1 sn−1 + . . . + an
B (s) − b0 A (s)= b0 +A (s)+ (b1 − b0 a1 ) sn−1 + . . . + (bn − b0 an )= b0 +
sn + a1 sn−1 + . . . + an

H (s) =and the state space realization is modified by using the resulting numerator coefficients and by introducing
a direct feedthrough term b0 u (t) in the output.
Example.

To model a 2nd order Butterworth filter of equation
1

H (s) =
s
ωc

!2

√
+ 2

s
ωc

!

(8.69)+1use
set: real OMEGA_C = 1.*2*pi;
genel: 1, scalar filter,
100, abstract, algebraic,
drive, sine, 0., 2.*pi, 1., forever, 0.,2, sqrt(2.)*OMEGA_C, OMEGA_C^2,0, 1.,
gain, OMEGA_C^2;# filter at 1Hz# output node
# input drive# a_1, a_2# b_0

Note that the formula of Eq. (8.69) had to be rearranged in order to make the denominator monic.
State space SISO
<genel_type> ::= state space SISO
<genel_arglist> ::=(NodeDof) <output_node> ,{ [ node dof , ] (NodeDof) <input_node>| drive , (DriveCaller) <input_value> } ,<state_order>[ , matrix E , <matrix_E_coef_list> ] ,matrix A , <matrix_A_coef_list> ,matrix B , <matrix_B_coef_list> ,matrix C , <matrix_C_coef_list>[ , matrix D , <D_coef> ][ , gain , <gain> ][ , balance , { yes | no } ][ , value , <x0_list>[ , derivative , <x0p_list> ] ]214

This element models a scalar (SISO) state space filter of the form
E ẋ = Ax + Bu
y = Cx + Du
where
• E is a(n optional) matrix state_order × state_order, defaulting to the identity matrix I,• A is a matrix state_order × state_order,• B is a vector state_order × 1,
• C is a vector 1 × state_order, and• D is a(n optional) scalar.
The matrices are read row-oriented; e.g., for matrix A:
matrix A,
a11, a12, ..., a1N,
a21, a22, ..., a2N,...,
aN1, aN2, ..., aNN
If LAPACK is available, the matrices are balanced by default, unless explicitly disabled by using thebalance optional keyword. If matrix E is defined, the dggbal() routine is used; the dgebal() routine
is used otherwise.
The state and its derivative can be initialized using the keywords value and derivative. The
initialization of the derivative only makes sense when the filter is in descriptor form.
State space MIMO
<genel_type> ::= state space MIMO
<genel_arglist> ::=<num_outputs> , (NodeDof) <output_node_list> ,<num_inputs> ,{ [ node dof , ] (NodeDof) <input_node>| drive , (DriveCaller) <input_value> }[ , ... ] ,<state_order>[ , matrix E , <matrix_E_coef_list> ] ,matrix A , <matrix_A_coef_list> ,matrix B , <matrix_B_coef_list> ,matrix C , <matrix_C_coef_list>[ , matrix D , <matrix_D_coef_list> ][ , gain , <gain> ][ , balance , { yes | no } ][ , value , <x0_list>[ , derivative , <x0p_list> ] ]215

This element models a vector (MIMO) state space filter of the form
E ẋ = Ax + Bu
y = Cx + Du
where
• E is a(n optional) matrix state_order × state_order, defaulting to the identity matrix I,• A is a matrix state_order × state_order,• B is a matrix state_order × num_inputs,• C is a matrix num_outputs × state_order, and• D is a(n optional) matrix num_outputs × num_inputs.
The matrices are read row-oriented.
If LAPACK is available, the matrices are balanced by default, unless explicitly disabled by using thebalance optional keyword. If matrix E is defined, the dggbal() routine is used; the dgebal() routine
is used otherwise.
The state and its derivative can be initialized using the keywords value and derivative. The
initialization of the derivative only makes sense when the filter is in descriptor form.

8.9.2

Special Rotorcraft Genel Elements

The Genel elements specifically developed for use in rotorcraft analysis currently include:• the swashplate;• the rotor trim.
Swashplate
The swashplate Genel is used to transform the controls of a rotor, in terms of collective and fore/aft
and lateral cyclic pitch, into the elongations of the actuators that actually move the swash plate. The
syntax of the swashplate is:<genel_type> ::= swash plate<genel_arglist> ::=<collective_abstract_node>[ , limits , <min_collective> , <max_collective> ] ,<fore/aft_abstract_node>[ , limits , <min_fore/aft> , <max_fore/aft> ] ,<lateral_abstract_node>[ , limits , <min_lateral> , <max_lateral> ] ,<actuator_1_abstract_node_label> ,<actuator_2_abstract_node_label> ,<actuator_3_abstract_node_label>[ , <dynamic_coef> , <cyclic_factor> , <collective_factor> ]216

The first three abstract nodes contain the input values of collective, fore/aft and cyclic pitch (they canbe actuated by means of abstract forces), and the limits on the “angles” can be easily set. The last threenodes will contain the values of the stroke of the actuators.
The first actuator should be put at the azimuthal position that makes the current blade assume thefore/aft pitch, so that its pitch link is atan (1/ωβ ) before the front direction. The other actuators should
follow, 120 deg apart in clockwise direction.
The limits on the actuators will simply force the value of the control inputs to remain in the boundaries
regardless of the input values.
The last three optional parameters are a dynamic coefficient that is used to add some dynamics tothe actuators’ stroke, namely the input variables are applied a sort of spring stiffness bulk element,
while the actuators’ strokes are applied a transfer function of the first order, namely αẋ + x = f , where
α = dynamic_coef and f is the desired stroke, so the smaller is α, the more the behavior is static.
The cyclic_factor and the collective_factor parameters are used to scale the inputs from angles
in the desired units to strokes, that usually are dimensional parameters. The actual strokes are made of
the collective contribution multiplied by collective_factor, and the cyclic contribution multiplied bycollective_factor × cyclic_factor.
Rotor Trim
The syntax of the rotor trim is<genel_type> ::= rotor trim
<genel_arglist> ::= [ <rotor_trim_type> ] ,<type_specific_rotor_trim_data> ,<thrust_node_label> ,<longitudinal_moment_node_label> ,<lateral_moment_node_label> ,(DriveCaller) <desired_thrust_coefficient> ,(DriveCaller) <desired_longitudinal_moment_coefficient> ,(DriveCaller) <desired_lateral_moment_coefficient> ,<rotor_lock_number> ,<rotor_nondimensional_flap_frequency> ,<thrust_time_constant> , <moments_time_constant> ,<thrust_gain> , <moments_gain>[ , trigger , (DriveCaller) <trigger> ]<rotor_trim_type> ::= { rotor | generic }# for rotor<type_specific_rotor_trim_data> ::=<rotor_label># for generic<type_specific_rotor_trim_data> ::=[ reference node , <ref_node_label> , ](DriveCaller) <thrust> ,(DriveCaller) <longitudinal_moment> ,(DriveCaller) <lateral_moment> ,<rotor_radius> ,217

(DriveCaller) <angular_velocity> ,(DriveCaller) <advance_ratio>
The rotor trim is experimental; it allows to set the controls of a generic helicopter, in conjunction withthe swashplate element, to asymptotically obtain the desired level of thrust and moment coefficients.
The corresponding behavior in terms of trim values (flapping angles and shaft angle) has not been
implemented yet. For details, see [17].

8.10

Gravity Element<elem_type> ::= gravity<arglist> ::= <gravity_model> , <gravity_data><gravity_model> ::=# uniform gravity field (default)[ uniform , ](TplDriveCaller<Vec3>) <gravity_acceleration># central gravity field| central ,[ origin , (Vec3) <absolute_origin> , ]mass , (real) <central_gravity_field_mass> ,G , { si | (real) <universal_gravity_constant> }The 3D drive caller gravity_acceleration represents the gravity acceleration in the global reference
frame. The keyword uniform is optional; a uniform gravity field is assumed when gravity_model ismissing.
The optional vector absolute_origin is the absolute origin of the central gravity field. The scalarmass is the central mass of the central gravity field. the scalar universal_gravity_constant is theuniversal gravity constant; if the keyword si is used, the value 6.67384 × 10−11 m3 kg−1 s−2 is used(source: http://physics.nist.gov/cuu/Constants/index.html.

8.11

Hydraulic Element

Note: under development; syntax subjected to changes
Initially implemented by: Lamberto Puggelli
Reviewed by: Pierangelo Masarati<elem_type> ::= hydraulic<normal_arglist> ::= <hydr_elem_type> , <hydr_elem_data>
The field hydraulic_element_data usually contains information about fluid properties, which are handled by means of a HydraulicFluid. This can be directly inserted, following the syntax described in
Section 2.11 preceded by the keyword fluid, or a previously defined fluid can be recalled by using the
keyword reference followed by the label of the desired fluid:<hydraulic_fluid_properties> ::={ <hydraulic_fluid_specification>| reference , <hydraulic_fluid_label> }218

8.11.1

Actuator

The actuator element models the hydraulic and interactional aspects of a two-way linear hydraulicactuator. The two hydraulic nodes represent the pressure in the two chambers of the cylinder. The
two structural nodes represent the cylinder and the piston. Their relative motion is assumed to consist
essentially in a displacement along a given direction in the reference frame of structural node 1. The user
must take care of this by constraining the two nodes with an appropriate set of joint elements. Other
hydraulic aspects of this component, like leakages between the two chambers and between the chambers
and the outside, and the related pressure losses, must be explicitly taken care of, e.g. by means of minor
loss elements.
<hydr_elem_type> ::= actuator<hydr_elem_data> ::=<node_1> , <node_2> ,<struct_node_1> , (Vec3) <offset_1> ,<struct_node_2> , (Vec3) <offset_2> ,[ direction , ((Unit)Vec3) <direction> , ]<area_1> ,<area_2> ,<cylinder_length> ,fluid , (HydraulicFluid) <fluid_1> ,{ same | fluid , (HydraulicFluid) <fluid_2> }The vector direction is internally normalized to unity. By default, it is direction 3 in the reference
frame of the structural node struct_node_1.
Example.

See the “actuator” example at

http://www.aero.polimi.it/mbdyn/documentation/examples/actuatorand the related chapter of the tutorials
http://www.aero.polimi.it/mbdyn/documentation/tutorials/

8.11.2

Minor Loss

A pressure loss between two pressure nodes.
<hydr_elem_type> ::= minor loss
<hydr_elem_data> ::=<node_1> , <node_2> ,<k12> , <k21> , <area> ,fluid , (HydraulicFluid) <fluid>
Coefficients k12 and k21 characterize the pressure loss when the flow goes from node_1 to node_2 andvice versa. Turbulent flow is assumed.

8.11.3Three Way Minor Loss

A pressure loss between three pressure nodes, depending on the sign of the pressure drop.

219

<hydr_elem_type> ::= three way minor loss
<hydr_elem_data> ::=<node_1> , <node_2> , <node_3> ,<k12> , <k31> , <area_12> , <area_31> ,fluid , (HydraulicFluid) <fluid>
Coefficients k12 and k31 and the respective values of area characterize the pressure loss when the flow
goes from node_1 to node_2 and from node_3 to node_1, respectively. Turbulent flow is assumed.

8.11.4Control Valve<hydr_elem_type> ::= control valve<hydr_elem_data> ::=<node_1> , <node_2> ,<node_3> , <node_4> ,<area> ,[ loss , <loss_factor> , ](DriveCaller) <state> ,fluid , (HydraulicFluid) <fluid>
This element represents a valve that connects node_1 to node_2 and node_3 to node_4 when state is
positive, and node_1 to node_3 and node_2 to node_4 when state is negative. The flow area is proportional to area times the norm of state, which must be comprised between −1 and 1. If loss_factor isdefined, it represents the fraction of area that leaks when state is exactly zero.

8.11.5

Dynamic Control Valve<hydr_elem_type> ::= dynamic control valve<hydr_elem_data> ::=<node_1> , <node_2> ,<node_3> , <node_4> ,(DriveCaller) <force> ,<initial_displacement> ,<max_displacement> ,<duct_width> ,[ loss , <loss_factor> , ]<valve_diameter> ,<valve_density> ,<displacement_penalty> ,<velocity_penalty> ,<acceleration_penalty> ,fluid , (HydraulicFluid) <fluid>
This element represents a valve that connects node_1 to node_2 and node_3 to node_4 when the displacement is positive and node_1 to node_3 and node_2 to node_4 when the displacement is negative, accounting for the dynamics of the valve body. The control force force is applied to the valve, whose geometricand structural properties are described by initial_displacement, max_displacement, duct_width,
valve_diameter and valve_density. Again the loss_factor, if defined, represents the fraction of the220area that leaks when the displacement is zero. Finally, displacement_penalty, velocity_penalty andacceleration_penalty are the penalty coefficients for displacement, velocity and acceleration when the
maximum stroke is reached.

8.11.6

Pressure Flow Control Valve<hydr_elem_type> ::= pressure flow control valve<hydr_elem_data> ::=<node_1> , <node_2> ,<node_3> , <node_4> ,<node_5> , <node_6> ,(DriveCaller) <force> ,<initial_displacement> ,<max_displacement> ,<duct_width> ,[ loss , <loss_factor> , ]<valve_diameter> ,<valve_density> ,<displacement_penalty> ,<velocity_penalty> ,<acceleration_penalty> ,fluid , (HydraulicFluid) <fluid>Same as Dynamic Control Valve (8.11.5), only the pressures at node_5 and node_6 are applied at thesides of the valve body and participate in the force balance.

8.11.7

Pressure Valve<hydr_elem_type> ::= pressure valve<hydr_elem_data> ::=<node_1> , <node_2> ,<area> ,<mass> ,<max_area> ,<spring_stiffness> ,<spring_preload> ,<width> ,<displacement_penalty> ,<velocity_penalty> ,<acceleration_penalty> ,fluid , (HydraulicFluid) <fluid>

8.11.8Flow Valve<hydr_elem_type> ::= flow valve<hydr_elem_data> ::=<node_1> , <node_2> , <node_3> ,221

<area> ,<mass> ,<max_area> ,<spring_stiffness> ,<spring_preload> ,<width> ,<displacement_penalty> ,<velocity_penalty> ,<acceleration_penalty> ,fluid , (HydraulicFluid) <fluid>

8.11.9Orifice<hydr_elem_type> ::= orifice<hydr_elem_data> ::=<node_1> , <node_2> ,<orifice_area> ,[ area , <pipe_area> , ][ reynolds , <critical_reynolds_number> , ]fluid , (HydraulicFluid) <fluid>

8.11.10

AccumulatorNot documented yet.

8.11.11Tank

Not documented yet.

8.11.12

Pipe

This element models a simple pipeline connecting two hydraulic nodes. In detail, it models the pressure
loss due to fluid viscosity according to a constitutive law that depends on the Reynolds number computed
on average fluid velocity and hydraulic diameter. Transition between laminar and turbulent flow is alsomodeled.
<hydr_elem_type> ::= pipe
<hydr_elem_data> ::=<node_1> , <node_2> ,<hydraulic_diameter> ,[ area , <area> , ]<length> ,[ turbulent , ][ initial value , <flow> , ]fluid , (HydraulicFluid) <fluid>
When area is not given, it defaults to the equivalent area computed according to the hydraulic diameter.
The flag turbulent forces the flow to be considered turbulent since the first iteration, when the initialconditions would fall in the transition region. The initial value parameter refers to the initial valueof the flow internal state.
222

Example.
set: integer NODE_1 = 10;
set: integer NODE_2 = 20;
set: integer PIPE = 100;
set: integer FLUID = 1000;# ...
hydraulic: PIPE, pipe, NODE_1, NODE_2,
5e-3, 100.e-3,
fluid, reference, FLUID;

8.11.13

Dynamic Pipe

Same syntax as the pipe hydraulic element (Section 8.11.12), it also considers fluid compressibility interms of pressure time derivative, and thus the corresponding dynamic effect.
<hydr_elem_type> ::= dynamic pipe
Output1: label
2: pressure at node 1
3: pressure at node 2
4: pressure derivative at node 1
5: pressure derivative at node 2
6: flow at node 1
7: flow at node 2
8: flow rate at node 1
9: flow rate at node 2
10: density at node 1
11: reference density
12: density at node 2
13: derivative of density with respect to pressure at node 1
14: derivative of density with respect to pressure at node 2
15: Reynolds number
16: flow type flag (boolean; true when flow is turbulent, false otherwise)

8.11.14

Imposed Pressure

No specific element has been implemented to impose the pressure at one node. The clamp variant of thegenel element (Section 8.9.1) can be used instead.
223

Example.
set: integer HYDRAULIC_NODE_LABEL = 100;
set: integer IMPOSED_PRESSURE_LABEL = 200;
genel: IMPOSED_PRESSURE_LABEL, clamp,
HYDRAULIC_NODE_LABEL, hydraulic,const, 101325.0;

8.11.15

Imposed Flow

No specific element has been implemented to impose the flow at one node. The abstract variant of theforce element (Section 8.8.2) can be used instead. The magnitude of the abstract force is the mass flow
extracted from the circuit at that node. In fact, a negative value of the abstract force means that theflow enters the node.
Example.
set: integer HYDRAULIC_NODE_LABEL = 100;
set: integer IMPOSED_FLOW_LABEL = 200;
force: IMPOSED_PRESSURE_LABEL, abstract,
HYDRAULIC_NODE_LABEL, hydraulic,const, -1e-3;

8.12

Joint Element

Joint elements connect structural nodes. Many different joints are available. Joints may have internal
degrees of freedom (the reaction forces) when they introduce kinematic constraints in form of algebraic
relationships between the coordinates of the nodes they connect. Joints that introduce configurationdependent forces are flexible joints. From the point of view of the input syntax there is no difference
between the two classes. A typical joint entry is<elem_type> ::= joint<normal_arglist> ::= <joint_type> , <joint_arglist>
The output is written to a file with extension .jnt. The output is generally made of a standard part,plus some extra information depending on the type of joint, which, when available, is described alongwith the joint description. Here the standard part is described:• column 1: the label of the joint• columns 2–4: the three components of the reaction force in a local reference• columns 5–7: the three components of the reaction couple in a local frame• columns 8–10: the three components of the reaction force in the global frame• columns 11–13: the three components of the reaction couple, rotated into the global frame
Legal joint types, with relative data, are:224

8.12.1

Angular acceleration

This joint imposes the absolute angular acceleration of a node about a given axis.
<joint_type> ::= angular acceleration<joint_arglist> ::=<node_label> ,((Unit)Vec3) <relative_direction> ,(DriveCaller) <acceleration>
The axis is relative_direction; it is internally normalized to unity.
Private Data
The following data are available:
1. "M" constraint reaction moment along joint direction
2. "wp" imposed angular acceleration along joint direction

8.12.2

Angular velocity

This joint imposes the absolute angular velocity of a node about a given axis.
<joint_type> ::= angular velocity<joint_arglist> ::=<node_label> ,((Unit)Vec3) <relative_direction> ,(DriveCaller) <velocity>
The rotation axis of the imposed angular velocity is relative_direction; it is internally normalized tounity. It rotates with the node indicated by node_label.
Private Data
The following data are available:
1. "w" imposed angular velocity about joint direction

8.12.3

Axial rotation

This joint is equivalent to a revolute hinge (see Section 8.12.37), but the angular velocity about axis
3 is imposed by means of the driver.
<joint_type> ::= axial rotation<joint_arglist> ::=<node_1> ,[ position , ] (Vec3) <relative_offset_1> ,[ orientation , (OrientationMatrix) <relative_orientation_matrix_1> , ]<node_2> ,[ position , ] (Vec3) <relative_offset_2> ,[ orientation , (OrientationMatrix) <relative_orientation_matrix_2> , ](DriveCaller) <angular_velocity>225This joint forces node_1 and node_2 to rotate about relative axis 3 with imposed angular velocity
angular_velocity.
Private Data
The following data are available:
1. "rz" relative rotation angle about revolute axis
2. "wz" relative angular velocity about revolute axis
3. "Fx" constraint reaction force in node 1 local direction 1
4. "Fy" constraint reaction force in node 1 local direction 2
5. "Fz" constraint reaction force in node 1 local direction 3
6. "Mx" constraint reaction moment about node 1 local direction 1
7. "My" constraint reaction moment about node 1 local direction 2
8. "Mz" constraint reaction moment about node 1 local direction 3
Hints
When wrapped by a driven element, the following hints are honored:• hinge{1} the relative orientation of the joint with respect to node 1 is reset;• hinge{2} the relative orientation of the joint with respect to node 2 is reset;• offset{1} the offset of the joint with respect to node 1 is reset;• offset{2} the offset of the joint with respect to node 2 is reset;• unrecognized hints are passed to the friction model, if any.

8.12.4Beam slider

This joint implements a slider, e.g. it constrains a structural node on a string of three-node beams, as
discussed in [18].
<joint_type> ::= kinematic<joint_arglist> ::=<slider_node_label> ,(Vec3) <relative_offset> ,[ hinge , (OrientationMatrix) <relative_orientation> ] ,[ type , { spherical | classic | spline } , ]<beam_number> ,<3_node_beam> ,{ same | (Vec3) <first_node_offset> } ,[ hinge , { same | (OrientationMatrix) <first_node_orientation> ] , }(Vec3) <mid_node_offset> ,[ hinge , (OrientationMatrix) <mid_node_orientation> ] ,226

(Vec3) <end_node_offset> ,[ hinge , (OrientationMatrix) <end_node_orientation> ] ,[ ... ]
[ , initial beam , <initial_beam> ][ , initial node , <initial_node> ][ , smearing , <smearing_factor> ]There are three types of slider:• the spherical slider does not constrain the orientation of the node;• the classical slider does allow rotation only about the sliding line;• the spline slider constrain the orientation of the node.
For each node of each beam element, the offset and the orientation of the slider can be defined; except
for the first element, the offset and the orientation of the first node can be specified using the keyword same, which causes the node to take the same value of the last node of the previous beam. The
initial_beam and initial_node indices serve as hints to set the initial contact point of the sliding
node. The smearing_factor determines the (non-dimensional) extension of the interference segment
when the node passes from one segment to another. Further information is available in [18].

8.12.5

Brake

This element models a wheel brake, i.e. a constraint that applies a frictional internal torque between two
nodes about an axis. The frictional torque depends on the normal force that is applied as an external
input by means of the same friction models implemented for regular joints.
<joint_type> ::= brake<joint_arglist> ::=<node_1_label> , (Vec3) <relative_offset_1>[ , hinge , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> , (Vec3) <relative_offset_2>[ , hinge , (OrientationMatrix) <relative_orientation_matrix_2> ] ,friction , <average_radius> ,[ preload , <const_value> , ]<friction_model> ,<shape_function> ,(DriveCaller) <normal_force>
Note: a revolute hinge (see Section 8.12.37) between the same two nodes must be defined as well, suchthat the only allowed relative kinematics between the two nodes are a rotation about relative axis 3.
OutputIn addition to the standard output, the brake joint outputs:• the three Euler-Cardano angles that express the relative rotation between the two connected nodes,
in degrees;• the three components of the relative angular velocity, in the reference frame of node 2;• any output specific for the friction model in use;
• the value of the force the brake is activated with.
227

Figure 8.8: Cardano hinge.
Private Data
The following data are available:
1. "rz" relative rotation angle about brake axis
2. "wz" relative angular velocity about brake axis

8.12.6

Cardano hingeThis joint implements a Cardano’s joint, also known as Hooke’s joint or Universal joint, which is madeof a sequence of two revolute hinges orthogonal to each other, one about relative axis 2 and one about
relative axis 3 of the reference systems defined by the two orientation statements. In other words, thisjoint constrains the relative axis 3 of node 1 to be always orthogonal to the relative axis 2 of node 2. As
a result, torque is transmitted about axis 1 of both nodes. The relative position is constrained as well.
<joint_type> ::= cardano hinge<joint_arglist> ::=<node_1_label> ,position , (Vec3) <relative_offset_1>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> ,position , (Vec3) <relative_offset_2>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ]The joint is shown in Figure 8.8 where the origins and orientations of node_1 and node_2 are given
by axes 1, 2, 3 and 1′ , 2′ , 3′ , respectively. The central, constrained, axes 3 and 2′ are obtained after
having applied relative_offset and relative_orientation_matrix transformations to node_1 andnode_2, respectively. Note: this joint does not represent a constant velocity joint, so, when a steadydeflection between the two nodes is present, a constant velocity about axis 1 of one node results in an
oscillating velocity about axis 1 for the other node. The constant velocity joint is implemented by thegimbal joint (Section 8.12.22), which essentially consists of a sequence of two cardano hinge (seeSection 8.12.6) joints with the hinges in reversed order, assembled in a manner that the deflection is split
half and half between the two joints.

8.12.7

Cardano pin

This joint implements a “Cardano” joint between a node and the ground. The absolute position is also
constrained. See above for details about the formulation.
228

<joint_type> ::= cardano pin<joint_arglist> ::=<node_label> ,position , (Vec3) <relative_offset>[ , orientation , (OrientationMatrix) <relative_orientation_matrix> ] ,position , (Vec3) <absolute_pin_position>[ , orientation , (OrientationMatrix) <absolute_pin_orientation_matrix> ]Note: this is equivalent to a cardano hinge (see Section 8.12.6) when one node is grounded.

8.12.8Cardano rotation

This joint implements a “Cardano” joint, which is made of a sequence of two revolute hinges orthogonal
to each other. The relative position is not constrained. See the cardano hinge for more details.
<joint_type> ::= cardano rotation<joint_arglist> ::=<node_1_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ]Note: this is equivalent to a cardano hinge (see Section 8.12.6) without position constraint. Or,in other words, a cardano hinge (see Section 8.12.6) is made of a cardano rotation on top of aspherical hinge (see Section 8.12.43).

8.12.9

Clamp

This joint grounds all 6 degrees of freedom of a node in an arbitrary position and orientation that remains
fixed.
<joint_type> ::= clamp<joint_arglist> ::= <node_label> ,[ position , ]{ node | (Vec3) <absolute_position> } ,[ orientation , ]{ node | (OrientationMatrix) <absolute_orientation_matrix> }The keyword node forces the joint to use the node’s position and reference frame. Otherwise, they must
be entered in the usual way for these entities. The default value for position and orientation are theposition and the orientation of the clamped node.
Private Data
The following data are available:
1. "Fx" constraint reaction force in global direction 1
2. "Fy" constraint reaction force in global direction 2229

3. "Fz" constraint reaction force in global direction 3
4. "Mx" constraint reaction moment in local direction 1
5. "My" constraint reaction moment in local direction 2
6. "Mz" constraint reaction moment in local direction 3

8.12.10

Coincidence

not implemented yet, use a spherical hinge (see Section 8.12.43) and a prismatic instead.

8.12.11

Deformable Axial Joint

This joint implements a configuration dependent moment that is exchanged between two nodes aboutan axis rigidly attached to the first node. It is intended to be used in conjunction with another jointthat constrains the relative rotation between the two nodes about the other axes, although no check isin place.
<joint_type> ::= deformable axial joint<joint_arglist> ::=<node_1_label>[ , position , (Vec3) <relative_offset_1> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , position , (Vec3) <relative_offset_2> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,(ConstitutiveLaw<1D>) <const_law>
Private Data
The following data are available:
1. "rz" relative rotation about axis 3, used as strain in the constitutive law
2. "wz" relative angular velocity about axis 3, used as strain rate in the constitutive law
3. "Mz" moment about axis 3, output by the constitutive law
In addition, the joint provides access to any private data provided by the constitutive law. They areaccessed by prefixing the name of the data with the string "constitutiveLaw."; see the specific constitutive law description of the available data in Section 2.10.
Hints
When wrapped by a driven element, the deformable axial joint honors the following hints:• hinge{1} the orientation with respect to node 1 of the reference used to compute the linear strain
is reset to the value resulting from the node 2 hinge orientation and the node 1 orientationR̃1h = RT1 R2 R̃2h

230

• hinge{2} the orientation with respect to node 2 of the reference used to compute the linear strain
is reset to the value resulting from the node 1 hinge orientation and the node 2 orientationR̃2h = RT2 R1 R̃1h
• unrecognized hints are passed through to the constitutive law.
OutputIn addition to the standard output, the deformable axial joint outputs:• column 14: the relative rotation about axis 3
If the constitutive law is either viscous or viscoelastic:• column 15: the relative angular velocity about axis 3

8.12.12

Deformable displacement hinge

Deprecated; use the deformable displacement joint (see Section 8.12.13) instead.

8.12.13

Deformable displacement joint

This joint implements a configuration dependent force that is exchanged between two points associatedto two nodes with an offset. The force may depend, by way of a generic 3D constitutive law, on therelative position and velocity of the two points, expressed in the reference frame of node 1.
The constitutive law is attached to the reference frame of node 1, so the sequence of the connections
may matter in case of anisotropic constitutive laws, if the relative orientation of the two nodes changes
during the analysis.
<joint_type> ::= deformable displacement joint<joint_arglist> ::=<node_1_label> ,position , (Vec3) <relative_offset_1>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> ,position , (Vec3) <relative_offset_2>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,(ConstitutiveLaw<3D>) <const_law>
Note: a variant of this element is under development, which refers the material reference frame toan orientation that is intermediate between those of the two nodes. See the invariant deformabledisplacement joint (Section 8.12.27).
Private Data
The following data are available:
1. "dx" relative displacement in node 1 local direction 1
2. "dy" relative displacement in node 1 local direction 2
3. "dz" relative displacement in node 1 local direction 3231

4. "vx" relative velocity in node 1 local direction 1
5. "vy" relative velocity in node 1 local direction 2
6. "vz" relative velocity in node 1 local direction 3
7. "Fx" constraint reaction force in node 1 local direction 1
8. "Fy" constraint reaction force in node 1 local direction 2
9. "Fz" constraint reaction force in node 1 local direction 3
In addition, the joint provides access to any private data provided by the constitutive law. They areaccessed by prefixing the name of the data with the string "constitutiveLaw."; see the specific constitutive law description of the available data in Section 2.10.
Hints
When wrapped by a driven element, the deformable displacement joint honors the following hints:• hinge{1} the orientation with respect to node 1 of the reference used to compute the linear strain
is reset to the value resulting from the node 2 hinge orientation and the node 1 orientationR̃1h = RT1 R2 R̃2h
• hinge{2} the orientation with respect to node 2 of the reference used to compute the linear strain
is reset to the value resulting from the node 1 hinge orientation and the node 2 orientationR̃2h = RT2 R1 R̃1h
• offset{1} the offset of the joint with respect to node 1 is reset to the value resulting from thenode 2 offset and the node 1 positionf˜1 = RT1 x2 + R2 f˜2 − x1
• offset{2} the offset of the joint with respect to node 2 is reset to the value resulting from thenode 1 offset and the node 2 positionf˜2 = RT2 x1 + R1 f˜1 − x2
• unrecognized hints are passed through to the constitutive law.
OutputIn addition to the standard output, the deformable displacement joint outputs:• columns 14–16: the three components of the linear strain.
If the constitutive law is either viscous or viscoelastic:• columns 17–19: the three components of the linear strain rate.

2328.12.14

Deformable Hinge

This joint implements a configuration dependent moment that is exchanged between two nodes. The
moment may depend, by way of a generic 3D constitutive law, on the relative orientation and angularvelocity of the two nodes, expressed in the reference frame of node 1.
The constitutive law is attached to the reference frame of node 1, so the sequence of the connections
may matter in case of anisotropic constitutive laws, if the relative orientation of the two nodes changes
during the analysis.
<joint_type> ::= deformable hinge<joint_arglist> ::=<node_1_label>[ , position , (Vec3) <relative_position_1> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , position , (Vec3) <relative_position_2> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,(ConstitutiveLaw<3D>) <const_law>[ , orientation description ,{ euler123 | euler313 | euler 321| orientation vector | orientation matrix } ]Note: a variant of this element has been developed, which refers the material reference frame to anorientation that is intermediate between those of the two nodes. See the invariant deformable hinge(Section 8.12.28).
Note: this joint only applies internal moments; no forces and no constraints to displacements are applied.
Usually, it is best used in conjunction with a spherical hinge (see Section 8.12.43), or any kind of jointthat constrains the relative displacement of the nodes as appropriate.
Private Data
The following data are available:
1. "rx" relative rotation vector component in node 1 local direction 1
2. "ry" relative rotation vector component in node 1 local direction 2
3. "rz" relative rotation vector component in node 1 local direction 3
4. "wx" relative angular velocity in node 1 local direction 1
5. "wy" relative angular velocity in node 1 local direction 2
6. "wz" relative angular velocity in node 1 local direction 3
7. "Mx" constraint reaction moment in node 1 local direction 1
8. "My" constraint reaction moment in node 1 local direction 2
9. "Mz" constraint reaction moment in node 1 local direction 3
In addition, the joint provides access to the private data provided by the constitutive law. They areaccessed by prefixing the name of the data with the string "constitutiveLaw."; see the specific constitutive law description of the available data in Section 2.10.
233

HintsWhen wrapped by a driven element, the deformable hinge joint honors the following hints:• hinge{1} the orientation with respect to node 1 of the reference used to compute the angular strain
is reset to the value resulting from the node 2 hinge orientation and the node 1 orientationR̃1h = RT1 R2 R̃2h
• hinge{2} the orientation with respect to node 2 of the reference used to compute the angular strain
is reset to the value resulting from the node 1 hinge orientation and the node 2 orientationR̃2h = RT2 R1 R̃1h
• unrecognized hints are passed through to the constitutive law.
OutputIn addition to the standard output, the deformable joint outputs:• columns 14–16 (or 14–22): the angular strain in the selected orientation format (either three ornine columns, according to the selected orientation description, or to its default value, see
Section 5.2.10).
If the constitutive law is either viscous or viscoelastic:• columns 17–19 (or 23–25): the three components of the angular strain rate.

8.12.15

Deformable joint

This joint implements a configuration dependent force and moment that are exchanged by two points
associated to two nodes with an offset. The force the and moment may depend, by way of a generic 6D
constitutive law, on the relative position, orientation, velocity and angular velocity of the two points,
expressed in the reference frame of node 1. It may be thought of as a combination of a deformabledisplacement joint (see Section 8.12.13) and of a deformable hinge (see Section 8.12.14); a significant
difference is that the deformable joint uses a 6D constitutive law (see Section 2.10), so the force
and the moment may both depend on the displacement and on the orientation.
The constitutive law is attached to the reference frame of node 1, so the sequence of the connections
may matter in case of anisotropic constitutive laws, if the relative orientation of the two nodes changes
during the analysis.
This element may add a considerable overhead because of the computation of the cross-coupling effects
between the forces and moments and the relative positions and orientations; if the constitutive law does
not couple relative displacements and orientations, a better choice consists in combining a deformablehinge and a deformable displacement joint.
<joint_type> ::= deformable joint<joint_arglist> ::=<node_1_label> ,position , (Vec3) <relative_offset_1>[ , orientation ,(OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> ,position , (Vec3) <relative_offset_2>234[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,(ConstitutiveLaw<6D>) <const_law>[ , orientation description ,{ euler123 | euler313 | euler 321| orientation vector | orientation matrix } ]Private Data
The following data are available:
1. "dx" relative displacement in node 1 local direction 1
2. "dy" relative displacement in node 1 local direction 2
3. "dz" relative displacement in node 1 local direction 3
4. "rx" relative rotation vector component in node 1 local direction 1
5. "ry" relative rotation vector component in node 1 local direction 2
6. "rz" relative rotation vector component in node 1 local direction 3
7. "vx" relative velocity in node 1 local direction 1
8. "vy" relative velocity in node 1 local direction 2
9. "vz" relative velocity in node 1 local direction 3
10. "wx" relative angular velocity in node 1 local direction 1
11. "wy" relative angular velocity in node 1 local direction 2
12. "wz" relative angular velocity in node 1 local direction 3
13. "Fx" constraint reaction force in node 1 local direction 1
14. "Fy" constraint reaction force in node 1 local direction 2
15. "Fz" constraint reaction force in node 1 local direction 3
16. "Mx" constraint reaction moment in node 1 local direction 1
17. "My" constraint reaction moment in node 1 local direction 2
18. "Mz" constraint reaction moment in node 1 local direction 3
In addition, the joint provides access to the private data provided by the constitutive law. They areaccessed by prefixing the name of the data with the string "constitutiveLaw."; see the specific constitutive law description of the available data in Section 2.10.
Hints
When wrapped by a driven element, the deformable joint honors the same hints of the deformabledisplacement joint.

235

Output
In addition to the standard output, the deformable joint outputs:• columns 14–16: the three components of the linear strain;• columns 17–19 (or 17–25): the angular strain in the selected orientation format (either three ornine columns, according to the selected orientation description, or to its default value, see
Section 5.2.10).
If the constitutive law is either viscous or viscoelastic:• columns 20–22 (or 26–28): the three components of the linear strain rate;• columns 23–25 (or 29–31): the three components of the angular strain rate.

8.12.16

Distance

This joint forces the distance between two points, each relative to a node, to assume the value indicatedby the drive. If no offset is given, the points are coincident with the node themselves.
<joint_type> ::= distance<joint_arglist> ::=<node_1_label> ,[ position , <relative_offset_1> , ]<node_2_label> ,[ position , <relative_offset_2> , ]{ (DriveCaller) <distance> | from nodes }The relative_offset_* are the distances of each end of the joint from the relative nodes in the node
reference frame. The distance and the distance with offset joints do not allow null distance.
Note: in case the keyword from nodes is used, a constant drive caller is automatically instantiatedfor the distance. Its value is computed from the initial positions of the nodes; if defined, the distance
between the offsets is considered.
Current
When parsing the drive caller, the following values are made available through the model::current
interface:• "L": the distance between the points connected by the joint, as it would be computed when fromnodes is used.
For example, to smoothly change the distance from the initial value to a desired value:
set: const integer DISTANCE = 99;
set: const integer NODE1 = 1;
set: const integer NODE2 = 2;
set: const real DESIRED_DISTANCE = .33;
# ...
joint: DISTANCE, distance,
NODE1, position, null,
NODE2, position, null,236

cosine, 0., pi/.5,(DESIRED_DISTANCE - model::current("L"))/2, # half (desired - initial)
half,model::current("L");# start from initial
Output
The extra output is:• the three components of the imposed distance in the global frame• the norm of the imposed distancePrivate Data
The following data are available:
1. "d" enforced distance
Hints
When wrapped by a driven element, the following hints are honored:• unrecognized hints are passed through to the distance drive.

8.12.17

Distance with offset

This element has been deprecated in favor of the distance joint element, which now supports offsets. It
may be dropped in future releases.
Private Data
See the distance joint element.

8.12.18

Drive displacement

This joint imposes the relative position between two points optionally offset from two structural nodes,
in the form of a vector that expresses the direction of the displacement in the reference frame of node 1,
whose amplitude is defined by a drive.
<joint_type> ::= drive displacement<joint_arglist> ::=<node_1_label> , (Vec3) <offset_1> ,<node_2_label> , (Vec3) <offset_2> ,(TplDriveCaller<Vec3>) <relative_position>
This element is superseded by the total joint, see Section 8.12.46.

237

Private Data
The following data are available:
1. "dx" imposed displacement component along node 1 axis 1
2. "dy" imposed displacement component along node 1 axis 2
3. "dz" imposed displacement component along node 1 axis 3
4. "fx" reaction force component along node 1 axis 1
5. "fy" reaction force component along node 1 axis 2
6. "fz" reaction force component along node 1 axis 3
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to node 1 is reset by pointing to the drive displacement
point;• offset{2} the offset of the joint with respect to node 2 is reset by pointing to the drive displacement
point;• unrecognized hints are passed through to the TplDriveCaller<Vec3>.

8.12.19

Drive displacement pin

This joint imposes the absolute position of a point optionally offset from a structural node, in the form ofa vector that expresses the direction of the displacement in the absolute reference frame, whose amplitudeis defined by a drive.
<joint_type> ::= drive displacement pin<joint_arglist> ::=<node_label> , (Vec3) <node_offset> ,(Vec3) <offset> ,(TplDriveCaller<Vec3>) <position>
This element is superseded by the total pin joint, see Section 8.12.47.
Private Data
The following data are available:
1. "dx" imposed displacement component along absolute axis 1
2. "dy" imposed displacement component along absolute axis 2
3. "dz" imposed displacement component along absolute axis 3
4. "fx" reaction force component along absolute axis 1
5. "fy" reaction force component along absolute axis 2
6. "fz" reaction force component along absolute axis 3
238

HintsWhen wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to the node is reset by pointing to the driven
displacement point;• offset{0} the offset of the joint with respect to the absolute reference frame is reset by pointing
to the driven displacement point;• unrecognized hints are passed through to the TplDriveCaller<Vec3>.

8.12.20

Drive hingeThis joint imposes the relative orientation between two nodes, in the form of a rotation about an axis
whose amplitude is defined by a drive.
<joint_type> ::= drive hinge<joint_arglist> ::=<node_1_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,(TplDriveCaller<Vec3>) <hinge_orientation>
This element is superseded by the total joint, see Section 8.12.46.
Note: this element is experimental; now it is more reliable, but it is limited to khinge_orientationk <π.
Private Data
The following data are available:
1. "rx" imposed relative rotation about node 1 hinge axis 1
2. "ry" imposed relative rotation about node 1 hinge axis 2
3. "rz" imposed relative rotation about node 1 hinge axis 3
4. "Mx" reaction moment about node 1 hinge axis 1
5. "My" reaction moment about node 1 hinge axis 2
6. "Mz" reaction moment about node 1 hinge axis 3
When wrapped by a driven element, the following hints are honored:• hinge{1} the orientation with respect to node 1 of the reference in which the enforced orientation
is expressed is reset;• hinge{2} the orientation with respect to node 2 of the reference in which the enforced orientation
is expressed is reset;• unrecognized hints are passed through to the TplDriveCaller<Vec3>.
239

8.12.21

Gimbal hingeThis joint has not been implemented yet; use a gimbal rotation and a spherical hinge (see Section 8.12.43) to emulate.

8.12.22

Gimbal rotation

A homokinetic joint without position constraints; this joint, in conjunction with a spherical hinge(see Section 8.12.43) joint, should be used to implement an ideal tiltrotor gimbal instead of a cardano
rotation (see Section 8.12.8). See the technical manual and [19] for details. It is equivalent to a series of
two Cardano’s joints (the cardano hinge, see Section 8.12.6) rotated 90 degrees apart, each accounting
for half the relative rotation between axis 3 of each side of the joint.
<joint_type> ::= gimbal rotation<joint_arglist> ::=<node_1_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ][ , orientation description ,{ euler123 | euler313 | euler321| orientation vector | orientation matrix } ]This joint allows nodes 1 and 2 to rotate about relative axes 1 and 2.
Output
The gimbal rotation joint outputs the three components of the reaction couple in the local frame (thatof node 1) and in the global frame.
The extra columns 14 and 15 contain the angles ϑ and ϕ. The extra columns from 16 on contain therelative rotation between nodes 1 and 2, in the format determined either by an explicit selection of theorientation description, or by the default orientation description defined by the default orientation
keyword (see Section 5.2.10).
The three components of the reaction couple in the local frame, and the angles ϑ and ϕ are alsoavailable as private data of the element under the names lambda[<i>], with i=1,2,3, theta and phi.
For a description of the formulation and of the angles describe above, see the Technical Manual.
Private Data
The following data are available:
1. "lambda[1]" constraint reaction moment about node 1 local axis 1
2. "lambda[2]" constraint reaction moment about node 1 local axis 2
3. "lambda[3]" constraint reaction moment about node 1 local axis 3
4. "theta" relative angle ϑ
5. "phi" relative angle ϕ240

8.12.23

Imposed displacement

This joint imposes the relative position between two points, optionally offset from two structural nodes,
along a given direction that is rigidly attached to the first node. The amplitude of the displacement isdefined by a drive.
<joint_type> ::= imposed displacement<joint_arglist> ::=<node_1_label> , (Vec3) <offset_1> ,<node_2_label> , (Vec3) <offset_2> ,(Vec3) <direction> ,(DriveCaller) <relative_position>
This element is superseded by the total joint, see Section 8.12.46.
Private Data
The following data are available:
1. "d" imposed displacement along direction, in node 1 reference frame;
2. "f" reaction force along direction, in node 1 reference frame.
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to node 1 is reset by pointing exactly to the imposed
displacement point;• offset{2} the offset of the joint with respect to node 2 is reset by pointing exactly to the imposed
displacement point;• unrecognized hints are passed through to the drive.

8.12.24

Imposed displacement pin

This joint imposes the absolute displacement of a point optionally offset from a structural node, along
a direction defined in the absolute reference frame. The amplitude of the displacement is defined by adrive.
<joint_type> ::= imposed displacement pin<joint_arglist> ::=<node_label> , (Vec3) <node_offset> ,(Vec3) <offset> ,(Vec3) <direction> ,(DriveCaller) <position>
This element is superseded by the total pin joint, see Section 8.12.47.

241

Private Data
The following data are available:
1. "x" imposed displacement along direction, in the absolute reference frame;
2. "f" reaction force along direction, in the absolute reference frame.
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to the node is reset by pointing exactly to the imposed
displacement point;• offset{0} the offset of the joint with respect to the absolute reference frame is reset by pointing
exactly to the imposed displacement point;• unrecognized hints are passed through to the drive.

8.12.25

In lineThis joint forces a point relative to the second node to move along a line attached to the first node.
<joint_type> ::= in line
<joint_arglist> ::=<node_1_label> ,[ position , (Vec3) <relative_line_position> , ][ orientation , (OrientationMatrix) <relative_orientation> , ]<node_2_label>[ , offset , (Vec3) <relative_offset> ]A point, optionally offset by relative_offset from the position of node node_2_label, slides along aline that passes through a point that is rigidly offset by relative_line_position from the position of
node_1_label, and is directed as direction 3 of relative_orientation. The joint is shown in Figure 8.9
where the origin and orientation of node_1 are given by axis 1′ , 2′ , 3′ and relative_line_position andrelative_orientation are the transformations that yield axis 1′0 , 2′0 , 3′0 when applied to its coordinate
axis. The origin and orientation of node_2 are given by axis 1, 2, 3 and axis 10 , 20 , 30 is the result ofapplying the relative_offset translation to its coordinate axis.

8.12.26

In planeThis joint forces a point relative to the second node to move in a plane attached to the first node.
<joint_type> ::= in plane<joint_arglist> ::=<node_1_label> ,[ position , (Vec3) <relative_plane_position> , ]((Unit)Vec3) <relative_normal_direction> ,<node_2_label>[ , offset , (Vec3) <relative_offset> ]242

Figure 8.9: Inline joint.
A point, optionally offset by relative_offset from the position of node node_2_label, slides on aplane that passes through a point that is rigidly offset by relative_plane_position from the position of
node_1_label, and is perpendicular to relative_normal_direction. The vector relative_normal_direction
is internally normalized to unity.

8.12.27

Invariant deformable displacement joint

Under development; right now, use the deformable displacement joint (see Section 8.12.13) instead.

8.12.28

Invariant deformable hingeThis (experimental) element is a variant of the deformable hinge (see Section 8.12.14); refer to thatjoint for the input syntax.
The invariant form of the deformable hinge joint refers the constitutive law to an orientation that isintermediate between those of the nodes it connects. As a result, the moment exchanged between thetwo nodes is invariant to the sequence of definition of the nodes when anisotropic constitutive laws areused. It is worth stressing that determining the constitutive law for this element may be tricky, since
usual measurement approaches directly measure forces and moments in a reference frame that is attached
to one of the two ends of the component, so in practical cases it might be more appropriate to use thevariant form of the joint, and consistently referring the constitutive law to the same end used to measure
the mechanical properties of the component.

8.12.29

Linear acceleration

This joint imposes the absolute linear acceleration of a node along a given axis.
<joint_type> ::= linear acceleration<joint_arglist> ::=<node_label> ,((Unit)Vec3) <relative_direction> ,(DriveCaller) <acceleration>
243

The axis is relative_direction; it is internally normalized to unity.
Private Data
The following data are available:
1. "F" constraint reaction force along joint direction
2. "a" imposed acceleration along joint direction

8.12.30

Linear velocity

This joint imposes the absolute linear velocity of a node along a given axis.
<joint_type> ::= linear velocity<joint_arglist> ::=<node_label> ,((Unit)Vec3) <relative_direction> ,(DriveCaller) <velocity>
The axis is relative_direction; it is internally normalized to unity.
Private Data
The following data are available:
1. "v" imposed velocity along joint direction

8.12.31

Modal

Original implementation: Felice Felippone;
Initial review: Giuseppe Quaranta;
Current review: Pierangelo Masarati.
This joint implements a Component Mode Synthesis (CMS) deformable body. Its interface with themultibody domain is represented by clamps that constrain the multibody interface nodes to the positionand orientation of the corresponding FEM nodes.
<joint_type> ::= modal<joint_arglist> ::={ <reference_modal_node> | clamped[ , position , (Vec3) <absolute_position> ][ , orientation , (OrientationMatrix) <absolute_orientation> ] } ,<mode_number> ,[ list , <mode> [ , ... ] , ][ initial value ,{ mode , <j> , <q_j> , <qP_j> [ , ... ] # 1 <= j <= mode_number| <q_1> , <qP_1> [ , ... ] } , ]{ <fem_node_number> | from file } ,[ { no damping| damping from file| rayleigh damping , <mass_damping_coef> , <stiffness_damping_coef>244

| single factor damping , <damping_factor>| diag damping ,{ all , <damping_factor> [ , ...]
| <num_damped_modes> , <mode_damping> [ , ... ] } } , ]" <fem_data_file> " ,[ [ { mass | damping | stiffness } ] threshold , <threshold> , ][ { create binary | use binary | update binary }[ , ... ] , ][ echo , " <echo_fem_data_file> " [ , precision , <precision_digits> ] , ][ use invariant 9 , ][ { origin node , <origin_node> | origin position , (Vec3) <pos> } , ]<interface_nodes_number> ,[ output , { yes | no | (bool)<output_flag_for_all_interfaces> } , ]<interface_node> [ , ... ]<mode_damping> ::= <mode_index> , <mode_damping_factor><interface_node> ::={ " <fem_node_label> " | (integer) <fem_node_label> } ,<multibody_label> , (Vec3) <offset_of_FEM_node>[ , output , { yes | no | (bool)<output_flag_for_this_interface> } ]The reference_modal_node is a special dynamic structural node that is required to handle the rigid
body motion of the modal joint. Its input is completely analogous to that of the dynamic structuralnodes, see Section 6.1, only the keyword dynamic must be replaced by modal.
If no rigid body dynamics is required, e.g. if the modal element is clamped, the clamped option canbe used, which allows to set the optional absolute_position and absolute_orientation. The former
is the location, in the multibody global reference system, of the origin of the FEM reference system.
The latter is the orientation, in the multibody global reference frame, of the FEM reference system.
They default to zero and identity, which means that the global multibody reference frame and the FEM
reference system are coincident.
The mode count in mode_number is not required to match the number of modes listed in the FEM
data file; if a lower number is given, only the first mode_number modes are used; moreover, a list of activemodes can be given, to use non-consecutive modes; e.g., to use modes 1, 2, 3 and 6 out of a set of 10
modes defined in the FEM data file, write...,
4,list, 1, 2, 3, 6,...

# number of active modes# list of active modes

By default, the origin of the FEM grid is placed either in the position of the modal node, with its
orientation, or in the absolute position and orientation in case the modal element is clamped, unless oneof the mutually exclusive origin node and origin position optional keywords is used. The origin
node keyword defines what FEM node corresponds to the modal node in the multibody domain, or what
FEM node corresponds to the optional absolute position and orientation in case of a clamped modal
element. The origin position keyword defines where, in the FEM model reference frame, the modal
node is placed, or the location that corresponds to the optional absolute position and orientation in caseof a clamped modal element.
Note that having the modal node coincident with a FEM node does not guarantee that the two remain
coincident during the analysis. This is only true if the modal shapes corresponding to the FEM node are245

identically zero (i.e. in case of attached modes). Otherwise, the FEM node initially coincident with themodal node departs from it as long as the modal coordinates are non-zero.
The FEM labels can be strings made of any character, provided they do not contain blanks. The
strings must be enclosed in double quotes. For legacy reasons, a label not enclosed in double quotes is
accepted, provided it is an integer.
If any of mass threshold, damping threshold, stiffness threshold are given, elements whose
absolute value is lower than the threshold are discarded from the mass, damping and stiffness matrices,
respectively. The keyword threshold is a catchall for all, meaning that the same threshold is used forall matrices.
The list of matchings between FEM and multibody nodes needs special care. The offset_of_FEM_node
field contains the distance of the FEM node from the respective multibody node; by default, this is expressed in the reference frame of the multibody node.
The fem_data_file can be generated by NASTRAN, following the procedure illustrated in Appendix A.3.
It is strongly recommended that constrained modal analysis be used for otherwise free bodies, withthe statically determined constraint consisting of clamping the FEM node that will coincide with thenode indicated as reference_modal_node, and using the origin node to make that point the origin of
the FEM frame.
Note about reference frames: the coincidence constraint between multibody and FEM nodes iswritten between the local frame of the FEM node and the global frame of the multibody node. As such,the multibody nodes must be oriented as the modal node the modal joint refers to, if any, or as thereference orientation of the modal joint, if it is clamped.
Note about initial assembly: it is very important that multibody and FEM nodes at interfaces
are given with a high degree of accuracy, because the initial assembly procedure of the modal element
does not behave very well (it’s on the TODO list with a very low priority); as a consequence, pay verymuch attention to the input of these nodes, until more robust procedures are developed. One trick is
to build models incrementally. Note: offsets between FEM and multibody nodes should be avoided unlessstrictly required.
Note about the FEM file: the format of the fem_data_file is relatively straightforward; it isreported in Appendix A.1. Initial modal displacements and velocities can be added, if required, by
manually editing the file; however this practice is discouraged, unless strictly required.
Note about large FEM files: using a very large fem_data_file may require long time for readingand parsing ASCII floats. The keyword use binary instructs MBDyn to use a binary version of the
fem_data_file. This binary version is automatically generated by MBDyn if requested by means of the
keyword create binary. The binary version of the fem_data_file is used only if its timestamp is more
recent than that of the ASCII version. The keyword update binary instructs MBDyn to regenerate thebinary version when the ASCII version is more recent.
Note about structural damping: information about structural damping can be provided by
specifying any of the no damping, damping from file, rayleigh damping, single factor damping,or diag damping keywords.
• no damping: instructs the solver that no damping must be used.
• damping from file: the solver expects a(n optional) generalized damping matrix in the database(as RECORD GROUP 13); such matrix is used when damping from file is specified, while it isignored and overridden by any of the other specified forms of damping provided in the specificationof the modal joint element. The generalized damping matrix appeared in MBDyn 1.5.3;• rayleigh damping: it is followed by mass_damping_coef and stiffness_damping_coef, which246

are used to compute the damping matrix as
C = mass_damping_coef · M + stiffness_damping_coef · K(8.70)

It appeared in MBDyn 1.7.1.
• single factor damping: it is followed by the damping factor ξ = damping_factor that is applied
to all modes. It appeared in MBDyn 1.7.1.
• diag damping: it is followed by the number of damped modes num_damped_modes, or by the
keyword all. If all is used, as many damping factors as the available modes are expected.
Otherwise, a list of mode_damping values follows. Each occurrence of mode_damping is made of themode’s index mode_index and the related damping value damping_factor.
In the last two cases, a damping factor is required. The corresponding damping for the i-th mode iscomputed aspci = 2 damping_factori ki mi

where damping_factori is the value provided for the list of values provided for diag damping (for eachmode). For example, a factor of 0.01 means 1% damping.
In previous versions, a (misleading) proportional damping form was present, which is now deprecated and replaced by single factor damping.
OutputUp to MBDyn 1.2.6, output occurred in a specific file that needed to be mandatorily given as the lastargument to each modal element definition.
Now output occurs in a .mod file, which contains, for each time step, as many rows as all the modesof all the modal elements whose output is enabled. Each row is structured as follows:• a field containing the label of the modal joint and the number of the mode, separated by a dot (e.g.
label.mode)• the value of the modal unknown• the value of the first derivative of the modal unknown• the value of the second derivative of the modal unknown
Note: the number of the mode in the first field of the output, after the dot, is the ordinal of the modein the FEM data file. If only a portion of the modes was selected using the list keyword, the mode
numbers will reflect the selected modes. For example, if the modal joint was defined as
set: MODAL_ELEM = 99;
set: MODAL_NODE = 101;
joint: MODAL_ELEM, modal, MODAL_NODE,3, list, 1, 7, 9, # only use modes 1, 7 and 9 of a larger basis
from file,"modal.fem",0;# no fem nodes
the output will look like99.1 0.000000e+00 0.000000e+00 0.000000e+00
99.7 0.000000e+00 0.000000e+00 0.000000e+00
99.9 0.000000e+00 0.000000e+00 0.000000e+00
247

The global motion of the n-th point on the FEM mesh is given by the formulaxn = xmodal + Rmodal (f0n + f1n q)(8.71)

where xmodal and Rmodal are the position vector and the orientation matrix of the modal node, if any,
f0n is the position of the n-th point in the floating frame of reference, f1n is the matrix of the shapesthat express the displacement on the n-th point in the floating frame of reference, and q are the modal
coordinates, i.e. the data in column 2 of the modal output file. In the Private Data, the i-th componentof the position of the n-th node is given by "x[<n>,<i>]" (see the related section for details).
Private Data
The following data are available:
1. "q[<mi>]" the value of the mode amplitude indicated by mi
2. "qP[<mi>]" the value of the mode amplitude derivative indicated by mi
3. "qPP[<mi>]" the value of the mode amplitude second derivative indicated by mi
4. "x[<n>,<i>]" FEM node n position i component value
5. "xP[<n>,<i>]" FEM node n velocity i component value
6. "xPP[<n>,<i>]" FEM node n acceleration i component value
7. "w[<n>,<i>]" FEM node n angular velocity i component value
8. "wP[<n>,<i>]" FEM node n angular acceleration i component value
When the mode indicator mi is a number <m>, then m represents the name of mode; when mi is thecharacter ‘#’ followed by a number <m>, then m is the index of the mode. The two cases may differ when
only a subset of the modes defined in the FEM data file are actually used. For example, if mode_number== 3 and in the joint definition the syntax “list, 1, 7, 9” was used, to indicate that of the threemodes to be used in the analysis the first mode is the first one in the database, whereas the second modeis the seventh one in the database, and the third mode is the ninth one in the database, then "q[1]" isequivalent to "q[#1]", whereas "q[7]" is equivalent to "q[#2]", and "q[9]" is equivalent to "q[#3]",
and possibly more readable.
“FEM” node means that the label of the FEM node must be used; this allows access also to the
motion of nodes that are not attached to a multibody node. Such motion is intended as expressed in the
global reference frame. No information on FEM node orientation is currently available. For example,"x[1001,1]" provides access to the x component of the position of node 1001; "xPP[N21,3]" provides
access to the z component of the acceleration of node N21.

8.12.32

Plane displacement

This joint allows two nodes to move in the common relative 1–2 plane and to rotate about the common
relative axis 3.
<joint_type> ::= plane displacement<joint_arglist> ::=<node_1_label> ,position , (Vec3) <relative_offset_1>248

[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> ,position , (Vec3) <relative_offset_2>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ]Note: this element is temporarily disabled; combine an in plane and a revolute rotation (see Section 8.12.39) joint, or use the total joint, see Section 8.12.46.

8.12.33

Plane displacement pin

This joint allows a node to move in the relative 1–2 plane and to rotate about the relative axis 3 withrespect to an absolute point and plane. See also Section 8.12.32.
<joint_type> ::= plane displacement pin<joint_arglist> ::=<node_label> ,position , (Vec3) <relative_offset>[ , orientation , (OrientationMatrix) <relative_orientation_matrix> ] ,position , (Vec3) <absolute_pin_position>[ , orientation , (OrientationMatrix) <absolute_pin_orientation_matrix> ]Note: this element is temporarily disabled; combine an in plane and a revolute rotation (see Section 8.12.39) joint instead, using a grounded node, or use a total pin joint, see Section 8.12.47.

8.12.34

Plane hingeThis joint has been renamed revolute hinge (see Section 8.12.37); the old name has been deprecatedand its support may be discontinued in future versions.

8.12.35

Plane pinThis joint has been renamed revolute pin (see Section 8.12.38); the old name has been deprecated andits support may be discontinued in future versions.

8.12.36

Prismatic

This joints constrains the relative orientation of two nodes, so that their orientations remain parallel.
The relative position is not constrained. The initial orientation of the joint must be compatible: use theorientation keyword to assign the joint initial orientation.
<joint_type> ::= prismatic<joint_arglist> ::=<node_1_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ] ,249

HintsWhen wrapped by a driven element, the following hints are honored:• hinge{1} the relative orientation of the joint with respect to node 1 is reset;• hinge{2} the relative orientation of the joint with respect to node 2 is reset;

8.12.37

Revolute hingeThis joint only allows the relative rotation of two nodes about a given axis, which is axis 3 in the reference
systems defined by the two orientation statements.
<joint_type> ::= revolute hinge<joint_arglist> ::=<node_1_label> ,position , (Vec3) <relative_offset_1>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label> ,position , (Vec3) <relative_offset_2>[ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ][ , initial theta , <initial_theta> ][ , friction , <average_radius> ,[ preload , <const_value> , ]<friction_model> ,<shape_function> ]The joint is shown in Figure 8.10 where the axes shown are the those obtained after having applied
the relative_offset and relative_orientation_matrix transformations to the coordinate axes ofnode_1 and node_2.
Note: this element can be thought of as the combination of a spherical hinge (see Section 8.12.43),
that constrains the three components of the relative position of the nodes, and of a revolute rotation(see Section 8.12.39), that constrains the relative orientation of the nodes so that only rotation about acommon axis is allowed.
Rationale
The rationale for having two statements to indicate the position and orientation of the same entity isthat the joint is supposed to constrain the position and orientation of two points, each attached to anode. This is what is typically known from the geometry of the components of a mechanism.
OutputThe output occurs in the .jnt file, according to default joint output for the first 13 columns; specificcolumns contain:• columns 14–16: the so-called Euler angles (in degrees) that describe the relative rotation; only thethird component is relevant, the first two essentially indicate the accuracy of the rotation constraint;• column 17–19: the relative angular velocity; only the third component is relevant, the first two arezero.
If friction is present:
250

Figure 8.10: Revolute hinge.
• column 20: the friction moment about the revolute axis;• subsequent columns: any friction model specific data.
Private Data
The following data are available:
1. "rz" relative rotation angle about revolute axis
2. "wz" relative angular velocity about revolute axis
3. "Fx" constraint reaction force in node 1 local direction 1
4. "Fy" constraint reaction force in node 1 local direction 2
5. "Fz" constraint reaction force in node 1 local direction 3
6. "Mx" constraint reaction moment about node 1 local direction 1
7. "My" constraint reaction moment about node 1 local direction 2
8. "Mz" constraint reaction moment about node 1 local direction 3
Hints
When wrapped by a driven element, the following hints are honored:• hinge{1} the relative orientation of the joint with respect to node 1 is reset;251• hinge{2} the relative orientation of the joint with respect to node 2 is reset;• offset{1} the offset of the joint with respect to node 1 is reset;• offset{2} the offset of the joint with respect to node 2 is reset;• unrecognized hints are passed through to the friction model, if any.

8.12.38

Revolute pin

This joint only allows the absolute rotation of a node about a given axis, which is axis 3 in the reference
systems defined by the two orientation statements.
<joint_type> ::= revolute pin<joint_arglist> ::=<node_label> ,position, (Vec3) <relative_offset>[ , orientation, (OrientationMatrix) <relative_orientation_matrix> ] ,position , (Vec3) <absolute_pin_position>[ , orientation , (OrientationMatrix) <absolute_pin_orientation_matrix> ][ , initial theta , <initial_theta> ]Note: this is equivalent to a revolute hinge (see Section 8.12.37) when one node is grounded.
Private Data
The following data are available:
1. "rz" relative rotation angle about revolute axis
2. "wz" relative angular velocity about revolute axis
3. "Fx" constraint reaction force in node 1 local direction 1
4. "Fy" constraint reaction force in node 1 local direction 2
5. "Fz" constraint reaction force in node 1 local direction 3
6. "Mx" constraint reaction moment about node 1 local direction 1
7. "My" constraint reaction moment about node 1 local direction 2
8. "Mz" constraint reaction moment about node 1 local direction 3
Hints
When wrapped by a driven element, the following hints are honored:• hinge{1} the relative orientation of the joint with respect to the node is reset;• hinge{0} the relative orientation of the joint with respect to the absolute frame is reset;• offset{1} the offset of the joint with respect to the node is reset;• offset{0} the offset of the joint with respect to the absolute frame is reset;252

8.12.39

Revolute rotation

This joint allows the relative rotation of two nodes about a given axis, which is axis 3 in the reference
systems defined by the two orientation statements. The relative position is not constrained.
<joint_type> ::= revolute rotation<joint_arglist> ::=<node_1_label>[ , position , (Vec3) <relative_offset_1> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_1> ] ,<node_2_label>[ , position , (Vec3) <relative_offset_2> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ]Rationale
A revolute joint without position constraints; this joint, in conjunction with an inline joint, should be
used to constrain, for example, the two nodes of a hydraulic actuator.
Private Data
The following data are available:
1. "rz" relative rotation angle about revolute axis
2. "wz" relative angular velocity about revolute axis
3. "Mx" constraint reaction moment about node 1 local direction 1
4. "My" constraint reaction moment about node 1 local direction 2
5. "Mz" constraint reaction moment about node 1 local direction 3
Hints
When wrapped by a driven element, the following hints are honored:• hinge{1} the relative orientation of the joint with respect to node 1 is reset;• hinge{2} the relative orientation of the joint with respect to node 2 is reset;

8.12.40

Rod

The rod element represents a force between two nodes that depends on the relative position and velocityof two points, each rigidly attached to a structural node. The direction of the force is also based on
the relative position of the points: it is the line that passes through them. If no offset is defined, thepoints are the nodes themselves.
The syntax is:<joint_type> ::= rod<joint_arglist> ::=<node_1_label> ,253

[ position , (Vec3) <relative_offset_1> , ]<node_2_label> ,[ position , (Vec3) <relative_offset_2> , ]{ (real) <rod_length> | from nodes }(ConstitutiveLaw<1D>) <const_law>
The constitutive law const_law receives as input the rod axial strain
ε=l − l0,l0(8.72)

where l0 = rod_length and l is the distance between the two points; in case of viscoelastic constitutive
law, the axial strain derivativel̇(8.73)ε̇ =l0
is also used. It returns the corresponding rod axial force,
F =F

l − l0 l˙
,
l0 l0

!

.

If a prestrain εp is defined, it consists in an imposed value of the axial strain that is subtracted from thegeometrical strain before being passed to the constitutive law; if a prestress Fp is defined, it consists
in an imposed axial force value that is added to the one obtained from the constitutive law, namely!
l˙l − l0.
− εp ,
F = Fp + F
l0l0For example, a linear elastic constitutive law for the rod element is defined as
F = EAl − l0,l0

where EA is the axial stiffness of the rod.
For further details on the supported constitutive laws, see Section 2.10.
Current
When parsing the constitutive law, the following values are made available through the model::current
interface:• "L0": the length of the rod rod_length as input by the user, or computed from the distance
between the points connected by the rod when from nodes is used;• "L": the length of the rod computed from the distance between the points connected by the rod;
identical to "L0" when from nodes is used.
For example, if one knows the value of EA and wants the stiffness in a linear elastic constitutive law toreflect its dependence on the reference length of the rod as computed from the initial configuration, thefollowing syntax does the trick:
set: const integer ROD = 99;
set: const integer NODE1 = 1;
set: const integer NODE2 = 2;254

set: const real EA = 1.e+6;# ...
joint: ROD, rod,
NODE1, position, null,
NODE2, position, null,from nodes,# compute length from nodes
linear elastic, EA/model::current("L0"); # compute K as EA/rod_length
OutputThe output occurs in the .jnt file, which contains:• the label• the three components of the internal force in the reference frame of the element (column 2, component x, contains the force)• the three components of the internal moment in the reference frame of the element (always zero)• the three components of the internal force in the global reference frame• the three components of the internal moment in the global reference frame (always zero)• the length of the rod• the three components of the rod axis in the global reference frame (a unit vector)• the length rate of the rod (derivative of length wrt/ time)• optional data appended by the constitutive law
Private Data
The following data are available:
1. "F" constraint force between the two nodes/connection points
2. "L" distance between the two nodes/connection points
3. "LPrime" distance rate between the two nodes/connection points
The rod joint can also give access the private data provided by the constitutive law. It is accessed by
prefixing the name of the data with the string "constitutiveLaw."; see the specific constitutive law
description of the available data in Section 2.10.

8.12.41

Rod with offset

The syntax is:<joint_type> ::= rod with offset<joint_arglist> ::=<node_1_label> ,(Vec3) <relative_offset_1> ,<node_2_label> ,
255

x2
4
y2

y

3
y1
2
x1

1
x

Figure 8.11: The rod bezier element(Vec3) <relative_offset_2> ,{ (real) <rod_length> | from nodes } ,(ConstitutiveLaw<1D>) <const_law>
Analogous to the rod joint with the optional offsets; see Section 8.12.40 for details.

8.12.42

Rod BezierThis joint, in analogy with the rod joint, represents a force that acts between two points each rigidly
attached to a structural node.
The force on node 1 acts along the line connecting the insertion point, defined in the reference frame of
the node by <relative_offset_1> and a first intermediate point defined, also in the reference frame of
the node, by <relative_offset_2>. In the same way, the force on node 2 is applied at the insertion
point of the element, defined in the reference frame of node 2 by <relative_offset_4> and acts along
the line connecting a second intermediate point defined by <relative_offset_3>.
The element internally is represented as a Bézier spline of order 3, which length and instantaneous
lengthening velocity are calculated using Gauss-Legendre quadrature.
The absolute value of the force depends on the strain and strain rate of the curve as in the standard rod
element (see Section 8.12.40) as determined by the ConstitutiveLaw<1D> <const_law>.
The syntax is:<joint_type> ::= rod bezier<joint_arglist> ::=<node_1_label> ,(Vec3) <relative_offset_1> ,(Vec3) <relative_offset_2> ,<node_2_label> ,(Vec3) <relative_offset_3> ,(Vec3) <relative_offset_4> ,{ (real) <rod_length> | from nodes } ,[ integration order , (integer) <order> ] ,[ integration segments , (integer) <segments> ] ,(ConstitutiveLaw<1D>) <const_law>
256

Optional parameters integration order and integration segments modify the behavior Gauss-Legendre
quadrature rule used to calculate the length and the instantaneous lengthening velocity of the element.
As the name suggest, the first argument controls the order of the integration scheme; if not specified, it
defaults to 2. The maximum order of integration currently implemented is 10.
The second argument sets the number of segments in which the Bézier curve is split in the integration;
it not specified, it defaults to 3.
OutputThe output occurs in the .jnt file, which contains:• column 1: the label• columns 2–4: the three components of the internal force in the reference frame of the element(column 2, component x, contains the force)• columns 5–7: the three components of the internal moment in the reference frame of the element(always zero)• columns 8–10: the three components of the force acting on node 1 in the global reference frame• columns 11–13: the three components of the internal moment in the global reference frame (alwayszero)• columns 14–16: the three components of the force acting on node 2 in the global reference frame• column 17: the length of the rod• columns 18–20: the three components of the line of action of the force acting on node 1 in the
global reference frame (a unit vector)• columns 21–23: the three components of the line of action of the force acting on node 2 in the
global reference frame (a unit vector)• column 24: the length rate of the rot (derivative of length wrt/ time)• optional data appended by the constitutive law
Private Data
The element exposes its private data in analogy with what happens in the rod element (see Section 8.12.40).

8.12.43

Spherical hingeThis joint constrains the relative position of two nodes; the relative orientation is not constrained.
<joint_type> ::= spherical hinge<joint_arglist> ::=<node_1_label> ,[ position , (Vec3) <relative_offset_1> , ][ orientation , (OrientationMatrix) <relative_orientation_matrix_1> , ]<node_2_label>[ , position , (Vec3) <relative_offset_2> ][ , orientation , (OrientationMatrix) <relative_orientation_matrix_2> ]257

Figure 8.12: Spherical hinge.
The joint is shown in Figure 8.12 where the axes shown are the those obtained after having applied therelative_offset and relative_orientation_matrix transformations to the coordinates of node_1
and node_2. Note: the orientation matrix, set by means of the orientation keyword, is used for output
purposes only. A default identity matrix is assumed.
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to node 1 is reset;• offset{2} the offset of the joint with respect to node 2 is reset;

8.12.44

Spherical pin

This joint constrains the absolute position of a node; the relative orientation is not constrained.
<joint_type> ::= spherical pin<joint_arglist> ::=<node_label> ,[ position , (Vec3) <relative_offset> , ][ orientation , (OrientationMatrix) <relative_orientation> , ]position , (Vec3) <absolute_pin_position>[ , orientation , <absolute_orientation> ]Note: this is equivalent to a spherical hinge (see Section 8.12.43) when one node is grounded. An
alternative way to model a grounded spherical hinge requires the use of another node, clamped by aclamp joint.

258

8.12.45

Total equation

Original implementation: Alessandro Fumagalli, Marco Morandini.
See also total reaction (see Section 8.12.48). See [20]. TODO

8.12.46

Total joint

Original implementation: Alessandro Fumagalli;
Review: Pierangelo Masarati.
See [21]. This element allows to arbitrarily constrain specific components of the relative positionand orientation of two nodes. The value of the constrained components of the relative position andorientation can be imposed by means of drives. As such, this element allows to mimic the behavior ofmost ideal constraints that connect two nodes.
<joint_type> ::= total joint<joint_arglist> ::=<node_1_label>[ , position , (Vec3) <relative_offset_1> ][ , position orientation , (OrientationMatrix) <rel_pos_orientation_1> ][ , rotation orientation , (OrientationMatrix) <rel_rot_orientation_1> ], <node_2_label>[ , position , (Vec3) <relative_offset_2> ][ , position orientation , (OrientationMatrix) <rel_pos_orientation_2> ][ , rotation orientation , (OrientationMatrix) <rel_rot_orientation_2> ][ , position constraint ,<position_status> , <position_status> , <position_status> ,(TplDriveCaller<Vec3>) <imposed_relative_position> ][ , orientation constraint ,<orientation_status> , <orientation_status> , <orientation_status> ,(TplDriveCaller<Vec3>) <imposed_relative_rotation> ]<position_status> ::={ inactive | active | position | velocity | <status> }<orientation_status> ::={ inactive | active | rotation | angular velocity | <status> }The relative position imposed by the position constraint is imposed in a reference frame rigidly
attached to the first node, in the optional offset relative_offset_1, and optionally further oriented by
the rel_pos_orientation_1 matrix.
The relative orientation imposed by the orientation constraint is imposed in a reference frame
rigidly attached to the first node, optionally further oriented by the rel_rot_orientation_1 matrix. It
consists in the Euler vector that expresses the imposed relative orientation, in radian.
The keyword active means that the constraint is active with respect to that component of relative
motion, so the related motion component is constrained, while inactive means that the constraint is
not active with respect of that component of relative motion, so the related motion component is notconstrained. Otherwise, a boolean can be provided in status to indicate that the degree of constraint iseither inactive (0) or active (1); this may be useful, for instance, to make constraint activation conditionalin parametric input files. The same applies to the status of the components of the impose orientation.

259

If a component of relative position or orientation is active, the corresponding component of the imposed position or orientation is enforced, otherwise it is ignored; however, the complete three-dimensional
vectors of the imposed relative position or orientation must be provided.
When the position constraint is enforced, the keyword active is equivalent to position; if the
keyword velocity is used, the constraint imposes the velocity of that component of the relative position,
resulting in a non-holonomic constraint.
Similarly, when the orientation constraint is enforced, the keyword active is equivalent torotation; if the keyword angular velocity is used, the constraint imposed the angular velocity ofthat component of the relative orientation, resulting in a non-holonomic constraint.
OutputThe output occurs in the .jnt file, which contains:• column 1: the label• columns 2–4: the three components of the internal force in the reference frame of the element• columns 5–7: the three components of the internal moment in the reference frame of the element• columns 8–10: the three components of the internal force in the global reference frame• columns 11–13: the three components of the internal moment in the global reference frame• columns 14–16: the three components of the relative displacement in the reference frame of theelement• columns 17–19: the three components of the relative rotation vector in the reference frame of theelement• columns 20–22: the three components of the relative velocity in the reference frame of the element• columns 23–25: the three components of the relative angular velocity in the reference frame of theelement
Private Data
The following data are available:
1. "px" relative position along node 1 position orientation axis 1
2. "py" relative position along node 1 position orientation axis 2
3. "pz" relative position along node 1 position orientation axis 3
4. "rx" relative orientation about node 1 rotation orientation axis 1
5. "ry" relative orientation about node 1 rotation orientation axis 2
6. "rz" relative orientation about node 1 rotation orientation axis 3
7. "Fx" reaction force about node 1 position orientation axis 1
8. "Fy" reaction force about node 1 position orientation axis 2
9. "Fz" reaction force about node 1 position orientation axis 3260

10. "Mx" reaction moment about node 1 rotation orientation axis 1
11. "My" reaction moment about node 1 rotation orientation axis 2
12. "Mz" reaction moment about node 1 rotation orientation axis 3
13. "dx" imposed relative position along node 1 position orientation axis 1
14. "dy" imposed relative position along node 1 position orientation axis 2
15. "dz" imposed relative position along node 1 position orientation axis 3
16. "tx" imposed relative orientation about node 1 rotation orientation axis 1
17. "ty" imposed relative orientation about node 1 rotation orientation axis 2
18. "tz" imposed relative orientation about node 1 rotation orientation axis 3
19. "vx" relative velocity along node 1 rotation orientation axis 1
20. "vy" relative velocity along node 1 rotation orientation axis 2
21. "vz" relative velocity along node 1 rotation orientation axis 3
22. "wx" relative angular velocity about node 1 rotation orientation axis 1
23. "wy" relative angular velocity about node 1 rotation orientation axis 2
24. "wz" relative angular velocity about node 1 rotation orientation axis 3
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to node 1 is reset;• offset{2} the offset of the joint with respect to node 2 is reset;• position-hinge{1} the relative orientation of the relative position constraint with respect to node
1 is reset;• position-hinge{2} the relative orientation of the relative position constraint with respect to node
2 is reset;• orientation-hinge{1} the relative orientation of the relative orientation constraint with respect
to node 1 is reset;• orientation-hinge{2} the relative orientation of the relative orientation constraint with respect
to node 2 is reset;• position-drive3 resets the relative position drive; the hint is passed to the Vec3 drive hint parser.
• orientation-drive3 resets the relative orientation drive; the hint is passed to the Vec3 drive hintparser.

261

Example. This example mimicks an instance of NASTRAN’s RBE2 element that constrains displacement in x and y, and rotation about z:
set: const integer EID = 100;
set: const integer GN = 200;
set: const integer GM1 = 300;
# ...
# $.......2.......3.......4.......5.......
# RBE2
EID
GN
CM
GM1
joint: EID, total joint,GN,position, reference, node, null,position orientation, reference, node, eye,rotation orientation, reference, node, eye,
GM1,
position, reference, other node, null,position orientation, reference, other node, eye,rotation orientation, reference, other node, eye,position constraint,
active,# "active" if CM includes "1"; "inactive" otherwise
active,# "active" if CM includes "2"; "inactive" otherwise
inactive, # "active" if CM includes "3"; "inactive" otherwisenull,orientation constraint,
inactive, # "active" if CM includes "4"; "inactive" otherwise
inactive, # "active" if CM includes "5"; "inactive" otherwise
active,# "active" if CM includes "6"; "inactive" otherwisenull;

8.12.47

Total pin joint

This element allows to arbitrarily constrain specific components of the absolute position and orientationof a node. The value of the constrained components of the absolute position and orientation can be
imposed by means of drives. As such, this element allows to mimic the behavior of most ideal constraints
that ground one node.
<joint_type> ::= total pin joint<joint_arglist> ::=<node_label>[ , position , (Vec3) <relative_offset> ][ , position orientation , (OrientationMatrix) <rel_pos_orientation> ][ , rotation orientation , (OrientationMatrix) <rel_rot_orientation> ][ , position , (Vec3) <absolute position> ][ , position orientation , (OrientationMatrix) <abs_pos_orientation> ][ , rotation orientation , (OrientationMatrix) <abs_rot_orientation> ][ , position constraint ,<position_status> , <position_status> , <position_status> ,(TplDriveCaller<Vec3>) <imposed_absolute_position> ]262

[ , orientation constraint ,<orientation_status> , <orientation_status> , <orientation_status> ,(TplDriveCaller<Vec3>) <imposed_absolute_rotation> ]<position_status> ::={ inactive | active | position | velocity | <status> }<orientation_status> ::={ inactive | active | rotation | angular velocity | <status> }The non-holonomic variant is not implemented yet.
OutputThe output occurs in the .jnt file, which contains:• column 1: the label• columns 2–4: the three components of the internal force in the reference frame of the element• columns 5–7: the three components of the internal moment in the reference frame of the element• columns 8–10: the three components of the internal force in the global reference frame• columns 11–13: the three components of the internal moment in the global reference frame• columns 14–16: the three components of the absolute displacement in the reference frame of theelement• columns 17–19: the three components of the absolute rotation vector in the reference frame of theelement• columns 20–22: the three components of the absolute velocity in the reference frame of the element• columns 23–25: the three components of the absolute angular velocity in the reference frame of theelement
Private Data
The following data are available:
1. "px" absolute position along absolute position orientation axis 1
2. "py" absolute position along absolute position orientation axis 2
3. "pz" absolute position along absolute position orientation axis 3
4. "rx" absolute orientation about absolute rotation orientation axis 1
5. "ry" absolute orientation about absolute rotation orientation axis 2
6. "rz" absolute orientation about absolute rotation orientation axis 3
7. "Fx" reaction force about absolute position orientation axis 1
8. "Fy" reaction force about absolute position orientation axis 2263

9. "Fz" reaction force about absolute position orientation axis 3
10. "Mx" reaction moment about absolute rotation orientation axis 1
11. "My" reaction moment about absolute rotation orientation axis 2
12. "Mz" reaction moment about absolute rotation orientation axis 3
13. "dx" imposed absolute position along absolute position orientation axis 1
14. "dy" imposed absolute position along absolute position orientation axis 2
15. "dz" imposed absolute position along absolute position orientation axis 3
16. "tx" imposed absolute orientation about absolute rotation orientation axis 1
17. "ty" imposed absolute orientation about absolute rotation orientation axis 2
18. "tz" imposed absolute orientation about absolute rotation orientation axis 3
19. "vx" absolute velocity along absolute position orientation axis 1
20. "vy" absolute velocity along absolute position orientation axis 2
21. "vz" absolute velocity along absolute position orientation axis 3
22. "wx" absolute angular velocity about absolute rotation orientation axis 1
23. "wy" absolute angular velocity about absolute rotation orientation axis 2
24. "wz" absolute angular velocity about absolute rotation orientation axis 3
Hints
When wrapped by a driven element, the following hints are honored:• offset{1} the offset of the joint with respect to the node is reset;• offset{0} the absolute position of the joint is reset;• position-hinge{1} the relative orientation of the absolute position constraint with respect to thenode is reset;• position-hinge{0} the absolute orientation of the absolute position constraint is reset;• orientation-hinge{1} the relative orientation of the absolute orientation constraint with respect
to the node is reset;• orientation-hinge{0} the absolute orientation of the absolute orientation constraint is reset;• position-drive3 resets the absolute position drive; the hint is passed to the Vec3 drive hint parser.
• orientation-drive3 resets the absolute orientation drive; the hint is passed to the Vec3 drive hintparser.

8.12.48

Total reaction

Original implementation: Alessandro Fumagalli, Marco Morandini.
See also total equation (see Section 8.12.45). TODO
264

8.12.49

Universal hinge

Deprecated in favour of the cardano hinge (see Section 8.12.6).

8.12.50

Universal pin

Deprecated in favour of the cardano pin (see Section 8.12.7).

8.12.51

Universal rotation

Deprecated in favour of the cardano rotation (see Section 8.12.8).

8.12.52

Viscous body<joint_type> ::= viscous body<joint_arglist> ::=<node_label> ,[ position , (Vec3) <relative_offset> , ][ orientation , (OrientationMatrix) <relative_orientation> , ](ConstitutiveLaw<6D>) <const_law>
This element defines a force and a moment that depend on the absolute linear and angular velocity ofa body, projected in the reference frame of the node itself. The force and moment are defined as a 6D
viscous constitutive law.

8.12.53

Lower Pairs

Revolute
Use a revolute hinge, or a total joint.
Prismatic
Use a prismatic and an inline, or a total joint.
Screw
Not supported yet.
Cylindrical
Use a revolute rotation and an inline, or a total joint.
Spherical
Use a spherical hinge, or a total joint.
PlanarUse a revolute rotation and an in plane, or a total joint.

265

8.13

Joint Regularization

The joint regularization element is used to modify algebraic constraint equations in order to improveill-conditioned problems.
<elem_type> ::= joint regularization<normal_arglist> ::= <type> [ , <data> ]<type> ::= tikhonov<data> ::= { <coef> | list , <coef_1> [ , ... ] }An element is instantiated, which requires an underlying algebraic constraint (a joint element that
instantiates algebraic equations) with the same label to exist. In that case, the algebraic constraint
equations are modified to regularize the problem. The joint that is regularized must exist, and it
must write constraint equations. If the keyword list is used, the coefficients for each internal state are
expected; the number of coefficients is determined by the joint.

8.13.1

Tikhonov

The tikhonov joint regularization type consists in modifying a constraint, expressed by an algebraic
equation Φ (x, t) and the corresponding Lagrangian multipliers λ, namely
(8.74)
ΦT/x λ∆x + ΦT/x ∆λ = F − ΦT/x λ/x

Φ/x ∆x = −Φ (x, t)(8.75)

by adding the multipliers to the constraint equation, weighed by the coefficient coef (or by the list ofcoefficients coef_<i>, in case different coefficients are given):ΦT/x λ∆x + ΦT/x ∆λ = F − ΦT/x λ(8.76)/xΦ/x ∆x − coef · ∆λ = −Φ (x, t) + coef · λ(8.77)The Tikhonov regularization allows the constraint to be violated by an amount that depends on themultipliers. In this sense, the coefficient coef should be considered sort of a compliance: the larger thecoefficient, the larger the constraint violation for a given value of the reaction λ.

8.14

Plate Elements

8.14.1

Shell4

Authors: Marco Morandini and Riccardo Vescovini
The shell4 elements model a four-node shell. The syntax is<elem_type> ::= { shell4eas | shell4easans }<normal_arglist> ::=<node_1_label> , <node_2_label> , <node_3_label> , <node_4_label> ,<shell_constitutive_law_data>

266

Figure 8.13: Shell: definitions<shell_constitutive_law_data> ::={ [ matr , ] <12x12_matrix>| sym , <upper_triangular_12x12_matrix>| diag , <diagonal_12x12_matrix>| isotropic , <isotropic_data> }[ , prestress , (Vec12) <prestress> ]<isotropic_data> ::={ { E | Young modulus } , <E>| { nu | Poisson modulus } , <nu>
| { G | shear modulus } , <G>| as , <as>
# TODO: clarify| at , <at>
# TODO: clarify| thickness , <thickness> }[ , ... ]The names shell4eas and shell4easans respectively stand for “Enhanced Assumed Strain” (EAS) and“Enhanced Assumed Strain-Assumed Natural Strain” (EAS-ANS).
Nodes are numbered according to Figure 8.13.
Only linear elastic constitutive properties can be currently modeled. They consist in a 12 × 12 matrix
that expresses the force and moment fluxes as functions of linear and angular strains according to






 n11  ε11 







n12 
ε12 
















n
ε




13
13












n
ε




21
21












n
ε




22
22








n23
ε23
(8.78)= [D]+ prestress m11 
 κ11 











 m12 
 κ12 











 m13 
 κ13 








m21 
κ21 















m
κ




22
22








m23
κ23
The prestress is a force and moment per unit span contribution to the force and moment fluxes.
267

Typically, only a membrane prestress makes sense, namely<prestress> ::= <T11> , <T12> , 0. , # force/span on face with normal 1<T21> , <T22> , 0. , # force/span on face with normal 20.
, 0.
, 0. , # moment/span on face with normal 1
0.
, 0.
, 0.
# moment/span on face with normal 2
with T21 ≡ T12.
When the isotropic keyword is used, only two of the optional sub-keywords E, nu and G are required,as the remaining parameter can be computed from the other two according to the relationshipG=E.
2 (1 + nu)(8.79)

If all are provided, they must be consistent. The optional parameters as and at are not documented
yet; the default should be used.
When the (optional) matr (or sym) form is used, the required data for an orthotropic plate, fromClassical Laminate Theory (CLT), with the principal axes of orthotropy parallel to the edges of thestructure and laminate, and with a symmetrical arrangement of the layers, are

 


Nx 
CEx
Cνxy Ey
0
0
0
0
εx 










 Cνxy Ey
 εy 

Ny 
CEy
0
0
0
0 









 




0
0
2G
h
0
0
0
Nxy
ε
xy
xy

=
(8.80)

Mx 
0
0
0
DEx
Dνxy Ey 0 
κx 












 

0
0
0
Dνxy Ey
DEy
0 


 My  κy 





Mxy
0
0
0
0
0
2F
κxy

with

C=
D=
F =

h
1 − νxy νyx(8.81a)h3
12(1 − νxy νyx )(8.81b)

Gxy h312(8.81c)The data actually required by MBDyn are






































N11
N12
N13
N21
N22
N23
M11
M12
M13
M21
M22
M23

CEx
0


0


0


 Cνxy Ey

0

= 

0






0







0






0





0

0






















0
2Gxy h
0
0
0
0
0
0
0
0
0
0

0
0
αs Gxy h
0
0
0
0
0
0
0
0
0

0
0
0
2Gxy h
0
0
0
0
0
0
0
0

Cνxy Ey
0
0
0
CEy
0
0
0
0
0
0
0

0
0
0
0
0
αs Gxy h
0
0
0
0
0
0

0
0
0
0
0
0
2F
0
0
−Dνxy Ey
0
0

0
0
0
0
0
0
0
DEx
0
0
0
0

0
0
0
0
0
0
0
0
2F αt
0
0
0

0
0
0
0
0
0
0
−Dνxy Ey
0
DEy
0
0

0
0
0
0
0
0
0
0
0
0
2F
0

0
0
0
0
0
0
0
0
0
0
0
2F αt

ε11
ε12
ε13
ε21
ε22
ε23
κ11
κ12
κ13
κ21
κ22
κ23
(8.82)








































where αs is the shear factor, and the torsional factor αt is the material coefficient typical for a 6-fieldshell theory, which does not appear in conventional shell theories. It should be viewed as an analogue ofthe shear factor. Values of αt from 0 to 1 have negligible influence on displacements and on the internalenergy of the system. See [22] for details.

268







































8.14.2

Membrane4

Authors: Marco Morandini and Tommaso Solcia
The membrane4 element models a four-node membrane. The syntax is<elem_type> ::= membrane4eas<normal_arglist> ::=<node_1_label> , <node_2_label> , <node_3_label> , <node_4_label> ,<membrane_constitutive_law_data><membrane_constitutive_law_data> ::={ [ matr , ] <3x3_matrix>| sym , <upper_triangular_3x3_matrix>| diag , <diagonal_3x3_matrix>| isotropic , <isotropic_data> }[ , prestress , (Vec3) <prestress> ]<isotropic_data> ::={ { E | Young modulus } , <E>| { nu | Poisson modulus } , <nu>
| { G | shear modulus } , <G>| thickness , <thickness> }[ , ... ]The name membrane4eas stands for “Enhanced Assumed Strain” (EAS). Nodes are numbered according
to Figure 8.13. Only linear elastic constitutive properties can be currently modeled. They consist in a
3 × 3 matrix that expresses the force fluxes as functions of linear strains according to n11  ε11 n22
ε22
(8.83)= [D]+ prestress




n12
ε12

The prestress is a force per unit span contribution to the force fluxes,<prestress> ::= <T11> , <T22> , <T12>

When the isotropic keyword is used, only two of the optional sub-keywords E, nu and G are required,as the remaining parameter can be computed from the other two according to the relationshipG=E.
2 (1 + nu)(8.84)

If all are provided, they must be consistent.
When the (optional) matr (or sym) form is used, the required data for an orthotropic membrane are

with


 
CE1
 N11 N22
=  Cν12 E2


N12
0

Cν21 E1
CE2
0



0
 ε11 

0
ε22


ε12
2G12 hh
1 − ν12 ν21
ν12 E2 = ν21 E1C=

269(8.85)(8.86a)(8.86b)

Example:membrane4eas: 100, 1, 2, 3, 4,
matr, E1*H/(1-NU12*NU21),
E1*H*NU21/(1-NU12*NU21), 0,E2*NU12*H/(1-NU12*NU21), E2*H/(1-NU12*NU21),0,0,0,
2*G12*H,prestress, PS, PS, 0.;

8.15

User-Defined Elements

8.15.1

Loadable Element

Note: the loadable element is deprecated in favor of the user defined element.
The loadable element is a wrapper for a user-defined element that is compiled in a separated moduleand linked run-time. The module should provide a comprehensive set of functions according to a specified
API; default functions are available if no special features are required. Implementation of modules canbe very easy, but a deep knowledge of the internals of the code is required when special tasks need to be
performed. There are virtually no limits on what a loadable element can do.
The syntax is simply:<elem_type> ::= loadable<normal_arglist> ::= " <module_name> "[ , name , " <calls> " ][ , <module_data> ]where module_name is the name of the module file; as soon as the file is checked and the binding of
the structure with function bindings succeeded, a function called read() is invoked, passing it the input
stream. This function is in charge of reading module_data following the general syntax of the input file.
An alternative form is<normal_arglist> ::= reference , " <name> "[ , <module_data> ]where name is the name by which the loadable element recorded itself when registered via the module
load directive, as described in Section 2.4.6. As a consequence, the following forms are equivalent:# direct runtime loadingloadable: 1, "/some/module.so";# "/some/module.so" registers itself as "some_module"
module load: "/some/module.so";loadable: 2, reference, "some_module";# works also as joint (might obsolete loadable elements)
joint: 3, some_module;
It is advisable that the function read() prints some help message when the first field of module_data is
the keyword help. All the helpers and the high-level structures are available, such as drivers, constitutive
laws, reference frames. Refer to each module for a description (if available) of the features and of the
input/output format. module_name should be a full path to the module function. If the name starts
with a slash “/”, the full path name is used. Otherwise the module is searched in the colon-separated
list of directories contained in the environment variable LD_LIBRARY, then among the libraries listed in/etc/ld.so.cache, and finally in /usr/lib and in /lib (see dlopen(3)). At last, it is searched in the270current directory, and the extension .so is added if missing. The string calls represents the name ofthe structure that contains the bindings to the functions. The default is calls.
Refer to $(BASE)/mbdyn/base/loadable.h for a description of the functions that are allowed. An
example module is given in directory$(BASE)/modules/module-template/which can be used as a starting point to build a custom module. The loadable element interface
allows to link modules in different languages, e.g. C or FORTRAN77; simply use module-template as a
guideline to providing callbacks to the loadable element interface and to collect required info from themain program (e.g. node positions, equation indices and everything else that is required for appropriate
connection), then call the functions that actually do the work in other languages from inside the callbacks.

8.15.2User-Defined Element

The user defined element is a much more streamlined form of custom element definition than theloadable element. From the point of view of the syntax the differences are minimal; however, from animplementation point of view, the user defined element is preferable.
The definition of a user defined element requires two steps. In the first step, a run-time loadable
module is loaded using the module load directive (see Section 2.4.6). This registers a handler to theuser defined element type along with a name used to reference it. In the second step, an instance ofthat user defined element type is created, referencing it by name.
The syntax of the user defined element is<elem_type> ::= user defined<normal_arglist> ::= <name> [ , <module_data> ]As for the loadable element, it is recommended that some useful output is given if the first module_data
is the keyword help.
An example module is given in directory$(BASE)/modules/module-template2/
which can be used as a starting point to build a custom module.
Example.
module load: "libmodule-template2"
user defined: 1000, template2, help;

8.15.3General Discussion on Run-Time Loadable Modules

In general, to call external functions from C++ one needs to declare them as#include <sys/types.h>extern "C" {int a_C_function(int arg, double darg);
int a_F77_subroutine(int32_t *iarg, double *darg);}

271

The same applies to FORTRAN 77 functions; only, the naming convention usually is compiler dependent;
some compilers turn all the names to uppercase or lowercase (remember that FORTRAN 77 is caseinsensitive); other compilers add underscores at the beginning or at the end of the names. Check what isthe behavior of your compiler, by compiling a simple program with your favorite FORTRAN 77 compiler,then looking at it with the utility nm(1), which will show how the symbols are represented internally.
For instance, the code
C This is a compiler test
SUBROUTINE F77SUB(I, D)
INTEGER*4 I
REAL*8 D(*)
D(I) = 0.0
END
when compiled with g77(1) on a GNU/Linux system, yields:[masarati@mbdyn manual]$ g77 -c f77sub.f[masarati@mbdyn manual]$ nm f77sub.o00000000 T f77sub_That is, g77(1) lowercases all symbols, and adds a trailing underscore. Macros to automatically detectand take care of this behavior are planned.
To compile loadable modules, one needs to configure the package as follows:./configure --with-module=<module_name>where module_name is the name of the directory the module is placed in with the module- part stripped;
e.g. to compile the tire module that resides in $(BASE)/modules/module-wheel2 one must type./configure --with-module=wheel2
Multiple modules can be compiled by typing the list of the names separated by blanks.
The modules need to resolve some of the symbols that are in the main executable; until a full working
libtool support is implemented, this must be done by hand. The g++(1) compiler requires the switch‘-rdynamic’ to be added to the loader’s flags.
For example,./configure --with-module=<module_name> LDFLAGS="-rdynamic"

8.16

Output Elements

Output elements take care of inter-process communication. These elements can use specific communication means, depending on the type of simulation they are used for, and can communicate specific typesof data.

272

8.16.1

Stream output

This is a special element which takes care of sending output to external processes by means of either
local or inet sockets during batch or real-time simulations. This topic is under development, so expect
frequent changes, and please do not count too much on backward compatibility.
The syntax is:<elem_type> ::= stream output<arglist> ::=stream name , " <stream_name> " ,create , { yes | no } ,[ { local , " <socket_name> " , |[ port , <port_number> , ][ host , " <host_name> " , ] } ][ socket type , { tcp | udp } , ][ { [ no ] signal| [ non ] blocking| [ no ] send first| [ do not ] abort if broken } [ , ... ] , ][ output every , <steps> , ][ echo , <file_name>[ , precision , <precision> ][ , shift , <shift> ] , ]<content>
The stream output allows MBDyn to send streamed outputs to remote processes during both batch andreal-time simulations, using sockets either in the local or in the inet namespace. If the simulation is
run in real-time using RTAI, RTAI mailboxes are used instead.
• stream_name is the name of the RTAI mailbox where the output is written (a unique string no
more than six characters long); it is basically ignored by the stream output element except whenusing RTAI;• the create keyword determines whether the socket must be created or looked-up as already existingon the system; if create is set to no, MBDyn will retry for 60 seconds and then give up;• socket_name is the path of the local socket that is used to communicate between processes;• port_number is the port number to be used with a inet socket. The default port number is 9011
(intentionally unassigned by IANA). If no host_name is given, localhost will be used;• host_name is the name or the IP of the remote host where the mailbox resides; note that if thisfield is given, create must be set to no. The simulation will not start until the socket is createdon the remote host;• socket type defaults to tcp;
• the flag no signal requests that no SIGPIPE be raised when sending through a socket when theother end is broken (by default, SIGPIPE is raised);• the flag non blocking requests that operations on the socket do not block (or block, in case ofblocking, the default);273

• the flag no send first requests that no send occurs before the first time step (by default, data
are always sent);• the flag do not abort if broken requests that the simulation continues in case the connection
breaks. No further data send will occur for the duration of the simulation (the default);• the field output every requests output to occur only every steps;• the field echo causes the content that is sent to the peer to be echoed on file file_name; theoptional parameter precision determines the number of digits used in the output; the optionalparameter shift is currently unused;• the field content is detailed in the next section.
This element, when used with the motion content type, obsoletes the stream motion output element(see Section 8.16.3). When the simulation is executed in real-time using RTAI, this element obsoletes
the RTAI output element (see Section 8.16.2).
Streamed output
Different types of data can be sent. The most general form is called values, consisting in an arbitrary setof independent scalar channels. A form specifically intended to communicate the motion of a mechanicalsystem is called motion, consisting in a subset of the kinematics of a set of structural nodes:<content> ::= { <values> | <motion> | <user_defined> }<values> ::= [ values , ]<channel_number> ,<value>[ , ... ][ , modifier , <content_modifier> ]<value> ::={ [ nodedof , ] (NodeDof) <output_dof>| drive , (DriveCaller) <drive_data> }<motion> ::= motion ,[ output flags ,{ position| orientation matrix| orientation matrix transpose| velocity| angular velocity }[ , ... ] , ]{ all | <struct_node_label> [ , ... ] }<user_defined> ::= <user_defined_type> [ , ... ]where• the (optional) keyword values indicates that a set of independent scalar channels is output by theelement;274

• the number of channels channel_number that are written determines how many value entries must
be read. In case of nodedof (the default, deprecated), they must be valid scalar dof entries, which
can be connected in many ways to nodal degrees of freedom; in case of drive, they can be arbitrary
functions, including node or element private data;• the keyword modifier defines how the content of the stream is modified before being sent; see
Section 7.1.5 for details.
• the keyword motion indicates that a subset of the kinematic parameters of a set of structuralnodes is output by the element. As opposed to the values case, which is intended for genericinterprocess communication output, this content type is intended to ease and optimize the outputof the motion of structural nodes, to be used for on-line visualization purposes. By default, only
the position of the selected nodes is sent. This is intended for interoperability with a development
version of EasyAnim which can read the motion info (the so-called “van” file) from a stream. The
optional keyword output flags allows to request the output of specific node kinematics: the node
position, orientation matrix (either row- or column-major), the velocity and the angular velocity.
The default is equivalent to output flags, position.
Non real-time simulation
During non real-time simulations, streams operate in blocking mode. The meaning of the parameters is:• stream_name indicates the name the stream would be known as by RTAI; it must be no more than
6 characters long, and mostly useless;• the instruction create determines whether MBDyn will create the socket, or try to connect to an
existing one;
• the keyword local indicates that a socket in the local namespace will be used; if create is set toyes, the socket is created, otherwise it must exist.
• either of the keywords port or host indicate that a socket in the internet namespace will be used;

if create is set to yes, host_name indicates the host that is allowed to connect to the socket; it
defaults to any host (0.0.0.0); if create is set to no, host_name indicates what host to connect to;
the default is localhost (127.0.0.1); the default port is 9011 (intentionally unassigned by IANA);• the flag no signal is honored;• the flag non blocking is honored;• the flag no send first is honored;• the flag do not abort if broken is honored.
If no socket type is specified, i.e. none of the local, port and host keywords are given, a socket is opened
by default in the internet namespace with the default IP and port; the create keyword is mandatory.
Real-time simulation
During real-time simulations, streams wrap non-blocking RTAI mailboxes. The meaning of the parameters is:• the parameter stream_name indicates the name the stream will be known as in RTAI’s resource
namespace; it must be exactly 6 characters long;275• the instruction create determines whether the mailbox will be created or looked for by MBDyn;• the keyword local is ignored;• the keyword host indicates that a mailbox on a remote host will be used; it is useless when createis set to yes, because RTAI does not provide the possibility to create remote resources; if none isgiven, a local mailbox is assumed;• the keyword port is ignored.
• the flag no signal is ignored;• the flag non blocking is honored; however, blocking mailboxes make little sense, and real-timesynchronization using RTAI should not rely on blocking mailboxes;• the flag no send first is ignored (although it should be honored when the mailbox is blocking);• the flag do not abort if broken is ignored; the program is always terminated if a mailbox is nolonger available.

8.16.2

RTAI output

This element is actually used only when the simulation is scheduled using RTAI; otherwise, the corresponding stream output element is used (see Section 8.16.1). As a consequence, its explicit use is
discouraged and deprecated. The stream output element should be used instead.

8.16.3Stream motion output

This element type is obsoleted by the stream output element with the motion content type (see Section 8.16.3). The syntax is:<elem_type> ::= stream motion output<arglist> ::=stream name , " <stream_name> " ,create , { yes | no } ,[ { local , " <socket_name> " ,| [ port , <port_number> , ] [ host , " <host_name> " , ] } ][ { [ no ] signal| [ non ] blocking| [ no ] send first| [ do not ] abort if broken }[ , ... ] , ]<motion>Its support may be discontinued in the future.

8.17

Miscellaneous

This section lists some extra cards that do not correspond to any specific simulation entity, but rather
alter the behavior of existing entries or cause special operations to be undertaken during model input.

276

8.17.1

Bind

The statement bind does not really define an element. It is rather used to instruct a parameter node
about which parameter of an element it is bound to. The parameter node must exist, and the element
the node is being bound to, of type elem_type and label element_label, must have been already defined.
The complete syntax is:<elem_type> ::= bind<arglist> ::=<element_label> ,<element_type> ,<parameter_node_label> ,<bind_args>
where bind_args depend on the type of parameter node.
Element
When binding an element to an element parameter node, each element makes a number of specificparameters available. A detailed list is given for each element in the private data section. In that case:<bind_args> ::={ [ index , ] <parameter_index>| string , " <parameter_name> " }The value of parameter_index must be legal, i.e. between 1 and the maximum number of parameters made available by the element. The alternative form, using the keyword string followed by theparameter_name, allows more friendly definition of the binding. The name of the parameter depends onthe element whose property is being bound. A complete listing of the parameters that a parameter node
can be bound to can be found in the ‘Private data’ subsection of each element’s specification.
Example.
The parameter node ANGLE is bound to the rotation of a revolute hinge (see Section 8.12.37).
# ... problem block
begin: control data;
structural nodes: 2;
parameter nodes: 1;
forces: 2;# ... other control data
end: control data;
set: integer NODE1 = 1000;
set: integer NODE2 = 2000;
set: integer ANGLE = 5000;
set: integer REVOLUTE = 6000;
begin: nodes;
structural: NODE1, dynamic, null, eye, null, null;
structural: NODE2, dynamic, null, eye, null, null;277

parameter: ANGLE, element;# ... other nodes
end: nodes;
begin: elements;
joint: REVOLUTE, revolute hinge,
NODE1,
position, reference, node, null,orientation, reference, node, eye,NODE2,
position, reference, node, null,orientation, reference, node, eye;bind: REVOLUTE, joint, ANGLE, string, "rx";couple: 1, NODE1, 0.,0.,1.,
dof, ANGLE, parameter, 1, linear, 0.,1.;
couple: 2, NODE2, 0.,0.,1.,
element, REVOLUTE, joint, string, "rx", linear, 0.,1.;# ... other elements
end: elements;
Note that the same element data, i.e. the revolute hinge relative rotation angle, is used to drive a couple
in two different ways; the latter, by means of the element drive (see Section 2.6.11) is more direct, but
the former, by means of the dof drive (see Section 2.6.7) through the bind mechanism has the additional
effect of updating the parameter node, which can be used to connect genel elements for special purposes.
Beam strain gage
When binding an element to a beam strain gage parameter node, the element_type field must be
beam. In that case:<bind_args> ::= <beam_evaluation_point>where beam_evaluation_point is the evaluation point of the beam element where the internal strain
and curvatures must be evaluated. It must be 1 for 2-node beams, while it can be either 1 or 2 for 3-node
beams.
Example.
# ... problem block
begin: control data;
parameter nodes: 1;
beams: 1;# ... other control data
end: control data;
set: integer BEAM = 100;
set: integer STRAIN = 200;

278

begin: nodes;
parameter: STRAIN, beam strain gage, 0.0, 0.1;
# ... other nodes
end: nodes;
begin: elements;
beam3: BEAM, ...; # beam databind: BEAM, beam, STRAIN, 1;# ... other elements
end: elements;

8.17.2

Driven Element

The driven type is not an element by itself. It is a wrapper that masks another element and switches it on
and off depending on the (boolean) value of a drive. It can be used to emulate a variable topology model,
where some elements simply don’t contribute to the residual or to the Jacobian matrices when their drive
has a certain value. Since the drivers can be arbitrary functions of the time, or other parameters including
the value of any degree of freedom, the driven elements can be “driven” in a very flexible way. Everyelement can be driven, except those that can be instantiated once only. The syntax for a driven elementis:<elem_type> ::= driven<normal_arglist> ::= (DriveCaller) <element_driver> ,[ hint , " <hint> " [ , ... ] ] ,<driven_element><driven_element> ::={ existing : <driven_elem_type> , <driven_elem_label>| <element_card> }When the keyword existing is used, an existing element of type driven_elem_type and label driven_elem_label
is looked for, and it is wrapped by the driven element. In this case, no new element is instantiated. The
label of the element must match that of the driving element given at the beginning. For consistency withthe syntax, and for more flexibility, even when wrapping an existing element the output flags can be set
at the end of the card. This flag overrides the one set when the driven element was instantiated.
Otherwise, a regular element is read after the driving element’s declaration; it is then instantiatedand wrapped by the driven element wrapper. Note that after the keyword existing or after the driven
element type, a colon is used as a separator. This is probably the only exception to the rule that thecolon can only follow a description at the beginning of a card. The label driven_elem_label of thedriven element must match that of the driving element used at the beginning of the driven card.
Example.

A pin constraint between two rigid bodies is released:

set: integer BODY_1 = 1;
set: integer BODY_2 = 2;
# ...
structural: BODY_1, dynamic,
null, eye, null, null;
structural: BODY_2, dynamic,
null, eye, null, null;279

# ....
body: BODY_1, BODY_1,
1000., null, diag, 100.,100.,1.;
body: BODY_2, BODY_2,
10., null, diag, 1.e-1,1.e-1,1.e-3;# ...
# this constraint will be released when Time = 10 s
driven: 1, string, "Time < 10.",
joint: 1, spherical hinge,
BODY_1,position, null,
BODY_2,
position, null;
Example. an axial rotation (see Section 8.12.3) joint is replaced by a revolute hinge (see Section 8.12.37) when the desired spin velocity, measured as the angular velocity of the second node (assuming, for instance, that the first one is fixed), is reached. The value of an abstract node is used to
input the angular velocity to the axial rotation joint.
set: integer BODY_1 = 1;
set: integer BODY_2 = 2;
set: integer CONTROL_OUTPUT = 3;
# ...
structural: BODY_1, static,null, eye, null, null;
structural: BODY_2, dynamic,
null, eye, null, null;
abstract: CONTROL_OUTPUT;# ....
driven: 1, node, BODY_2, structural, string, "Omega[3]",string, "Var < 100.",
joint: 1, axial rotation,
BODY_1,position, null,orientation, 1, 1.,0.,0., 3, 0.,0.,1.,
BODY_2,
position, null,orientation, 1, 1.,0.,0., 3, 0.,0.,1.,
node, CONTROL_OUTPUT, abstract, string, "x",linear, 0.,1.;
driven: 2, node, BODY_2, structural, string, "Omega[3]",string, "Var >= 100.",
joint: 2, revolute hinge,
BODY_1,position, null,orientation, 1, 1.,0.,0., 3, 0.,0.,1.,
BODY_2,
position, null,orientation, 1, 1.,0.,0., 3, 0.,0.,1.;

280

Hint
The hint feature consists in allowing the setup of elements to be computed when they are activatedrather than at startup. For example, a joint that is activated after some simulation time may need tocompute its relative position and orientation from the parameters of the simulation; a drive that controls
the evolution of the relative configuration of a joint may need to infer its parameters from the current
configuration of the overall system; and so on.
Currently, only few elements, significantly joints, support and honor hints. The typical syntax isgiven by a keyword followed by some optional parameters within curly brackets. For instance, the hintthat instructs a joint to compute the offset with respect to the second node when it is activated isdriven: 10, string, "Time > 1.", hint, "offset{2}",joint: 10, ...
A similar form is used to instruct a joint to compute the relative orientation with respect to node 1:
driven: 20, string, "Time > 1.", hint, "hinge{1}",joint: 20, ...
A distance joint may be fed a new drive by using:set: const real T0 = 1.;
driven: 30, string, "Time > T0",
hint, "drive{cosine, T0, pi/.1, -.9/2., half, model::distance(1,2)}",
joint: 30, distance, ...
A drive hinge joint may be fed a new drive by using:set: const real T0 = 1.;
driven: 40, string, "Time > T0",
# note: the lines wrap for typographical reasons# in the actual file, the string has to be a single line
hint, "drive3{model::xdistance(1,2), \model::ydistance(1,2), model::zdistance(1,2), \cosine, T0, pi/.1, -.9/2., half, model::distance(1,2)}",
joint: 30, drive hinge, ...
This feature will likely be extended to other elements and generalized as much as possible.

8.17.3

InertiaThis card causes the equivalent inertia properties of a subset of elements to be computed.
<card> ::= inertia : <label>[ , name , " <inertia_name> " ][ , position , (Vec3) <reference_position> ][ , orientation , (Mat3x3) <reference_orientation> ], <type_subset> [ , ... ][ , output , { no | yes | log | both | always } [ , ... ] ] ;<type_subset> ::= <type> , { all | <label> [ , ... ] }<type> ::= { body | joint | loadable }281

where type currently can be body, joint and loadable, although more elements associated to inertia
might participate in the future. All elements whose labels are listed must exist, and duplicates aredetected and considered errors. The keyword all causes all the elements of type type to be included in
the list.
The only effect of the inertia statement is to log each inertia entry in the .log file in a self explanatory form, referred both to the global reference frame and to a reference frame originating fromreference_position and oriented as reference_orientation. The optional parameter output may
be used to alter the default behavior:• no disables the output, making the inertia statement essentially ineffective;• yes enables output to standard output;• log enables output to the .log file (the default);• both enables output to both standard output and .log file.
• always causes inertia properties to be re-computed at each time step. To this end, an inertia card
must appear in the control data block, declaring how many corresponding inertia elements willbe created. The number of inertia elements declared in the control data section must match thenumber of inertia cards in the elements block whose output is set to always.

8.17.4

OutputThis card does not instantiate any element; it rather enables output of selected elements, and it isanalogous to that of the nodes (see Section 6.6.1):<card> ::= output : <elem_type> , <elem_list> ;<elem_list> ::={ <elem_label> [ , ... ]| range , <elem_start_label> , <elem_end_label> }elem_type is a valid element type that can be read as card name in the elements block. In case the
keyword range is used, all existing elements comprised between elem_start_label and elem_end_label
are set; missing ones are silently ignored.

282

Appendix A

Modal Element Data
A.1

FEM File Format

This section describes the format of the FEM input to the modal joint of MBDyn (Section 8.12.31).
These data can be obtained, for example:• from Code Aster (http://www.code-aster.org/), as discussed in Section A.2;
• from NASTRAN (http://www.mscsoftware.com/) output, using the femgen utility, as detailedin Appendix A.3 (in short, it processes binary output from NASTRAN, as defined by means ofappropriate ALTER files provided with MBDyn sources, into a file that is suitable for direct input
in MBDyn);• by manually crafting the output of your favorite FEM analysis: since it is essentially a plain ASCII
file, it can be generated in a straightforward manner from analogous results obtained with almost
any FEM software, from experiments or manually generated from analytical or numerical modelsof any kind.
The format is:<comments>** RECORD GROUP 1,<any comment to EOL; "HEADER"><comment><REV> <NNODES> <NNORMAL> <NATTACHED> <NCONSTRAINT> <NREJECTED><comments; NMODES = NNORMAL + NATTACHED + NCONSTRAINT - NREJECTED>** RECORD GROUP 2,<any comment to EOL; "FINITE ELEMENT NODE LIST"><FEMLABEL> [...NNODES]<comments; FEM label list: NNODES integers>** RECORD GROUP 3,<any comment to EOL; "INITIAL MODAL DISPLACEMENTS"><MODEDISP> [...NMODES]<comments; initial mode displacements: NMODES reals>** RECORD GROUP 4,<any comment to EOL; "INITIAL MODAL VELOCITIES"><MODEVEL> [...NMODES]<comments; initial mode velocities: NMODES reals>** RECORD GROUP 5,<any comment to EOL; "NODAL X COORDINATES"><FEM_X> [...NNODES]<comments; FEM node X coordinates>** RECORD GROUP 6,<any comment to EOL; "NODAL Y COORDINATES"><FEM_Y> [...NNODES]<comments; FEM node Y coordinates>283

** RECORD GROUP 7,<any comment to EOL; "NODAL Z COORDINATES"><FEM_Z> [...NNODES]<comments; FEM node Z coordinates>** RECORD GROUP 8,<any comment to EOL; "NON-ORTHOGONALIZED MODE SHAPES"><comment; NORMAL MODE SHAPE # 1>
<FEM1_X> <FEM1_Y> <FEM1_Z> <FEM1_RX> <FEM1_RY> <FEM1_RZ>[...NNODES]<comment; NORMAL MODE SHAPE # 2>
<FEM2_X> <FEM2_Y> <FEM2_Z> <FEM2_RX> <FEM2_RY> <FEM2_RZ>[...NNODES][...NMODES]<comments; for each MODE, for each NODE: modal displacements/rotations>** RECORD GROUP 9,<any comment to EOL; "MODAL MASS MATRIX. COLUMN-MAJOR FORM"><M_1_1>[...] <M_1_NMODES>[...]<M_NMODES_1> [...] <M_NMODES_NMODES><comments; the modal mass matrix in column-major (symmetric?)>** RECORD GROUP 10,<any comment to EOL; "MODAL STIFFNESS MATRIX. COLUMN-MAJOR FORM"><K_1_1>[...] <K_1_NMODES>[...]<K_NMODES_1> [...] <K_NMODES_NMODES><comments; the modal stiffness matrix in column-major (symmetric?)>** RECORD GROUP 11,<any comment to EOL; "DIAGONAL OF LUMPED MASS MATRIX"><M_1_X> <M_1_Y> <M_1_Z> <M_1_RX> <M_1_RY> <M_1_RZ>[...]<M_NNODES_X> [...] <M_NNODES_RZ><comments; the lumped diagonal mass matrix of the FEM model>** RECORD GROUP 12,<any comment to EOL; "GLOBAL INERTIA PROPERTIES"><MASS><X_CG> <Y_CG> <Z_CG><J_XX> <J_XY> <J_XZ><J_YX> <J_YY> <J_YZ><J_ZX> <J_ZY> <J_ZZ><comments; the global inertia properties of the modal element>** RECORD GROUP 13,<any comment to EOL; "MODAL DAMPING MATRIX. COLUMN-MAJOR FORM">[...] <C_1_NMODES><C_1_1>[...]<C_NMODES_1> [...] <C_NMODES_NMODES><comments; the modal damping matrix in column-major (symmetric?)>** END OF FILE

An arbitrary number of comment lines may appear where <comments[...]> is used; only one comment line must appear where where <comment[...]> is used.
The beginning of a record is marked** RECORD GROUP <RID>
where the number RID indicates what record is being read. The size of each record, i.e. the number ofvalues that are expected, is defined based on the header record, so MBDyn should be able to detect
incomplete or mis-formatted files.
The records contain:• RECORD GROUP 1, a.k.a. the “header”, contains a summary of the contents of the file:– REV is a string that indicates the revision number; it is currently ignored;284

– NNODES is the number of (exposed) FEM nodes in the FEM model;– NNORMAL is the number of normal modes;– NATTACHED is the number of “attached”, i.e. static, modes;– NCONSTRAINT is the number of constraint modes;– NREJECTED is the number of rejected modes.
Currently, the number of available modes is computed as
NMODES = NNORMAL + NATTACHED + NCONSTRAINT − NREJECTED
because modes are treated in a generalized manner, so there is no need to consider the different typesof shapes in a specific manner. Typically, one should set all numbers to 0, except for NNORMAL whichshould be set to the number of modes actually present in the data set. Remember that MBDyn
can still select a subset of the available modes to be used in the analysis, so that there is no needto further edit this file.
• RECORD GROUP 2 contains a listing of the NNODES labels of the (exposed) FEM nodes. The labels
can be any string of text, and are separated by blanks (as intended by the isspace(3) C standard
library function). A label cannot thus contain any amount of whitespace.
• RECORD GROUP 3 contains the initial values of the NMODES modal unknowns (optional; set to zero
if omitted);• RECORD GROUP 4 contains the initial values of the NMODES modal unknowns derivatives (optional;
set to zero if omitted);• RECORD GROUP 5 contains the X component of the position of the NNODES FEM nodes in thereference frame attached to the modal node (or to the origin node, if given).
• RECORD GROUP 6 contains the Y component of the data above;• RECORD GROUP 7 contains the Z component of the data above;• RECORD GROUP 8 contains the non-orthogonalized components of the NMODES modes; for each mode,
the three components X, Y , Z of the modal displacement, and the three components RX, RY ,RZ of the linearized modal rotations are listed; each mode shape is separated by a comment line,
which typically is**

NORMAL MODE SHAPE #<N>

for readability;• RECORD GROUP 9 contains the modal mass matrix, i.e. a square, NMODES × NMODES matrix that
contains the reduced mass [m] resulting from the multiplication
T[m] = {X} [M ] {X}(A.1)

When only normal modes are used, it is diagonal. It can be semi-definite positive, or even zero, if
a partially or entirely static model is considered.

285

• RECORD GROUP 10 contains the modal stiffness matrix, i.e. a square, NMODES × NMODES matrix that
contains the reduced stiffness [k] resulting from the multiplication
T[k] = {X} [K] {X}(A.2)

When only normal modes are used, it is diagonal; in that case, the diagonal contains the modal
mass times the square of the eigenvalues, i.e. kii = ωi2 mii . It should be definite positive; in fact,
rigid degrees of freedom that would make it semi-definite should rather be modeled by combining
separate modal submodels by way of multibody connections, so that the multibody capability tohandle finite relative displacements and rotations is exploited. Note however that the positivedefiniteness of the generalized stiffness matrix is not a requirement.
• RECORD GROUP 11 contains the lumped inertia matrix associated to the NNODES (exposed) FEM
nodes; for each node, the X, Y , Z, RX, RY and RY inertia coefficients are listed (they can bezero). The nodal mass coefficients Y and Z should be equal to coefficient X. The resulting diagonal
matrix should satisfy the constraint illustrated in Equation A.1.
• RECORD GROUP 12 contains the global inertia properties of the modal element: the total mass, thethree components of the position of the center of mass in the local frame of the FEM model, andthe 3 × 3 inertia matrix with respect to the center of mass, which is supposed to be symmetric andpositive definite (or semi-definite, if the model is static).
• RECORD GROUP 13 contains the modal damping matrix, i.e. a square, NMODES × NMODES matrix that
contains the reduced damping [c] resulting from the multiplicationT[c] = {X} [C] {X}(A.3)

It can be semi-definite positive, or even zero, if no damping is considered. This record is optional.
If given, it is used in the analysis unless overridden by any damping specification indicated in themodal joint element definition. The generalized damping matrix appeared in MBDyn 1.5.3.
Note that RECORD GROUP 11 and RECORD GROUP 12 used to be mutually exclusive in earlier versions.
The reason for accepting RECORD GROUP 12 format, regardless of RECORD GROUP 11 presence, is related
to the fact that in many applications the FEM nodal inertia may not be available and, at the sametime, a zero-order approximation of the inertia is acceptable. The reason for allowing both is that when
RECORD GROUP 11 is present, its data were originally used to compute all inertia invariants, including
the rigid-body ones that can be provided by RECORD GROUP 12. This in some cases may represent anunacceptable approximation; RECORD GROUP 12 data can be used to replace those invariants by a better
estimate, when available.
Both RECORD GROUP 11 and RECORD GROUP 12 may be absent. This case only makes sense when azero-order approximation of the inertia is acceptable and the rigid-body motion of the modal element is
not allowed, i.e. the element is clamped to the ground (see the keyword clamped in Section 8.12.31 fordetails).
Although the format loosely requires that no more than 6 numerical values appear on a single line,
MBDyn is very forgiving about this and can parse the input regardless of the formatting within eachrecord. However this liberality may lead to inconsistent or unexpected parsing behavior, so use at own
risk.

A.1.1

Usage

The modal joint element is intended to model generically flexible elements whose flexibility is modeled
in terms of linear superposition of deformable shapes expressed in a floating frame of reference (FFR).
286

The reference (rigid-body) motion is handled by a special multibody node, the modal node. In
practice, this node “carries around” the (local) reference frame in which the finite element model (FEM)
is defined. When the modal joint is to be directly connected to the ground, the modal node can beomitted using the clamped keyword instead of the node’s label.
Interaction of the modal joint with the multibody environment should occur through the use ofinterface nodes. Interface nodes are regular structural nodes that are clamped to their corresponding
FEM nodes; static nodes are recommended, to save 6 equations, unless one intends to explicitly connect
additional inertia to them.
(Note: in case the FEM mode shapes are defined as so-called attached modes, i.e. in case the FEmodel was clamped at the origin of its reference frame, the modal node can be directly interfaced to themultibody environment as a regular interface node; otherwise the user needs to understand that suchnode is interfacing the origin of the FEM reference frame.)
For example, if you want to permit arbitrary relative rotation between two independent instancesof the modal joint element, which are connected by a revolute hinge joint, you should define thetwo instances of the modal element each with its own modal node, and each with an interface node at
the respective locations of the hinge. At this point, the interface nodes can be connected by a regularrevolute hinge joint element.

A.1.2

Example: Dynamic ModelAs an example, a very simple, hand-made FEM model file is presented below. It models a FEM model
made of three aligned nodes, where inertia is evenly distributed. Note that each line is prefixed with a
two-digit line number that is not part of the input file. Also, for readability, all comments are prefixedby “**”, in analogy with the mandatory “** RECORD GROUP” lines, although not strictly required by theformat of the file.
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

** MBDyn MODAL DATA FILE** NODE SET "ALL"** RECORD GROUP 1, HEADER**REVISION, NODE, NORMAL, ATTACHMENT, CONSTRAINT, REJECTED MODES.
REV0
3
2
0
0
0
**
** RECORD GROUP 2, FINITE ELEMENT NODE LIST
1001 1002 1003**** RECORD GROUP 3, INITIAL MODAL DISPLACEMENTS
0 0**** RECORD GROUP 4, INITIAL MODALVELOCITIES
0 0**** RECORD GROUP 5, NODAL X COORDINATES000**** RECORD GROUP 6, NODAL Y COORDINATES
-2.
0

287

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

2.
**
** RECORD GROUP 7, NODAL Z COORDINATES000**** RECORD GROUP 8, MODE SHAPES**NORMAL MODE SHAPE # 1
0 0 1 0 0 0
0 0 0 0 0 0
0 0 1 0 0 0**
NORMAL MODE SHAPE # 2
1 0 0 0 0 0
0 0 0 0 0 0
1 0 0 0 0 0**** RECORD GROUP 9, MODAL MASS MATRIX
2 0
0 2
**
** RECORD GROUP 10, MODAL STIFFNESS MATRIX
1 0
0 1e2
**
** RECORD GROUP 11, DIAGONAL OF LUMPED MASS MATRIX
1 1 1 1 1 1
1 1 1 1 1 1
1 1 1 1 1 1The corresponding global inertia properties are:
m=3
 
 0 
0
xCM =
 
0


11 0 0J = 0 3 0 
0 0 11

A.1.3

(A.4)
(A.5)

(A.6)

Example: Static ModelAs an example, a very simple, hand-made FEM model file is presented below. It models a FEM model
made of three aligned nodes, where inertia is only associated to the mid-node. As a consequence, thethree mode shapes must be interpreted as static shapes, since the modal mass matrix is null. Note thateach line is prefixed with a two-digit line number that is not part of the input file. Also, for readability,
all comments are prefixed by “**”, in analogy with the mandatory “** RECORD GROUP” lines, although
not strictly required by the format of the file.
01
02
03
04

** MBDyn MODAL DATA FILE** NODE SET "ALL"

288

05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

** RECORD GROUP 1, HEADER**REVISION, NODE, NORMAL, ATTACHMENT, CONSTRAINT, REJECTED MODES.
REV0
3
2
0
0
0
**
** RECORD GROUP 2, FINITE ELEMENT NODE LIST
1001 1002 1003**** RECORD GROUP 3, INITIAL MODAL DISPLACEMENTS
0 0**** RECORD GROUP 4, INITIAL MODALVELOCITIES
0 0**** RECORD GROUP 5, NODAL X COORDINATES000**** RECORD GROUP 6, NODAL Y COORDINATES
-2.
0
2.
**
** RECORD GROUP 7, NODAL Z COORDINATES000**** RECORD GROUP 8, MODE SHAPES**NORMAL MODE SHAPE # 1
0 0 1 0 0 0
0 0 0 0 0 0
0 0 1 0 0 0**
NORMAL MODE SHAPE # 2
1 0 0 0 0 0
0 0 0 0 0 0
1 0 0 0 0 0**** RECORD GROUP 9, MODAL MASS MATRIX
0 0
0 0
**
** RECORD GROUP 10, MODAL STIFFNESS MATRIX
1 0
0 1e2
**
** RECORD GROUP 12, GLOBAL INERTIA
30 0 0
11 0 00 3 0
0 0 11

289

The same global inertia properties of the model in Section A.1.2 have been used; as a result, thetwo models show the same rigid body dynamics behavior, but the dynamic model also shows deformablebody dynamic behavior, while the static one only behaves statically when straining is involved.

A.2

Code Aster Procedure

The fem_data_file can be generated by Code Aster, using the macro provided in the cms.py file,which is located in directory contrib/CodeAster/cms/ of the distribution, and is installed in directory$PREFIX/share/py/.
Preparing the input for Code Aster essentially requires to prepare the bulk of the mesh either manuallyor using some meshing tools (e.g. gmsh), as illustrated in the related documentation and tutorials, andthen writing a simple script in python (http://www.python.org/) that defines the execution procedure.
To produce the data for MBDyn’s modal element, a specific macro needs to be invoked during theexecution of Aster. The macro instructs Aster about how the solution procedure needs to be tailored to
produce the desired results, and then generates the .fem file with all the requested data.
The steps of the procedure are as follows:
1. prepare a Code Aster input model (the .mail file), containing the nodes, the connections and at
least a few groups of nodes, as indicated in the following;
2. prepare a Code Aster command file (the .comm file), following, for example, one of the given
templates;
3. as soon as the model, the materials, the element properties and any optional boundary constrains
are defined, call the CMS macro with the appropriate parameters. The syntax of the macro is:
CMS(
MAILLAGE = <mesh_concept> ,[ INTERFACE = <interface_node_set_name> , ]EXPOSED = _F( { GROUP_NO = <exposed_node_set_name> | TOUT = ’OUI’ } ),MODELE = <model_concept> ,CARA_ELEM = <element_properties_concept> ,CHAM_MATER = <material_properties_concept> ,[ CHAR_MECA = <boundary_conditions_concept> ,[ OPTIONS = _F([ NMAX_FREQ = <maximum_number_of_frequencies> ]), ]OUT = _F(
TYPE = { ’MBDYN’ } ,[ PRECISION = <number_of_digits> , ][ DIAG_MASS = { ’OUI’ | ’NON’ } , ][ RIGB_MASS = { ’OUI’ | ’NON’ } , ]FICHIER = <output_file_name>));where:• MAILLAGE is the name of a python object returned by LIRE_MAILLAGE;• INTERFACE is a string containing the name of the group of nodes, defined in the mesh file, thatwill be used as interface to add Craig-Bampton shapes to the base (if omitted, only normal
modes are used);290• EXPOSED allows two formats:– GROUP_NO is a string containing the name of the group of nodes, defined in the mesh file,that will be exposed, i.e. that will appear in the .fem file generated by this macro;– TOUT is a string that must be set to ’OUI’, indicating that all nodes will be exposed(technically speaking, all nodes involved in at least one connection);• MODELE is the name of a python object returned by AFFE_MODELE;• CARA_ELEM is the name of a python object returned by AFFE_CARA_ELEM;• CHAM_MATER is the name of a python object returned by AFFE_MATERIAU;• CHAR_MECA is the name of a python object returned by AFFE_CHAR_MECA (optional);• OPTIONS allows a set of generic options to be passed:– NMAX_FREQ is the number of frequencies expected from the eigenanalysis, and thus thenumber of normal modes that will be added to the modal base; the smallest frequencies
are used;• OUT describes the parameters related to the type of output the macro generates; right now,
only output in the format specified in this section is available:– TYPE indicates the type of output the macro is requested to generate; it must be ’MBDYN’;– FICHIER (“file” in French) is the name of the file where the generated data must be
written; it must be a fully qualified path, otherwise it is not clear where the file is actually
generated;– PRECISION contains the number of digits to be used when writing the data (for example,
PRECISION = 8 results in using the format specifier %16.8e);– DIAG_MASS requests the output of the diagonal of the mass matrix (RECORD GROUP 11);
this option really makes sense only if all nodes are output (namely, if the nodes set passed
to EXPOSED consists in all nodes);– DIAG_MASS requests the output of the rigid-body inertia properties (RECORD GROUP 12);the macro returns a python object consisting in the generalized model it used to generate the file,
as returned by MACR_ELEM_DYNA.
4. prepare a .export file, either following the examples or using astk;
5. run Aster.
Annotated examples are provided in directory contrib/CodeAster/cms/.

A.3

NASTRAN Procedure

The fem_data_file can be generated using NASTRAN, by means of the ALTER cards provided indirectory etc/modal.d/ of the distribution.
The steps of the procedure are as follows:
1. prepare a NASTRAN input card deck, made of bulk data, eigenanalysis properties data and/or
static loads (details about this phase are currently missing and will be provided in future releasesof the manual).
2. complete the NASTRAN input file by putting some specific ALTER cards. In detail:291

(a) the file MBDyn_NASTRAN_alter_1.nas contains ALTER definitions for static solutions; appropriate loading subcases for each solution must be provided in the case control and in the bulk
data sections of the input file;
FIXME: I don’t know how to use static shapes only.
(b) the file MBDyn_NASTRAN_alter_2.nas contains ALTER definitions for eigenanalysis solutions;an appropriate eigenanalysis method, with the related data card must be provided in the casecontrol and in the bulk data sections of the input file;
FIXME: I don’t know how to use this together with static shapes; I only get the normal modeshapes, even if the matrices are complete.
(c) the file MBDyn_NASTRAN_alter_3.nas contains ALTER definitions for eigenanalysis solutions;an appropriate eigenanalysis method, with the related data card must be provided in the casecontrol and in the bulk data sections of the input file;
Note: this works; see tests/modal/beam.README.
Exactly one of these files must be included at the very top of the NASTRAN input file; they alreadyinclude the appropriate SOL statement, so the input file must begin with
$ Replace ’#’ below with number that matches your needs
INCLUDE ’MBDyn_NASTRAN_alter_#.nas’
CEND$... any other executive control and bulk data card
The static solution of case (a: SOL 101) and the eigensolution of case (b: SOL 103) need to be
performed in sequence; if only the eigensolution is to be used, the ALTER file of case (c: SOL 103)
must be used. The static solution of case (a) generates a binary file mbdyn.stm; the eigensolutionsof cases (b–c) generate two binary files, mbdyn.mat and mbdyn.tab, which, in case (b), include thestatic solutions as well. The ALTER currently included in the MBDyn distribution work correctly
only with the following PARAM data card:
PARAM,POST,-1
3. Run NASTRAN.
4. Run the tool femgen, which transforms the above binary files into the fem_data_file. The filename is currently requested as terminal input; this is the name of the file that will be used in the
input model for mbdyn. Conventionally, the .fem extension is used.

A.4

Procedures for Other FEA Software

Currently, no (semi-)automatic procedures are available to extract modal element data from other FEA
software. If you need to use any other software, and possibly a free software, you’ll need to design yourown procedure, which may go from a very simple script (shell, awk, python) for handling of textual
output, to a fully featured modeling and translation interface. If you want to share what you developedwith the MBDyn project, feel free to submit code, procedures or just ideas and discuss them on the
mbdyn-users@mbdyn.org mailing list.

292

Appendix B

ModulesB.1

Element Modules

Recall that element modules are invoked as user defined elements, whose syntax is<elem_type> ::= user defined<normal_arglist> ::= <name> [ , <module_data> ]B.1.1

Module-aerodyn

Authors: Fanzhong Meng and Pierangelo Masarati
This module implements NREL’s AeroDyn v 12.58 wind turbine aerodynamic loads.

B.1.2

Module-asynchronous machine

Author: Reinhard ReschThis module implements an asynchronous electric motor.

B.1.3

Module-cyclocopter

Author: Mattia Mattaboni (turned into module by Pierangelo Masarati)This module implements inflow models for cycloidal rotors.
<name> ::= cycloidal no inflow<module_data> ::=<aircraft_node_label> ,[ orientation , (OrientationMatrix) <orientation> , ]<rotor_node_label><name> ::= cycloidal { uniform 1D | uniform 2D | Polimi }<module_data> ::=<aircraft_node_label> ,[ orientation , (OrientationMatrix) <orientation> , ]<rotor_node_label>293(bool) <average> ,<rotor_radius> ,<blade_span>[ , delay , (DriveCaller) <delay> ][ , omegacut , <cut_frequency> ][ , timestep , <time_step> ]The optional orientation is required when axis 3 of the aircraft node is not normal to the rotor
axis, it is defined with respect to the aircraft node; axis 3 of the rotor node must be aligned with therotor axis; the choices of axes 1 and 2 only influence the orientation of the output.
Example 1.
user defined: CURR_DRUM,
cyclocopter no inflow,
AIRCRAFT,
orientation,reference, node,1, 0., 0., 1.,3, 0., 1., 0.,
AIRCRAFT;
The latter defines a cyclocopter with no inflow. It essentially is only useful to obtain the output data.
Example 2.
user defined: CURR_DRUM,
cyclocopter uniform 2D,
AIRCRAFT,
orientation,reference, node,1, 0., 0., 1.,3, 0., 1., 0.,
CURR_DRUM,
0, # no average# 1, # average
ROTOR_DIAMETER/2.,
SPAN,
delay,
const, 0.5,
omegacut, OMEGA_CUT,
kappa, 1.3, # hover empirical correction coefficient
timestep, DT,
output, yes;
While this one defines a cyclocopter with a twodimensional inflow model.
OutputThe output is obtained in plain text in the .usr file where the columns represent,• 1: element label294• 2–4: rotor force on the aircraft in local x, y and z directions in the optionally transformed, if<orientation> is defined, aircraft reference frame• 5–7: rotor moment about the aircraft in local x, y and z directions in the optionally transformed,
if <orientation> is defined, aircraft reference frame• 8: mean magnitude of the inflow velocity, based on momentum theory• 9–16: depends on inflow model

B.1.4

Module-fab-electric

Author: Eduardo Okabe
This module implements several electric components.
Resistor<name> ::= resistor
Capacitor<name> ::= capacitor
Inductor<name> ::= inductor
Diode<name> ::= diodeSwitch<name> ::= switch
Electrical source<name> ::= electrical source
Ideal transformer<name> ::= ideal transformer
Operational amplifier<name> ::= operational amplifier
BJT<name> ::= bjt
Proximity sensor<name> ::= proximity sensor295

B.1.5Module-fab-motion

Author: Eduardo Okabe
This module implements several joints.
Gear joint<name> ::= gear joint
Linear transmission joint<name> ::= linear transmission joint
Motion transmission joint<name> ::= motion transmission joint
Smooth step
<name> ::= smooth step

B.1.6

Module-fab-sbearings

Author: Eduardo Okabe
This module implements several joints.
Hydrodynamic bearing<name> ::= hydrodynamic bearing
Rolling bearing<name> ::= rolling bearing

B.1.7

Module-hydrodynamic plain bearing with offset

Author: Reinhard ReschThis module implements a hydrodynamic plain bearing according to Hans Jürgen Butenschön 1976
Das hydrodynamische zylindrische Gleitlager endlicher Breite unter instationärer Belastung.
<name> ::= hydrodynamic_plain_bearing_with_offset<arglist> ::=shaft, (<label>) <shaft_node> ,[ offset , (Vec3) <o1> , ]bearing , (<label>) <bearing_node> ,[ offset , (Vec3) <o2> , ]bearing width , (real) <b> ,{ , shaft diameter , (real) <d> | bearing_diameter , (real) <D> } ,relative clearance , (real) <Psi> ,oil viscosity , (real) <eta> ,initial assembly factor , (DriveCaller) <assembly_factor>296

[ , number of gauss points , (integer) <num_gauss_points> ][ , output points , (integer) <num_output_points>[ , { gauss point , (integer) <gauss_index_1 > |custom , r , (real) <r_1> ,alpha , (real) <alpha_1> }]][ , extend shaft to bearing center , { yes | no | (bool) <extend_axis_of_shaft> } ][ , epsilon max , (real) <epsilon_max> ]We assume that the axis of rotation is always axis three in the reference frame of the node. Only small
misalignments of bearing and shaft are allowed.
cos ϕ = e3 T R1 T R2 e3 ≈ 1(B.1)

The effective angular velocity of the bearing rigidly connected to node <bearing_node> is ω̄2 = e3 T R2 T ω2
and the effective angular velocity of the shaft connected to node <shaft_node> is ω̄1 = e3 T R2 T ω1 . <o1>and <o2> are the offsets between nodes and centre of the shaft and bearing respectively. The width of the
bearing is <b> and the relative clearance of the bearing is defined as <Psi> = (<D> − <d>)/<D> where <D>
is the inner diameter of bearing and <d> is the outer diameter of the shaft. <eta> is the dynamic viscosityof the oil and its SI unit is [Pa s]. It is possible to disable the hydrodynamic bearing force at the beginning of the simulation by providing some sort of ramp up function called <assembly_factor>. In orderto take into account small misalignments between shaft and bearing, one can set the number of Gauss
points <num_gauss_points> to a value of two, three or six. In that case hydrodynamic bearing forces
will be evaluated at multiple points along the width of the bearing and output will be generated for each
Gauss point by default. Output can be customised by selecting only a subset of available Gauss points
by means of <gauss_index_1> or by specifying custom locations <r_1> and weighting factors <alpha_1>
to be output. If the option <extend_axis_of_shaft> is enabled, axial movement of the shaft is allowed
and bearing kinematics and reaction forces will be evaluated at the intersection point between the axisof the shaft and centre plane of the bearing. According to the theory of a rigid bearing, eccentricitiesof ε ≥ 1 are not possible and the simulation would fail if ε becomes one or higher. In addition to that,the approximation of the Sommerfeld numbers is valid until a relative eccentricity of ε = 0.999. For thatreason a linear extrapolation of the Sommferfeld numbers is used in case of ε ≥ <epsilon_max> whichis equal to 0.999 by default.

B.1.8

Module-imu

Author: Pierangelo Masarati
This module implements an element that provides the motion of a structural node in the form of theoutput of an Inertial Measurement Unit (3 components of acceleration, 3 components of angular velocity
in body axes) and an element that prescribes the motion of a structural node in terms of acceleration
and angular velocity.
IMU
This user-defined element emulates a IMU.
<name> ::= imu<module_data> ::=<node_label>297

[ , position , (Vec3) <offset> ][ , orientation , OrientationMatrix <orientation> ]It makes the acceleration and the angular velocity of node node_label available in the node’s reference
frame as private data. The location and orientation of the IMU with respect to the node may be modified
by offset and orientation.
Output. This element sends output to the .usr file. Each entry contains
1) the label
2–4) three components of angular velocity, in the reference frame of the node
5–7) three components of acceleration, in the reference frame of the node
Private Data.

The following data are available:

1. "wx" angular velocity in local direction 1
2. "wy" angular velocity in local direction 2
3. "wz" angular velocity in local direction 3
4. "ax" acceleration in local direction 1
5. "ay" acceleration in local direction 2
6. "az" acceleration in local direction 3
IMU constraint
This user-defined element enforces IMU data as a constraint.
<name> ::= imu constraint<module_data> ::=<node_label>[ , position , (Vec3) <offset> ][ , orientation , (OrientationMatrix) <orientation> ](TplDriveCaller<Vec3>) <omega> ,(TplDriveCaller<Vec3>) <acceleration>
It imposes the angular velocity omega and the acceleration acceleration, namely the measurementsthat come from an IMU, to node node_label. The location and orientation of the IMU with respect tothe node may be modified by offset and orientation.
Output. This element sends output to the .usr file. Each entry contains
1) the label
2–4) three angular velocity Lagrange multipliers, in the reference frame of the node
5–7) three acceleration Lagrange multipliers, in the reference frame of the node8–10) three components of velocity, in the reference frame of the node
11–13) three components of velocity derivative, in the reference frame of the node298

B.1.9Module-mds

This module is a simple example of run-time loadable user-defined element, implements a scalar massdamper-spring system.

B.1.10Module-nonsmooth-nodeAuthor: Matteo Fancello<name> ::= nonsmooth node<module_data> ::=(StructDispNode) <NonsmoothNODELABEL> ,mass , (real) <mass> ,radius , (real) <radius> ,planes , (integer) <number_of_planes> ,<PlaneDefiningNODELABEL> ,position , (Vec3) <relative_plane_position> ,rotation orientation , (OrientationMatrix) <rel_rot_orientation_1> ,restitution , (real) <rest_coef>[ , friction coefficient , (real) <mu> ][ , ... ] # as many blocks as number_of_planes[ , constraint type , { position | velocity | both } ] # default: both[ , theta , <theta> ][ , gamma , <gamma> ][ , LCP solver , <solver> ][ , tolerance , <tolerance> ][ , max iterations , <num_iter> ]# these options depend on LCP solver support, see# http://siconos.gforge.inria.fr/Numerics/LCPSolvers.html[ , limit iterations , <niterations> ][ , limit LCP iterations , <niterations> ][ , verbose , { yes | no | (bool) <verbose> } ]<solver> ::=lexico lemke # the default| rpgs
| qp
| cpg
| pgs
| psor| nsqp| latin| latin_w| newton_min| newton_FB
Output• 1: element label299

• 2–4: impulse on nonsmooth node in global ref. frame• 5–7: position of nonsmooth node in global ref. frame• 8–10: velocity of nonsmooth node in global ref. frame• 11–13: constraint reaction between multibody node and nonsmooth node
• 14: norm of the impulse reaction normal to the contact plane• 15: number of active constraints during step
if verbose, also:• 16–18: position constraint relaxation factor (only when constraint type is both)• 19: LCP solver status: 0 indicates convergence, 1 indicates iter ≡ maxiter, > 1 indicates failure(only for some solvers)• 20: LCP solver resulting_error (only meaningful for some solvers)

B.1.11Module-template2

Template of user-defined element.

B.1.12Module-wheel2

Authors: Marco Morandini, Stefania Gualdi and Pierangelo Masarati
This module implements a simple tire model for aircraft landing and ground handling.

B.1.13Module-wheel4

Authors: Louis Gagnon, Marco Morandini, and Pierangelo Masarati
This module implements a rigid ring tire model similar to the models commonly known as SWIFT.
It is used as an element that will apply a 3D force and a 3D moment to the ring node of a wheelring multibody system. A wheel node is also necessary for inertia and contact forces calculations. It
is intended to evaluate the transient behavior of the tire rolling on a deteriorated road profile. The
equations are integrated implicitly except for the road profile, which is an input. This profile has to bepreviously filtered by a super ellipse function because the wheel4 module will only apply the tandem-cam
part of the profile filtering. It is tailored for, but not restricted to, applications at low camber angles,
limited steering and velocity changes, and continuous contact with the road. It is expected to be accurate
under excitation frequencies up to 100 Hz and road deformations up to 20% of the tire radius. A variable
time-step algorithm is also embed and speeds up the simulation in cases where the road is flat.
Two runnable examples are available and will clarify the implementation in an actual multibody
simulation:• the simple example axleExampleNoData located within the module-wheel4 directory of the MBDyn
package• the more complex semitrailer model is available on the example page of the MBDyn website;
this example provides the script necessary to apply the super ellipse filter on the road profile;
http://www.mbdyn.org/?Documentation___Official_Documentation___Examples

300

<name> ::= wheel4<module_data> ::=(StructDispNode) <WheelStructNodeLabel> , (StructBody) <WheelBodyLabel> ,(OrientationVector) <wheel_axle_direction> , (real) <tire_radius> ,swift ,
(StructDispNode) <RingStructNodeLabel> , (StructBody) <RingBodyLabel> ,(vector) <patch_stiffness> , (drive) <stiffness_modifier> ,(vector) <patch_damping> , (drive) <damping_modifier> ,(vector) <initial_patch_velocity> , (real) <patch_mass> ,(DriveCaller) <road_profile_driver> ,(real) <patch_to_ellip_cam_ratio> ,(real) <r_a1_param> , (real) <r_a2_param> ,(real) <patchToTireCircumf_ratio> ,(real) <vert_wheel_ring_stiff>[ , loadedRadius ][ , slip ,ginac , <longi_tire_force_funct> ,ginac , <lateral_tire_force_funct> ,ginac , <pneumatic_trail_funct> ,ginac , <aligning_residual_moment> ,(real) <S_ht> , (real) <S_hf> ,(real) <q_sy1> , (real) <q_sy3> ,(real) <dvao>[ , threshold, (real) <TRH> , (real) <TRHA> , (real) <TRHT> ,(real) <TRHTA> , (real) <TRHC> , (real) <TdLs> , (real) <TdReDiv> ,(real) <TdRe> , (real) <dtOn> , (real) <TmaxH> ,(real) <dtRes> , (real) <maxstep> , (real) <minstep> ,(real) <TmaxF> , (real) <TminF> , (integer) <TminS> , (real) <TdivF> ,(real) <TdivF3> , (real) <TdivF4> , (real) <RDA> ,(real) <RDB> , (real) <RDL> ] ]where the keyword loadedRadius enables the use of the alternative, validated, loading radius insteadof the more generally used definition. The keywords slip and threshold should always be present.
Although the given examples are the best way to understand the model, the following tables clarify most
input parameters,

301<wheel_axle_direction><tire_radius><patch_stiffness><stiffness_modifier><patch_damping><damping_modifier><initial_patch_velocity><patch_to_ellip_cam_ratio><r_a1_param><r_a2_param><patchToTireCircumf_ratio><vert_wheel_ring_stiff><longi_tire_force_func><lateral_tire_force_func><pneumatic_trail_func><aligning_residual_moment><S_ht><S_hf><q_sy1><q_sy3><dvao><dtOn><TmaxH><dtRes><maxstep><minstep><TdivF3><TdivF4>

<RDA>
<RDB>
<RDL>

tire parameters
3D vector of the wheel axle direction in the absolute reference frame(care should be taken if set to a value other than 0.,1.,0. because no
elaborate testing has been carried for alternate axle initial orientations;any comments or on its functionality are welcome)rigid ring radius (undeformed radius of the tire)
3D stiffness vector of the contact patch to ring connection (in the ringreference frame)
modifier drive to allow, for example, a gradual application of the stiffness
3D damping vector of the contact patch to ring connection (usually about
6% to 10% of critical damping and distributed over ring and patch connections)modifier drive to allow, for example, a gradual application of the damping
3D vector for the initial velocity of the patch in absolute reference frame
patch contact-length to elliptical cam tandem base parameter (Schmeitz
eq. 4.15, ls /(2a) )ra1 contact length parameter from Besselink eq. 4.85
ra2 contact length parameter from Besselink eq. 4.85
ratio of the contact patch length to tire circumference (to calculate howmuch mass contributes to the ring’s centripetal forces)
vertical stiffness given to the viscoelastic connection between the ring andthe wheel nodes
longitudinal force Fx /Fz given in GiNaC format
lateral force Fy /Fz given in GiNaC format
pneumatic trail divided by vertical force and given in GiNaC format
residual torque Mzr /Fz given in GiNaC format
horizontal shift of pneumatic trail, for aligning moment angle modifier
residual aligning moment angle modifier/shift
tire rolling resistance linear velocity coefficient (usually between 0.01 and
0.02)
rolling resistance velocity correction coefficientreference velocity for rolling resistance velocity influence factor
variable timestep algorithm parameterboolean to enable or disable adjustable timestep calculation (will greatly
increase the rapidity of the solution only if you have few bumps on a verysmooth road and will otherwise slow down the simulation)
maximum height change wanted on the road profile for one step
resolution of bump searchmaximum timestep imposed in the initial value section
minimum timestep imposed in the initial value section
timestep adjustment factor if force switched sign 3 times in the last TminS
steps
timestep adjustment factor if force switched sign 4 or more times in thelast TminS steps
road offset parameters
road offset (null before position reaches that value)road offset (interpolated when position is between <RDA> and that value)road loop condition (will loop after <RDB>+<RDL> over <RDL>)

302

<TRH><TRHA><TRHT><TRHTA><TRHC><TdLs><TdReDiv><TdRe>

algorithm threshold parameters
prevents division by zero at null x-velocity at the price of losing validity
for velocities near <TRH>
buffer used to prevent division by zeroprevents division by zero when computing the angle of the vehicle or
wheelsbuffer used on angle zero division prevention
maximum value allowed for the longitudinal slip ratio
minimum value that the half contact patch length may takeminimum value that the wheel angular velocity may take in the calculation of the effective rolling radiusmaximum ratio

ef f ectiverollingradius
ringradius

which will be allowed to reachInformation about the informally cited works may be found in the following two theses,• Schmeitz, A. J. C. (2004) A Semi-Empirical Three-Dimensional Model of the Pneumatic Tyre
Rolling over Arbitrarily Uneven Road Surfaces available on request• Besselink, I.J.M. (2000). Shimmy of Aircraft Main Landing Gears available at
http://www.tue.nl/en/publication/ep/p/d/ep-uid/227775/
OutputThe output can be obtained either in plain text in the .usr file or in NetCDF format in the .nc file.
Section C.1.3 explains the NetCDF output whereas the plain text output is as follows,• 1: element label• 2: velocity of wheel in x-dir (longitudinal, forward)• 3: velocity of wheel in y-dir (lateral)• 4: relative speed between center of wheel and contact point on tire in the forward direction• 5–7: moment applied on ring by this module• 8–10: moment arm on ring
• 11: slip ratio• 12: slip angle• 13: longitudinal friction coefficient• 14: lateral friction coefficient• 15: road height• 16–18: road normal• 19–21: position of patch• 22–24: velocity of patch• 25–27: relative position of patch• 28–30: relative velocity of patch303

• 31–33: force between ring and patch acting on patch• 34–36: force between ring and patch acting on ring and thus applied on ring by this module• 37–39: forward direction vector of the wheel• 40–42: forward direction vector of the ring• 43–45: forward direction vector of the ring without the slope of the profile• 46–48: point of contact on ring between ring and springs (contact patch viscoelastic elements)• 49: normal force for Pacejka’s formulas• 50–52: relative velocity between patch and wheel• 53: sum of wheel, ring, and patch kinetic energies• 54: sum of wheel and ring potential energies (patch is not included because it is not subjected togravity)• 55: sum of wheel, ring, and patch total energies (kinetic + potential)• 56: virtually calculated effective rolling radius• 57: half length of the tandem elliptical cam follower• 58: modified loaded radius (distance between ring center and patch center)• 59–61: distance between ring contact point and patch as seen from the ring in its own reference
frame (not rotated with road slope)• 62: centrifugal force added to tire
• 63–65: rolling resistance force vector (this force is then applied as a moment only)• 66–68: aligning moment• 69: center point x-value of the road profile (this is not actual position, but only position on the
input road file
• 70: front edge x-point of the tandem (front contact point of patch)• 71: rear edge x-point of the tandem (rear contact point of patch)• 72: centrifugally induced virtual displacement of tire in the radial direction (units of distance)• 73: patch vertical velocity calculated using road displacement and timestep• 74: timestep

B.2

Constitutive Law Modules

B.2.1

Module-constlaw

Simple example of run-time loadable user-defined constitutive law.

304

B.2.2Module-constlaw-f90

Simple example of run-time loadable user-defined constitutive law in Fortran 90.

B.2.3

Module-constlaw-f95

Simple example of run-time loadable user-defined constitutive law in Fortran 95.

B.2.4

Module-cont-contact

Author: Matteo FancelloImplements various formulas of 1D continuous contact models. The same constitutive law can also be
used as a 3D constitutive law, under the assumption that the 1D formulas are considered with respect
to direction 3 of the 3D entity it is associated with. In such case, the component 3 of strain and strain
rate are used as inputs, and the output force is applied along direction 3.
The syntax is<drive_caller> ::= help ;| [ help , ][ sign , { positive | negative | <sign_value> } , ][ formulation , { flores | hunt crossley | lankarani nikravesh } , ]restitution , <restitution_coef> ,kappa , <stiffness> ,exp , <exponent>[ , EpsPrimeTol , <initial_eps_prime_tol> ]• <sign_value> is a non-null real number, whose sign is used for the sign parameter.
• <restitution_coef> is the restitution coefficient ([0 → 1]).
• <stiffness> is the stiffness coefficient (> 0).
• <exp> is the exponent (> 1).
• <initial_eps_prime_tol> is the tolerance on the initial contact velocity (> 0).
Three models are implemented. They all use the strain and the strain rate, either as are, when sign
is positive, or their opposite, when sign is negative,x = sign_value · Eps(B.2a)ẋ = sign_value · EpsPrime(B.2b)The expression of the force is
f =0
f = sign_value · xexp (stiffness + dissipation_coef · ẋ)

x≤0

x>0

(B.3a)(B.3b)

with the dissipation coefficient dissipation_coef defined according to each of the supported models.
Their formulation is:• flores [23]: this is the default model; the dissipation coefficient isdissipation_coef =8
1 − restitution_coef· stiffness ·5
restitution_coef · ẋ0Note that in this case 0 < restitution_coef ≤ 1.
305

(B.4)

• hunt crossley [24]: the dissipation coefficient isdissipation_coef =3
1 − restitution_coef· stiffness ·
2
ẋ0

(B.5)

• lankarani nikravesh [25]: the dissipation coefficient isdissipation_coef =3
1 − restitution_coef2· stiffness ·
4
ẋ0

(B.6)

Note that dissipation_coef = 0 when |ẋ0 | < initial_eps_prime_tol; i.e., when the initial contact
velocity is below the threshold, no dissipation takes place.

B.2.5

Module-damper-graall

Author: Pierangelo Masarati, based on an original work of Gian Luca GhiringhelliThis module implements a 1D constitutive law that models the behavior of a landing gear shock
absorber. It requires the user to supply the name of the GRAALL-style input file that contains the dataof the damper. It will be documented as soon as it reaches an appreciable level of stability. See also theshock absorber constitutive law.

B.2.6

Module-damper-hydraulicAuthor: Pierangelo Masarati
This module implements a simple hydraulic damper with turbulent orifice and relief valve.

B.2.7

Module-muscles

Authors: Andrea Zanoni and Pierangelo Masarati
This module implements a family of simple muscle constitutive laws, based on [26].
<drive_caller> ::= muscle Pennestri ,[ initial length , <Li> , ]reference length , <L0> ,[ reference velocity , <V0> , ]reference force , <F0> ,activation , (DriveCaller) <activation>[ , activation check , (bool) <activation_check> ][ , ergonomy , { yes | no } ][ , reflexive , # only when ergonomy == noproportional gain , <kp> ,derivative gain , <kd> ,reference length , (DriveCaller) <lref> ]The ergonomy flag, when active, indicates that the equivalent damping must not be used. It is used toindicate that the constitutive law acts as an “ergonomy” spring in an inverse kinematics analysis.
The reflexive keyword indicates that reflexive behavior is being defined; its use is mutually exclusivewith the active status of the ergonomy flag.
The initial length equal to reference length unless specified. It is used to differentiate thelength of the rod as computed from the input from the length used to formulate the constitutive law.
306

The reference velocity is set to 2.5 m/s unless specified.
The second occurrence of the reference length is related to the reflexive contribution to muscular
activation, which is defined as


lref
ℓ̇
ℓ
a = activation + kp ·+ kd ·
−
(B.7)
L0
L0
V0

B.3

Drive Caller Modules

B.3.1

Module-drive

Simple example of run-time loadable user-defined drive caller.

B.3.2

Module-randdrive

Generates normally distributed pseudo-random numbers with given mean and variance (standard deviation) using the random number handling capabilities provided by Boost1 .
<drive_caller> ::= boost random ,(real) <mean> , (real) <variance>
The module itself supports load-time input parameters:
module load : "libmodule-randdrive"[ , { seed , (integer) <seed> ]| seed input file name , " <seed_input_file_name> " } ][ , seed output file name , " <seed_output_file_name> " ]where the integer seed is used to seed the random number generator, whereas seed_input_file_name
and seed_output_file_name are used to load/save the random number generator’s state in Boost’s
internal format.

B.4

Template Drive Caller Modules

B.4.1

Module-eu2phi

This module implements a TplDriveCaller<Vec3> drive caller that converts three Euler angles into thecorresponding Euler vector.
Syntax:eu2phi ,[ help , ][ format , { euler123 | euler313 | euler321 } , ](TplDriveCaller<Vec3>) <drive>
Example:# assuming that file drive 1 provides Euler angles 1, 2 and 3 in channels 1, 2, 3:
joint: 10, total joint,
1001,
1002,
1 http://www.boost.org/

307

orientation constraint, active, active, active,
eu2phi, format, euler123,
component,
file, 1, 1,
file, 1, 2,
file, 1, 3;

B.5

Driver Modules

Recall that driver modules are invoked as file drivers, whose syntax is<driver_type> ::= file<normal_arglist> ::= <name> [ , <module_data> ]B.5.1

Module-HID

This module provides input from joysticks in the form of a stream, using the Human Interface Device(HID) standard. It is the user’s responsibility to map the device’s output to stream channels.
<name> ::= joystick<module_data> ::= <file> ,<number_of_buttons> ,<number_of_linear_controls>[ , scale , <scale_factor> [ , ... ] ] ; # scale_factors default to 1.0
This stream makes available number_of_buttons + number_of_linear_controls channels. It is assumed that linear controls come after buttons; scale_factors apply to linear controls.
The value of buttons is 0 when not pressed, and 1 when pressed.
The value coming from linear controls is (assumed to be) comprised between -UINT16_MAX andUINT16_MAX; it is multiplied by its scale_factor and divided by UINT16_MAX, so that the value provided by the channel is comprised between -scale_factor and scale_factor. In some cases, the value
coming from linear controls can be comprised between 0 and UINT16_MAX; it is suggested to handle thisoccurrence, if needed, by means of an additional linear drive caller before using the value provided bythis stream driver.
Example:file: 999, joystick,"/dev/input/js0",# joystick device
8,# number of buttons
6,# number of linear controls
scale, 1., 10., 100., 256., 1., 1.;
Note that HID provide events when they occur, whereas the logic of file drivers is that of gathering
information and making it consistently available through the solution of a time step.
For buttons, the indication that the button was pressed across two time steps is returned. If the
button was released, or pressed and released multiple times, only the indication that is was pressed (atleast once) is actually returned.
For linear controls, the last measured value across two time steps is returned.

308

B.6

Scalar Function Modules

B.6.1

Module-scalarfunc

Simple example of run-time loadable user-defined scalar function.

B.7

Miscellaneous Modules

B.7.1

Module-flightgear

Author: Luca Conti (supported by Google Summer of Code 2017)
This module implements...
It consists of three components:• a stream modifier for FlightGear flight dynamics data
• a stream modifier for FlightGear controls data
• a customization of the file drive caller to support retrieval of FlightGear specific data from stream
drives (see Section 2.6.13)
The stream modifiers are used in conjunction with stream output elements for communication to FlightGear (see Section 8.16.1), and with stream drivers for communication from FlightGear (see Section 7.1.5).
Stream Output Element<user_defined> ::= <user_defined_type> ,{ NetFDM | NetCtrls }[ , print options ], <var_name> , <value>[ , ...]<user_defined_type> ::= flightgear
where <value> is currently either drive or nodedof, followed by the related arguments as illustrated in
Streamed output (see Sec. 8.16.1). The supported values for <var_name> are listed below with reference
to flight dynamics (NetFDM) or controls (NetCtrls).
Stream Drive<user_defined> ::= <user_defined_type> ,{ NetFDM | NetCtrls }[ , print options ]<user_defined_type> ::= flightgear
Flight Dynamics Available Channels•

309

Controls Available Channels•
File Drive Customization<user_defined> ::= <user_defined_type> , <var_name><user_defined_type> ::= flightgear
The supported names are those listed above for flight dynamics and controls. The correct subset ischosen based on the type of stream drive the label refers to, i.e. when the file drive caller points to a
stream driver related to flight dynamics (NetFDM), the flight dynamics related values for var_name must
be used. Similarly, the controls related values for var_name must be used when the file drive caller points
to a stream driver related to controls (NetCtrls).
Example# ...
\begin{drivers}# ...
file: CTRLS, stream,
name, "CTRLS",
create, yes,
port, 9011,
socket type, udp,
non blocking,flightgear, NetCtrls, print options;# ...
\end{drivers}\begin{elements}# ...
stream output: FDM,
stream name, "FG_FDM",
create, no,port, 9012,
host, "0.0.0.0",
socket type, tcp,
non blocking,flightgear, NetFDM, print options,longitude, drive, node, AIRCRAFT, structural, string, "X[1]", direct,
latitude, drive, node, AIRCRAFT, structural, string, "X[2]", direct;..., file, CTRLS, flightgear, aileron;..., file, CTRLS, flightgear, throttle_01, amplitude, 100.;\end{elements}

B.7.2# use as is# scaleModule-octave

Author: Reinhard ReschThis module implements support for octave-based user-defined entities, including drive callers, constitutive laws, scalar functions, and elements.
310

General octave flags
Every GNU Octave based entity supports the following flags:<octave_flags> ::= [ update octave variables, { yes | no | (bool) <status> }, ][ update mbdyn variables, { yes | no | (bool) <status> }, ][ update global variables, { yes | no | (bool) <status> }, ][ pass data manager, { yes | no | (bool) <status> }, ][ embed octave, { yes | no | (bool) <status> }, ][ octave search path, (string) <path1> [ , ... ] ]Global variables If the flag update octave variables is enabled, MBDyn’s symbol table is copied
to the global Octave name space before each function call. This flag should be used only if the Octave
function has to access things like plug in variables which depend on the state of the simulation. If
this flag is not enabled (the default) MBDyn’s symbol table is copied only before the first call of any
Octave function. If the flag update mbdyn variables is enabled, MBDyn’s symbol table is updated by
Octave’s global variables after each function call. Only those variables that exist in MBDyn’s symbol
table are updated. The flag update global variables is a combination of update octave variables
and update mbdyn variables.
Additional arguments If the flag pass data manager is enabled, a pointer to MBDyn’s data manager is passed to the Octave function as the last argument.
Embed octave The flag embed octave makes it possible to write Octave functions directly inside the
MBDyn input file. This is especially useful for small models. If this flag is enabled, the MBDyn input
file where embed octave appears will be sourced into Octave before the first function call. In order towork it is necessary to put all MBDyn specific commands inside a #{ . . . #} comment, and to put all
Octave specific code inside a #/* . . . #*/ comment.
Octave’s search path Directories which should be appended to Octave’s search path should appear
after octave search path. This is rather a global option and is not specific to a particular element ordrive caller.
Element
An Octave element is a full featured user defined MBDyn element written in GNU Octave scripting
language. From Octave’s point of view an Octave element is a special class.
<elem_type> ::= user defined<normal_arglist> ::= octave , " <class_name> "[ , <octave_flags> ][ , <elem_data> ]All member functions of this class must reside in a directory named “@<class_name>”. The parent
directory of “@<class_name>” must be in Octave’s search path. Additional Element specific data in<elem_data> like node labels, vectors and rotation matrices may be accessed from within the constructorof the Octave class. If the octave-ad package is installed, the D function can be used to in order tocompute the Jacobian matrix from the residual.

311

Octave element member functions At the moment the following member functions are supported:• [elem] = <class_name>(pMbElem, pDM, HP)• [iRows, iCols] = WorkSpaceDim(elem)• [iNumDof] = iGetNumDof(elem) # optional; iNumDof == 0 if missing• SetValue(elem, XCurr, XPrimeCurr) # optional• [f, ridx] = AssRes(elem, dCoef, XCurr, XPrimeCurr)• [Jac, ridx, cidx, bSparse] = AssJac(elem, dCoef, XCurr, XPrimeCurr) # optional• [elem] = Update(elemin, XCurr, XPrimeCurr) # optional• [iRows, iCols] = InitialWorkSpaceDim(elem) # optional• [iNumDof] = iGetInitialNumDof(elem) # optional• SetInitialValue(elem, XCurr) # optional• [f, ridx] = InitialAssRes(elem, XCurr) # optional• [Jac, ridx, cidx, bSparse] = InitialAssJac(elem, XCurr) # optional• [order] = GetDofType(elem, i) # optional• [order] = GetEqType(elem, i) # optional• [elem] = AfterPredict(elemin, XCurr, XPrimeCurr) # optional• [elem] = AfterConvergence(elemin, XCurr, XPrimeCurr) # optonal• [iNumPrivData] = iGetNumPrivData(elem) # optional• [iPrivDataIdx] = iGetPrivDataIdx(elem, name) # optional• [dPrivData] = dGetPrivData(elem, i) # optional• [iNumConnectedNodes] = iGetNumConnectedNodes(elem) # optional• [connectedNodes] = GetConnectedNodes(elem) # optional• Output(elem, outStream) # optional• DescribeDof(elem, out, prefix, bInitial) # optional• DescribeEq(elem, out, prefix, bInitial) # optional• Restart(elem, out) # optional
Semantic and parameters of these functions are almost the same like in C++.
TODO: Describe the meaning of the parameters!

312

Drive Caller
An Octave drive caller could be used as an alternative to string drives or GiNaC drives. If the octave-ad
package is installed, Octave based drive callers are differentiable by default. An arbitrary number of additional arguments can be passed to the Octave function <function_name> after the arguments keyword.
<drive_caller> ::= octave , " <function_name> "[ , <octave_flags> ][ , arguments, (integer) <count>, <arg_1> [ , ... , <arg_n> ] ]Template Drive Caller
The syntax of a template drive caller is the same like the scalar drive caller. Of course the Octave
function must return a matrix or a vector according to the dimension of the drive caller. The templatedrive caller is also differentiable by default.
<tpl_drive_caller> ::= octave , " <function_name> "[ , <octave_flags> ][ , arguments, (integer) <count>, <arg_1> [ , ... , <arg_n> ] ]Scalar Function<scalar_function> ::= octave , " <function_name> "[ , <octave_flags> ][ , arguments, (integer) <count>, <arg_1> [ , ... , <arg_n> ] ]Constitutive Law
Octave constitutive laws are full featured user defined constitutive laws. Additional constitutive law
specific data in <const_law_data> may be accessed from within the constructor of the Octave class.
<specific_const_law> ::= octave , " <class_name> "[ , <octave_flags> ]dimension , <dimension>[ , <const_law_data> ]Octave constitutive law member functions At the moment the following member functions aresupported:• [cl] = <class_name>(pDM, HP)• [cl, F, FDE, FDEPrime] = Update(clin, Eps, EpsPrime)• [constLawType] = GetConstLawType(cl)If the octave-ad package is installed, the D function can be used to compute FDE and FDEPrime fromfunction F. Semantic and parameters of these functions are almost the same like in C++.
TODO: Describe the meaning of the parameters!

B.7.3

Module-tclpgin

This module implements the Tcl plugin in form of run-time loadable module.

313

B.7.4Module-template

Loadable element template (deprecated).

B.7.5

Module-udunits

Author: Pierangelo Masarati
This module implements a namespace called units that provides unit-conversion capabilities to themathematical parser, based on the UDUnits library. The namespace provides only the function convert,
which is thus invoked as units::convert. This function’s prototype is(real) units::convert( (string) <from> , (string) <to> [ , (real) <val> ] )where• from is a string indicating what units to convert from;• to is a string indicating what units to convert to;• val is an optional real argument that indicates what value should be converted.
When called with just the two mandatory arguments, the function returns the scale factor between the
two units; for example
units::convert("ft", "m")returns 0.3048.
When called with the third optional argument val as well, the function returns the optional argument
val converted according to the conversion arguments; for example
units::convert("ft", "m", 10.)returns 3.048, corresponding to0.3048 m/ft * 10 ft
The first form may not be enough, for example, for those conversions that include an “intercept”; forexample, when converting from degrees Celsius to degrees Fahrenheit, the actual conversion would be
F = 32 + 9 / 5 * C
In those cases, the conversion fails, unless the third argument is specified; for example
units::convert("Celsius", "Fahrenheit")
would fail, while
units::convert("Celsius", "Fahrenheit", 0.)would return 32.
This module requires UNIDATA’s libudunits; get it fromhttp://www.unidata.ucar.edu/software/udunits/.
Some Linux distributions provide it packaged; for example, recent Ubuntu releases provide a library
libudunits2; to use it, tweak the configuration variables in modules/module-udunits/Makefile.inc.

314Appendix C

NetCDF Output Format
NetCDF support has been initially contributed by Patrick Rix.
NetCDF is a format to efficiently store and retrieve data to and from a database on file in a portable,
platform-independent manner. Further details can be found at
http://www.unidata.ucar.edu/software/netcdf/
and in [27]. The link reported above also describes some of the common tools that can be used to readand manipulate the contents of the database.
The output in NetCDF format consists in a single binary file written by the NetCDF library andintended to be read by tools exploiting the library itself. This document does not describe the details of
NetCDF low-level format, since this is not intended to be accessed directly by MBDyn users. Interested
readers can consult the specific documentation [27].
The output in NetCDF format is a work-in-progress, so it may be subjected to changes during thedevelopment of MBDyn. This chapter is intended to document its current status, so it may be incomplete,and occasionally outdated as well.

C.1

NetCDF Output

Following the convention of NetCDF data, each datum is defined by a variable, whose name indicates
the type of datum and the entity that generated it, organized in a tree-like fashion.
For example, the vector containing the three components of the position of the structural nodelabeled label isnode.struct.<label>.X
Each variable usually has few attributes:• a description is usually given;• the units are specified, unless variables are non-dimensional;• the type is specified, if relevant; it contains the name of the C/C++ structure the data was taken
from.
Each level contains some datum that is intended to make the contents of the database as selfexplanatory as possible. For example, the level node contains an array whose values are the strings
indicating the node types available; each level node.<type> contains the labels of the available nodes forthat type, and so on.
315

C.1.1

Base Level

Currently, the following basic levels are available:• run, for general simulation-related data;• node, for nodes;• elem, for elements.

C.1.2

Run Level

There is no variable run, with the name of the run level. This level contains general, simulation-relateddata:• run.step, the step number;• time (previously run.time), the value of the time;• run.timestep, the value of the timestep.
Note: the run.time variable has been renamed time because many NetCDF manipulation tools automatically recognize this name as the ordering variable for the rest of the data.

C.1.3

Node Level

There is no variable node, with the name of the node level. This level contains as many sublevels as thenode types that are present in the model. Each node type consists in a variable that contains an arraywith the labels (integers) of the nodes defined for that type. A variable named node.<type>.<label>
may be present (it is, for example, for structural nodes); however, useful data are usually containedin specific variables, whose names describe the contents.
Currently supported node types are:
• Structural nodes, indicated as struct.
Structural Node
The following variables are defined.
• node.struct.<label> is actually empty; it contains the type of the structural node in the typeattribute;• node.struct.<label>.X contains the position of the node, in the appropriate reference frame;• node.struct.<label>.R contains the orientation matrix of the node, in the appropriate reference
frame;• node.struct.<label>.Phi contains the orientation vector describing the orientation of the node,in the appropriate reference frame;• node.struct.<label>.E contains the Euler angles describing the orientation of the node, in theappropriate reference frame;• node.struct.<label>.XP contains the velocity of the node, in the appropriate reference frame;• node.struct.<label>.Omega contains the angular velocity of the node, in the appropriate reference frame.
316

Note that only one of R, Phi, or E are present, depending on the requested description of the orientationof the node (see structural node, Section 6.1, and default orientation, Section 5.2.10).
The dynamic and modal node types, if requested, can output extra variables.
• node.struct.<label>.XPP contains the acceleration of the node, in the appropriate reference
frame;• node.struct.<label>.OmegaP contains the angular acceleration of the node, in the appropriate
reference frame.
If requested, the inertia associated to dynamic nodes is output within the namespace of the node,
although actually handled by the corresponding automatic structural element. As a consequence,extra variables can appear in the output of dynamic nodes.
• node.struct.<label>.B contains the momentum of the inertia associated to the node, in theappropriate reference frame;• node.struct.<label>.G contains the momenta moment of the inertia associated to the node, in
the appropriate reference frame;• node.struct.<label>.BP contains the derivative of the momentum of the inertia associated to
the node, in the appropriate reference frame;• node.struct.<label>.GP contains the derivative of momenta moment of the inertia associated to
the node, in the appropriate reference frame.

C.1.4

Element Level

There is no variable elem, with the name of the element level. This level contains as many sublevels
as the element types that are present in the model. Each element type consists in a variable that
contains an array with the labels (integers) of the elements defined for that type. A variable named
elem.<type>.<label> may be present; however, useful data are usually contained in specific variables,
whose names describe the contents.
Currently supported element types are:• Automatic structural elements, indicated as autostruct.
• Beam elements, indicated as beam2 and beam3 for 2- and 3-node beam elements, respectively.
• Force and couple elements, indicated as force and couple.
Aerodynamic Elements
NetCDF output of aerodynamic elements has been sponsored by REpower Systems AG.
The aerodynamic elements allow to define a broad set of variables. Values are output at the integration
points. Each element allows to define n integration points. The aerodynamic body outputs at n points.
The aerodynamic beam2 outputs at 2 · n points. The aerodynamic beam3 outputs at 3 · n points.
Output.
• elem.aerodynamic.<label>.X_<i> contains the location of the integration point i, in the global
reference frame;• elem.aerodynamic.<label>.R_<i> contains the orientation matrix of the airfoil at the integration
point i, in the global reference frame;317

• elem.aerodynamic.<label>.Phi_<i> contains the rotation vector that describes the orientationof the airfoil at the integration point i, in the global reference frame;• elem.aerodynamic.<label>.E_<i> contains the set of Euler angles that describes the orientationof the airfoil at the integration point i, in the global reference frame. The sequence of the angles
is detailed in the variable’s description. It can be 123 (the default), 313 or 321;
• elem.aerodynamic.<label>.V_<i> contains the velocity of the integration point i, in the global
reference frame;• elem.aerodynamic.<label>.Omega_<i> contains the angular velocity of the integration point i,in the global reference frame;• elem.aerodynamic.<label>.F_<i> contains the force at the integration point i, in the absolutereference frame;• elem.aerodynamic.<label>.M_<i> contains the moment at the integration point i, in the absolutereference frame, referred to the location of the integration point.
Note: variables R_<i>, Phi_<i> and E_<i> are mutually exclusive.
Note: by default, only variables elem.aerodynamic.<label>.F_<i> and elem.aerodynamic.<label>.M_<i>are output. See Section 8.1.1 for indications about how to customize aerodynamic element output in
NetCDF format.
Automatic Structural
No variables are explicitly defined for the automatic structural element; on the contrary, their specificdata, if requested, is appended to the corresponding dynamic structural node.
Beam
The beam elements allow to define a broad set of variables.
Two-Node Beam Element. The two-node beam element allows to define the variables• elem.beam.<label>.X contains the location of the evaluation point, in the global reference frame;• elem.beam.<label>.R contains the orientation matrix of the beam section at the evaluation point,in the global reference frame;• elem.beam.<label>.Phi contains the rotation vector that describes the orientation of the beam
section at the evaluation point, in the global reference frame;• elem.beam.<label>.E contains the set of Euler angles that describes the orientation of the beam
section at the evaluation point, in the global reference frame. The sequence of the angles is detailed
in the variable’s description. It can be 123 (the default), 313 or 321;
• elem.beam.<label>.F contains the internal force at the evaluation point, in the reference frameof the beam section;• elem.beam.<label>.M contains the internal moment at the evaluation point, in the reference frameof the beam section;• elem.beam.<label>.mu contains the linear strain at the evaluation point, in the reference frameof the beam section;318

• elem.beam.<label>.k contains the angular strain at the evaluation point, in the reference frameof the beam section;• elem.beam.<label>.muP contains the linear strain rate at the evaluation point, in the reference
frame of the beam section;• elem.beam.<label>.kP contains the angular strain rate at the evaluation point, in the reference
frame of the beam section.
Note: variables R, Phi and E are mutually exclusive.
Note: variables muP and kP are only available for viscoelastic beam elements.
Note: by default, only variables F and M are output. See Section 8.3.2 for indications about how tocustomize beam element output in NetCDF format.
Three-Node Beam Element. The three-node beam element allows to define the same set of variablesof the two-node one, postfixed with either _I or _II to indicate the first (between nodes 1 and 2) or thesecond (between nodes 2 and 3) evaluation point.
Force
The various flavors of force and couple elements allow different variables.
Absolute displacement force:the type is absolute displacement.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
Internal absolute displacement force:the type is internal absolute displacement.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
Absolute force:the type is absolute.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
• elem.force.<label>.Arm contains the three components of the arm, in the absolute reference
frame.
Follower force:the type is follower.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
• elem.force.<label>.Arm contains the three components of the arm, in the absolute reference
frame.
Absolute couple: the type is absolute.
• elem.couple.<label>.M contains the three components of the couple, in the absolute reference
frame.
Follower couple: the type is follower.
• elem.couple.<label>.M contains the three components of the couple, in the absolute reference
frame.
319

Internal absolute force:the type is internal absolute.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
• elem.force.<label>.Arm1 contains the three components of the arm with respect to node 1, in
the absolute reference frame.
• elem.force.<label>.Arm2 contains the three components of the arm with respect to node 2, in
the absolute reference frame.
Internal follower force:the type is internal follower.

• elem.force.<label>.F contains the three components of the force, in the absolute reference frame.
• elem.force.<label>.Arm1 contains the three components of the arm with respect to node 1, in
the absolute reference frame.
• elem.force.<label>.Arm2 contains the three components of the arm with respect to node 2, in
the absolute reference frame.
Internal absolute couple: the type is internal absolute.
• elem.couple.<label>.M contains the three components of the force, in the absolute reference
frame.
Internal follower couple: the type is internal follower.
• elem.couple.<label>.M contains the three components of the force, in the absolute reference
frame.

C.1.5

Eigenanalysis

The binary output of eigenanalysis is structured as follows.
Base level
If at least one eigenanalysis is requested, a base level is added, called eig. This level contains generaldata:• eig.step, the step number at which each eigenanalysis was performed;• eig.time, the time in seconds at which each eigenanalysis was performed;• eig.dCoef, the coefficient used to build the problem matrices;• eig.idx, the indexes of the nodes dofs in the eigenvectors.
Analysis level
For each analysis, a level eig.<index> is created. The requested outputs are then added to the level.

320Full matrices. If output full matrices was specified, the following variables are added to theeig.<index> level:• eig.<index>.Aplus : contains the J(+c) = f/ẋ + dCoef · f/x matrix;• eig.<index>.Aminus : contains the J(−c) = f/ẋ − dCoef · f/x matrix.
Both matrices are stored in full format.
Sparse matrices. If output sparse matrices was specified, the following variables are added to theeig.<index> level:• eig.<index>.Aplus : contains the J(+c) = f/ẋ + dCoef · f/x matrix;• eig.<index>.Aminus : contains the J(−c) = f/ẋ − dCoef · f/x matrix.
and the following dimensions specified• eig_<index>_Aplus_sp_iSize : represents the number of nonzero elements in matrix Aplus;• eig_<index>_Aminus_sp_iSize : represents the number of nonzero elements in matrix Aminus;
Both matrices are stored in sparse format.
Eigenvalues and Eigenvectors. If output eigenvectors was specified, the following variables areadded to the eig.<index> level:• eig.<index>.VR : contains the right eigenvectors matrix;• eig.<index>.VL : contains the left eigenvectors matrix, only written if the chosen method computesit;• eig.<index>.alpha : contains the alpha matrix, in which the first row contains the αr coefficients,
the second row the αi coefficients and the third row the β coefficients, so that the k-th discrete
time eigenvalue isΛk =αr (k) + iαi (k)
.
β(k)

(C.1)

while the corresponding continuous time domain eigenvalue λk is
λk =1 αr (k)2 + αi (k)2 − β(k)2 + i2αi (k)β(k)1 Λk − 1.
=2
dCoef Λk + 1
dCoef(αr (k) + β(k)) + αi (k)2

(C.2)

Note that this means that the transposed of the alpha matrix as described in Section 4.1.1 iswritten in the NetCDF file;
Both matrices VR and VL (when available) are stored as 3D matrices, where the first index of the third
dimension refers to the real part of the eigenvectors and the second index of the third dimension to theimaginary part. So to store the matrices in complex shape in software packages that support is, forexample in Octave, a procedure like the following must be used (here making use of the Octave package
netcdf, see Section C.2.1):

321

Example 1.
# load the VR matrix in 3D format
octave:1> VR_3D = ncread(’mbdyn_output.nc’, ’eig.0.VR’);octave:2> VR_cpx = VR_3D(:, :, 1) + 1i*VR_3D(:, :, 2);octave:3> clear VR_3D
octave:4> VR(’component’, ’mode’) % access ’component’ of ’mode’
The same using the Octave package octcdf, see Section C.2.1:# load the VR matrix in 3D format
octave:1> nc = netcdf(’mbdyn_output.nc’, ’r’);octave:2> VR_3D = nc{’eig.0.VR’}(:);
octave:3> VR_cpx = VR_3D(1, :, :) + 1i*VR_3D(2, :, :);octave:4> clear VR_3D
octave:5> VR_cpx(component, mode); % access ’component’ of ’mode’
The following example shows how to reconstruct the discrete time eigenvalues vector Lambda and thecorresponding continuous time eigenvalues vector lambda (see Section 4.1.1):
Example 2.
# load alpha and dCoef of eigensolution 0
octave:1> alpha = ncread(’mbdyn_output.nc’, ’eig.0.alpha’);octave:2> dCoef = ncread(’dbp.nc’, ’eig.dCoef’, 1, 1);# compute Lambda (discrete time) and lambda (continuous time)
octave:3> Lambda = (alpha(1,:) + 1i*alpha(2,:))./alpha(3,:);octave:4> lambda = 1/dCoef*((Lambda - 1)./(Lambda + 1));
Geometry. As opposed to the .m text file output, the reference configuration is not written separately
in the NetCDF output, since it is already available from the standard structural nodes’ output.
For example, to access the reference configuration of node 10, during the first calculated eigensolution,
the following procedure can be used in Octave (here, again, making use of the Octave package netcdf,
see Section C.2.1):
Example 1.
# access the position and orientation of node 10 during eigensolution 0
octave:1> ts = ncread(’mbdyn_output.nc’, ’eig.step’, 1, 1);
octave:2> X0_10 = ncread(’mbdyn_output.nc’, ’node.struct.10.X’, [1, ts(1)], [3, 1])
octave:3> Phi0_10 = ncread(’mbdyn_output.nc’, ’node.struct.10.Phi’, [1, ts(1)], [3, 1])
The following function can be used to recover the complete reference configuration
Example 2.
function X0 = eig_geom(ncfile, eig, orient)%% EIG_GEOM -- Extracts the reference configuration of the eigensolution of%index eig from MBDyn NetCDF output file ncfile, that is written%with default orientation orient
%
322

%
%
%
%
%
%
%
%
%

INPUTS:- ncfile -- filename (full path) of MBDyn NetCDF output file
- eig-- index of eigensolution of interest- orient -- string identifying the orientation used forthe structural nodes output. Please note that thisfunction does not handle multiple output
orientation descriptions
X0 = eig_geom(ncfile, eig, orient)pkg load netcdf
step = ncread(ncfile, ’eig.step’, eig + 1, 1);
nodes = ncread(ncfile, ’node.struct’);
if orient == ’R’ncoord = 12;
else
ncoord = 6;
end
X0 = zeros(length(nodes)*6, 1);
for ii = 1:length(nodes)
nodevar = [’node.struct.’ num2str(nodes(ii)) ’.’];
x_bg = (ii - 1)*ncoord + 1;
r_bg = x_bg + 3;
X0(x_bg:x_bg + 2) = ncread(ncfile, [nodevar ’X’], [1 step], [3 1]);
if orient == ’R’
X0(r_bg:r_bg + 2) = ncread(ncfile, [nodevar orient], [1 1 step], [3 1 1]);
X0(r_bg + 3: r_bg + 5) = ncread(ncfile, [nodevar orient], [1 2 step], [3 1 1]);
X0(r_bg + 6: r_bg + 8) = ncread(ncfile, [nodevar orient], [1 3 step], [3 1 1]);
else
X0(r_bg:r_bg + 2) = ncread(ncfile, [nodevar orient], [1 step], [rN 1]);
end
end

end
The reference configuration of eigensolution 0, with default orientation set to orientation vector(see Section 5.2.10 and C.1.3) is extracted withoctave:1> X0 = eig_geom(’mbdyn_output.nc’, 0, ’Phi’)In the same fashion, the reference configuration of eigensolution 2, with default orientation set toorientation matrix is extracted withoctave:1> X0 = eig_geom(’mbdyn_output.nc’, 2, ’R’)
The orientation matrix of the node 3 (supposing it is also the third node in the model) in the reference
configuration is, thenoctave:2> R3 = zeros(3,3);octave:3> R3(:) = X0(2*12 + 4, 3*12);
323

C.2

Accessing the Database

The database can be accessed using any of the tools listed at the web site
http://www.unidata.ucar.edu/software/netcdf/software.html(yes, including MBDyn itself. . . )C.2.1

OctaveOctave used to provide access to NetCDF databases using the (possibly outdated) octcdf package. The
preferred package is the netcdf package.
OctCDF (WARNING: possibly outdated).

The octcdf package, available fromhttp://ocgmod1.marine.usf.edu/,
provides a clean interface to using NetCDF databases from within the popular math environment Octave.
Results from MBDyn can be easily handled once the data structure is known.
To access the database, a handler needs to be obtained by callingoctave:1> nc = netcdf(’mbdyn_output.nc’, ’r’);
Variable descriptions are accessed as
octave:2> nc{’node.struct.1000.X’}
Their values are accessed as
octave:3> nc{’node.struct.1000.X’}(10, 3)
So, for example, the z component of the position of node 1000 can be plot withoctave:4> plot(nc{’time’}(:), nc{’node.struct.1000.X’}(:,3))
NetCDF. The netcdf package appears to have superseded the octcdf package in recent distributionsof Octave. It is no longer necessary to obtain a handler to the MBDyn output file.
Variable properties are displayed withoctave:1> ncinfo(’mbdyn_output.nc’, ’node.struct.1000.X’);
Single records (in this example the position of node 10 at step 15) are accessed withoctave:2> X10_15 = ncread(’mbdyn_output_nc, ’node.struct.10.X’, [1, 15], [3, 1]);
Single values (in this example the z-position of node 10 at step 15) withoctave:3> X10_15_z = ncread(’mbdyn_output_nc, ’node.struct.10.X’, [3, 15], [1, 1]);324

Appendix D

Results Visualization
This section describes the different ways the raw output from MBDyn can be arranged to work withthird-party software for visualization. In most of the cases, the preparation of the results can be done asa post-processing, starting from raw MBDyn output files. This is true, for instance, for EasyAnim (seehttp://mecara.fpms.ac.be/EasyDyn/ for details).
In previous versions of MBDyn, the output results statement allowed to generate output compatible
with MSC.ADAMS; provisions for Altair Motion View has been under preparation for long time, but it
has never been truly supported. Anyone interested in that interface should contact MBDyn developers.
The output results statement is now deprecated; support for all visualization tools will be reworked
in form of postprocessing of MBDyn’s raw output, either in textual or binary form. Right now, thatstatement is used to enable the experimental support for NetCDF.
Some post-processing preparation instructions are available for those packages that require special handling and thus are built-in.

D.1

EasyAnim

MBDyn exploits a special version of EasyAnim, based on 1.3 sources and patched by MBDyn developers;
the patch is known to work under UN*X (GNU/Linux, essentially); it has not been tested with Windows,
except with cygwin. It is available from the MBDyn web site, and it has been submitted to EasyAnim
developers for evaluation. Check out MBDyn’s web site for more information.
The preparation of the output is done via awk(1), which is invoked by the mbdyn2easyanim.sh script.
It uses the .log and .mov files, and generates a pair of .vol and .van files which contain the model andthe motion, respectively. Use
mbdyn2easyanim.sh <mbdyn_output_filename>where mbdyn_output_filename is the name of the output file from MBDyn, with no extension. This
script generates a model based on the topology information contained in the mbdyn_output_filename.log
file, plus the animation information according to the contents of the mbdyn_output_filename.mov file.
To check the model during preparation, run MBDyn withabort after: input;
in the problem_name section (page 106), so that the model is output in the input configuration, andEasyAnim can visualize it.
The model can be customized by supplying the mbdyn2easyanim.sh script additional awk(1) codethat adds nodes, edges and sides whose movement is associated to that of existing nodes.
For this purpose, one needs to write an awk(1) script like
325

BEGIN {# add a node property# node prop name, color, radius
nodeprop_add("dummy_node", 4, 1.);# add a node
# node name, base node name, x, y, z in base node frame, prop namenode_add("added_node", "base_node", 1., 2., 3., "dummy_node");# add an edge property# edge prop name, color, radius
edgeprop_add("dummy_edge", 15, 2.);# add an edge
# edge name, node 1 name, node 2 name, prop nameedge_add("added_edge", "node_1", "node_2", "dummy_edge");# add a side property# side prop name, color
sideprop_add("dummy_side", 8);# add a side
nodes[1] = "node_1";
nodes[2] = "node_2";
nodes[3] = "node_3";
nodes[4] = "node_4";# side name, number of nodes, node labels, prop nameside_add("added_side", 4, nodes, "dummy_side");}place it into a file, say custom.awk, and then invoke the interface script as
mbdyn2easyanim.sh -f custom.awk <mbdyn_output_filename>D.2

Output Manipulation

This section notes how output can be manipulated in useful manners.

D.2.1

Output in a Relative Reference Frame

In many cases it may be useful to represent the output of structural nodes in a reference frame relative
to one node. For example, to investigate the deformation of a helicopter rotor, it may be useful to refer
the motion of the blades to the reference frame of the rotor hub, so that the reference rotation of therotor is separated from the local straining.
For this purpose, MBDyn provides an awk(1) script that extracts the desired information from the.mov file.
The script is $SRC/var/abs2rel.awk and is usually installed in $PREFIX/share/awk.
To invoke the script run$ awk -f abs2rel.awk \-v RefNode=<label> \326

[-v RefOnly={0|1}] \[-v InputMode=<imode>] \[-v OutputMode=<omode>] \infile.mov > outfile.mov
It requires the specification of the reference node label, which is given by the RefNode parameter.
The optional parameter RefOnly determines whether the output is transformed in a true reference
frame, or it is simply re-oriented according to the orientation of the reference node.
The command also allows to specify the input and output formats of the orientations, under theassumption that rotations of all nodes are generated with the same format. The optional parameters
imode and omode can be:• euler123 for the Euler-like angles, in degrees, according to the 123 sequence;• euler313 for the Euler-like angles, in degrees, according to the 313 sequence;• euler321 for the Euler-like angles, in degrees, according to the 321 sequence;• vector for the orientation vector, in radians;• matrix for the orientation matrix.
When RefOnly is set to 0 (the default), this script basically computes the configuration of each node
as function of that of the reference one, namely
R′n = RT0 Rn(D.1)

x′n = RT0 (xn − x0 )
ωn′ = RT0 (ωn − ω0 )ẋ′n = RT0 (ẋn − ẋ0 − ω0 × (xn − x0 ))ω̇n′ = RT0 (ω̇n − ω̇0 − ω0 × (ωn − ω0 ))ẍ′n = RT0 (ẍn − ẍ0 − ω̇0 × (xn − x0 ) − ω0 × ω0 × (xn − x0 ) − 2ω0 × (ẋn − ẋ0 ))

(D.2)
(D.3)
(D.4)
(D.5)
(D.6)

where subscript 0 refers to the reference node, subscript n refers to the generic n-th node, and the prime
refers to the relative values. Accelerations are only computed when present in the .mov file for both
nodes.
When RefOnly is set to 1, the script simply re-orients the velocity and the acceleration of each nodewith respect to that of the reference node, namely
R′n = RT0 Rn(D.7)

x′n = RT0 (xn − x0 )
ωn′ = RT0 ωn

(D.8)
(D.9)

ẋ′n = RT0 ẋnω̇n′ = RT0 ω̇n(D.11)

ẍ′n = RT0 ẍn(D.12)

327(D.10)

Appendix E

Log File Format
MBDyn by default writes a file with .log extension that contains generic, one time info about theanalysis and the model.
This file is experimental, since it is mainly intended to be used by external software, like postprocessing tools, to extract or somehow infer information about the model, without the complexity ofparsing the entire input.
It is used, for example, by the script mbdyn2easyanim.sh, along with the corresponding .mov output
file, to generate model files for EasyAnimm, as illustrated in Section D.1.

E.1

Generic Format

The format is typically made of a keyword, starting in the first column, made of alphanumeric chars (mayinclude spaces, though), terminated by a colon, and possibly followed by arbitrary, context-dependentdata. Data may span multiple rows, where a continuation row is marked by a blank in the first column.

E.2

Model Description Entries

Some of the keywords mark model entities, described in the following.

E.2.1

acceleration, velocity

The angular acceleration, the linear acceleration the angular velocity and the linear velocity
joints.
<joint_type>: <label><node_label> (Vec3) <relative_direction><joint_type> ::={ angularacceleration | linearacceleration | angularvelocity |linearvelocity }The relative direction vectors indicate the (not normalized) axis of the imposed acceleration/velocity.
All data are on one line, without continuation.

E.2.2

aero0

The aerodynamic body.
328

aero0: <label> <node_label>(Vec3) <trail_left> (Vec3) <lead_left>(Vec3) <trail_right> (Vec3) <lead_right>
The points are expressed as 3D vectors Vec3, whose origin and orientation is expressed in the reference
frame of the node. All data are on one line, without continuation.

E.2.3

aero2

The two-node aerodynamic beam.
aero2: <label><node_1_label>(Vec3) <trail_left> (Vec3) <lead_left><node_2_label>(Vec3) <trail_right> (Vec3) <lead_right>
The points are expressed as 3D vectors Vec3, whose origin and orientation is expressed in the reference
frame of the respective nodes. All data are on one line, without continuation.

E.2.4

aero3

The three-node aerodynamic beam.
aero3: <label><node_1_label>(Vec3) <trail_left> (Vec3) <lead_left><node_2_label>(Vec3) <trail_center> (Vec3) <lead_center><node_3_label>(Vec3) <trail_right> (Vec3) <lead_right>
The points are expressed as 3D vectors Vec3, whose origin and orientation is expressed in the reference
frame of the respective nodes. All data are on one line, without continuation.

E.2.5

axial rotation

The axialrotation joint
axialrotation: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.6

beam2

The two-node beam.
beam2: <label><node_1_label> (Vec3) <offset_1><node_2_label> (Vec3) <offset_2>
329

The beam label is followed by the label and the offset of each node. All data are on one line, without
continuation.

E.2.7

beam3

The three-node beam.
beam3: <label><node_1_label> (Vec3) <offset_1><node_2_label> (Vec3) <offset_2><node_3_label> (Vec3) <offset_3>
The beam label is followed by the label and the offset of each node. All data are on one line, without
continuation.

E.2.8

body

The body element.
body: <label><node_label>(real) <mass>(Vec3) <x_cg>(Mat3x3) <J>
The x_cg vector indicates the location of the center of mass with respect to the reference frame of therespective node. The J matrix is the inertia matrix.

E.2.9

beam slider

The beam slider joint.
<beamslider>: <label><slider_node_label>(Vec3) <relative_offset>(Mat3x3) <relative_orientation><beam_number><3_node_beam_1>(Vec3) <first_node_offset>(Mat3x3) <first_node_orientation>(Vec3) <mid_node_offset>(Mat3x3) <mid_node_orientation>(Vec3) <end_node_offset>(Mat3x3) <end_node_orientation>[...]
All data on one line, without continuation.

E.2.10brake

The brake joint

330

brake: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.11clamp

The clamp joint
clamp: <label><node_label> (Vec3) <position> (Mat3x3) <orientation><node_label> (Vec3) <position> (Mat3x3) <orientation>
The format is quite obscure; the position and the orientation are repeated twice. Moreover, theposition is always a vector of zeros, and the orientation is the identity matrix. Basically, the locationof the clamp is assumed to be that of the node. All data are on one line, without continuation.

E.2.12deformable joints

The deformable hinge, the deformable displacement joint and the deformable joint, including
the invariant versions, where defined<joint_type>: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2><joint_type> ::=[ invariant ] deformable { hinge | [ displacement ] joint }The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.13

distance

The distance joint
distance: <label><node_1_label> (Vec3) <offset_1><node_2_label> (Vec3) <offset_2>
The label of the joint, followed by the label of each node and the offset of the respective joint extremity,in the reference frame of the node. All data are on one line, without continuation. Both distance anddistance with offset joints are logged in this form.

E.2.14drive displacement

The drive displacement joint331

drivedisplacement: <label><node_1_label> (Vec3) <offset_1><node_2_label> (Vec3) <offset_2>
All data in one line, without continuation.

E.2.15drive displacement pin

The drive displacement pin joint
drivedisplacementpin: <label><node_1_label> (Vec3) <offset_1>(Vec3) <position>
All data in one line, without continuation.

E.2.16

gimbal rotation

The gimbal rotation joint
gimbalrotation: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.17

inline

The inline joint
inline: <label><node_1_label> (Vec3)<position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3)<position_2> (Mat3x3) <orientation_2>
The label of the joint, followed by the label of the node that carries the reference line, the reference
point position_1 on the line and the orientation orientation_1 of the line, such that axis 3 is alignedwith the line. The second node label and the position of the point on the plane follow; orientation_2
is the identity matrix. All data are on one line, without continuation.

E.2.18inplaneThe inplane joint
inplane: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The label of the joint, followed by the label of the node that carries the reference plane, the reference
point position_1 on the plane and the orientation orientation_1 of the plane, such that axis 3 is normal
to the plane. The second node label and the position of the point on the plane follow; orientation_2
is the identity matrix. All data are on one line, without continuation.

332

E.2.19

prismatic

The prismatic joint
prismatic: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors are zero, while the orientation_* matrices indicate the orientation of the joint
in the reference frame of the respective nodes. All data are on one line, without continuation.

E.2.20relative frame structural node

The relative frame variant of dummy structural nodes is logged separately, as it cannot be intermixed
with regular structural nodes and the offset variant of dummy structural nodes. The syntax is the sameof the structural node (Section E.2.27), namely
relative frame structural node: <label> (Vec3) <X> <orientation_description>

E.2.21revolute hinge

The revolute hinge joint
revolutehinge: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.22

revolute rotation

The revolute rotation joint
revoluterotation: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.23rod

The rod joint
rod: <label><node_1_label> (Vec3) <offset_1><node_2_label> (Vec3) <offset_2>
The label of the joint, followed by the label of each node and the offset of the respective joint extremity,in the reference frame of the node. All data are on one line, without continuation. Both rod and rod
with offset joints are logged in this form.
333E.2.24spherical hinge

The spherical hinge joint
sphericalhinge: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.25spherical pin

The spherical pin joint
sphericalpin: <label><node_label> (Vec3) <position> (Mat3x3) <orientation><node_label> (Vec3) <position> (Mat3x3) <orientation>
The format is quite obscure; the position and the orientation are repeated twice. The vector positionindicates the location of the joint, while the matrix orientation is the identity matrix. All data are on
one line, without continuation.

E.2.26

structural forces

The structural forces elements<force_type>: <force_label><node1_label> (Vec3)<arm1>[ <node2_label> (Vec3)<arm2> ]<force_type> ::= structural [ internal ] { absolute | follower } { force | couple }When internal is present node2_label and arm2 must be present as well, otherwise they must be
omitted.

E.2.27structural node

The structural node
structural node: <label> (Vec3) <X> <orientation_description><orientation_description> ::={ euler123 (Vec3) <euler123_angles>| euler313 (Vec3) <euler313_angles>| euler321 (Vec3) <euler321_angles>| phi (Vec3) <orientation_vector>| mat (Mat3x3) <orientation_matrix> }The label of the node, the position X and the orientation parameters that express the orientation are
given. When orientation is any of euler* parametrizations, the angles are in degrees.

334E.2.28

total joint

The total joint
total joint: <label><node_1_label>(Vec3) <relative_offset_1>(Mat3x3) <rel_pos_orientation_1>(Mat3x3) <rel_rot_orientation_1><node_2_label>(Vec3) <relative_offset_2>(Mat3x3) <rel_pos_orientation_2>(Mat3x3) <rel_rot_orientation_2>(bool) <position_status_1>(bool) <position_status_2>(bool) <position_status_3>(bool) <velocity_status_1>(bool) <velocity_status_2>(bool) <velocity_status_3>(bool) <orientation_status_1>(bool) <orientation_status_2>(bool) <orientation_status_3>(bool) <angular_velocity_status_1>(bool) <angular_velocity_status_2>(bool) <angular_velocity_status_3>
All data on one line, without continuation.

E.2.29

total pin joint

The total pin joint
total joint: <label><node_label>(Vec3) <relative_offset>(Mat3x3) <rel_pos_orientation>(Mat3x3) <rel_rot_orientation>(Vec3) <absolute_position>(Mat3x3) <abs_pos_orientation>(Mat3x3) <abs_rot_orientation>(bool) <position_status_1>(bool) <position_status_2>(bool) <position_status_3>(bool) <velocity_status_1>(bool) <velocity_status_2>(bool) <velocity_status_3>(bool) <orientation_status_1>(bool) <orientation_status_2>(bool) <orientation_status_3>(bool) <angular_velocity_status_1>(bool) <angular_velocity_status_2>(bool) <angular_velocity_status_3>
335All data on one line, without continuation.

E.2.30universal hinge

The universal hinge joint
universalhinge: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors indicates the location of the joint in the reference frame of the respective node,
while the orientation_* matrices indicate the orientation of the joint in the reference frame of therespective node. All data are on one line, without continuation.

E.2.31

universal pin

The universal pin joint
universalpin: <label><node_label> (Vec3) <position> (Mat3x3) <orientation><node_label> (Vec3) <relative_position> (Mat3x3) <relative_orientation>
The position vector and the orientation matrix indicate the location and the orientation of the joint in
the global reference frame, while the relative_position vector and the relative_orientation matrix
indicate the location and the orientation of the joint in the reference frame of the node. All data are on
one line, without continuation.

E.2.32

universal rotation

The universal rotation joint
universalrotation: <label><node_1_label> (Vec3) <position_1> (Mat3x3) <orientation_1><node_2_label> (Vec3) <position_2> (Mat3x3) <orientation_2>
The position_* vectors are zero, while the orientation_* matrices indicate the orientation of the joint
in the reference frame of the respective node. All data are on one line, without continuation.

E.3

Analysis Description Entries

Some of the keywords mark analysis entities, described in the following.

E.3.1

inertia

An aggregate inertia.
inertia: <label> (<name>)mass:(real) <mass>J:(Mat3x3) <J>
Xcg:(Vec3) <x_cg>
Jcg:(Mat3x3) <J_cg>
Vcg:(Vec3) <v_cg>
336

Wcg:
(Vec3) <omega_cg>
Xcg-X:(Vec3) <relative_x_cg>
R^T*(Xcg-X): (Vec3) <relative_orientation_x_cg>
Rp:(Vec3) <principal_axes_orientation_matrix>
Thetap:(Vec3) <principal_axes_orientation_vector>
Jp:(Mat3x3) <principal_inertia_matrix_cg>

E.3.2

output frequency

An indication of how often output occurs with respect to time steps.
output frequency: <how_often>
where how_often can be:• custom if the output is specially crafted by the output meter statement (Section 5.2.7);• a positive integer if the output occurs every how_often time steps, as dictated by the output
frequency statement (Section 5.2.6).

E.3.3

struct node dofs

The list of structural nodes (excluding dummy nodes).
struct node dofs: <idx> [...]
where idx is the off-by-one index of the location of the first state associated to a node (for example,
X(idx + i), with i = 1, 2, 3, is the component of the position along axis i).

E.3.4

struct node momentum dofs

The list of structural nodes (excluding static and dummy nodes).
struct node momentum dofs: <idx> [...]
where idx is the off-by-one index of the location of the first state associated to a node’s momentum andmomenta moment (for example, X(idx + i), with i = 1, 2, 3, is the component of the position along axis
i).

E.3.5

struct node labels

The list of structural nodes labels (excluding dummy nodes).
struct node label: <label> [...]

E.4

Output Elements

E.4.1

RTAI stream output

The stream output element in case an RTAI mailbox is used:337

outputelement: <label>stream
RTAI(string) <stream_name>(string) <host>(string) <name>(bool) <create>{ values | motion }<content>
The create flag can take 1 or 0 value. The content formatting is specified in section E.4.4. All data in
one line, without continuation.

E.4.2

INET socket stream output

the stream output element in case an INET socket is used:
outputelement: <label>streamINET(string) <stream_name>(string) <host>(integer) <port>{ tcp | udp }(bool) <create>(bool) <signal>(bool) <blocking>(bool) <send_first>(bool) <abort_if_broken>(integer) <output_frequency>{ values | motion }<content>
The content formatting is specified in section E.4.4. All data in one line, without continuation.

E.4.3

local socket stream output

the stream output element in case an local socket is used:
outputelement: <label>streamUNIX(string) <path>{ tcp | udp }(string) <stream_name>(bool) <create>(bool) <signal>(bool) <blocking>(bool) <send_first>(bool) <abort_if_broken>(integer) <output_frequency>338

{ values | motion }<content>
The content formatting is specified in section E.4.4. All data in one line, without continuation.

E.4.4

output element content

The content of a stream output element. In case of output of type values<content>::<values> (integer) <num_channels>
While in case of output of type motion<content>::<motion>(integer) <num_nodes>(bool) <position_output_flag>(bool) <orientation_matrix_output_flag>(bool) <orientation_matrix_transpose_output_flag>(bool) <velocity_output_flag>(bool) <angular_velocity_output_flag>
All data in one line, without continuation.

E.5

File drivers

E.5.1

INET socket stream file driver

The stream file driver in case an INET socket is used:
filedriver:<label>streamINET(string) <stream_name>(string) <host>(integer) <port>{ tcp | udp }(bool) <create>(bool) <signal>(bool) <blocking>(integer) <input_frequency>(bool) <receive_first>(real) <timeout>(integer) <columns_number>(real) <initial_value_1>(real) <initial_value_2>
[...]

339

Appendix F

Frequently Asked Questions
This section contains answers to frequently asked questions related to input and output formatting, andexecution control. It is an attempt to fill the knowledge gap between the user’s needs and the descriptionof each input statement. In fact, this manual assumes that the user already knows what statement isrequired to solve a given problem or to model a given system, so that all it is missing is the details about
the syntax. This is typically not true, especially for inexperienced users, whose main problem consists
in understanding how to solve a problem, or model a system. Of course an input manual is not theright document to start with but, better than nothing, this section is trying to fill this gap, allowing toapproach the manual “the other way round”.
If one’s question is listed below, then it’s likely that the answer will point to reading the right sectionsof the manual.

F.1

Input

F.1.1

What is the exact syntax of element X ?

The exact syntax of each input card is illustrated in the input manual.
The input manual is regularly updated, but omissions may occur, and outdated stuff and bugs may
always slip in. Please feel free to notify errors and submit patches, if you think there is anything wrong
in it, using the mbdyn-users@mbdyn.org mailing list (you need to subscribe first; instructions can beobtained on the website http://www.aero.polimi.it/mbdyn/).

F.1.2

What element should I use to model Y ?

To answer this question, the complement of the input manual, namely a modeling manual, is required. Unfortunately, such document does not exist, and it is not even foreseen. Right now, modelingstyle and capabilities are grossly addressed in the tutorials; for specific needs you should ask on the
mbdyn-users@mbdyn.org mailing list (you need to subscribe first; instructions can be obtained on the
web site http://www.aero.polimi.it/mbdyn/).

340

F.2

OutputF.2.1

How can I reduce the amount of output?

There are different possibilities: one can only output a portion of the results, or produce output only at
selected time steps, or both.
To selectively produce output there are different means:• by category: use the default output statement (Section 5.2.5) to indicate what entities should
be output. By default, all entities output data, so the suggested use is:default output: none, structural nodes, beams;
so that the first value, none, turns all output off, while the following values re-enable the desired
ones only.
• entity by entity, directly: all entities allow an output specification as the last argument (nodes:
Section 6; elements: Section 8); so, at the end of an entity’s card just put..., output, no;..., output, yes;

# to disable output# to enable output• entity by entity, deferred: all entities allow to re-enable output after they have been instantiatedby using the output statement (nodes: Section 6.6.1; elements: Section 8.17.4).
So a typical strategy is:• use default output to select those types that must be on or off; also disable the types of thoseentities that must be partially on and partially off;
• use the direct option to respectively set the output of those entities that must be absolutely on or
off; this overrides the default output value.
• use the output statement to enable the output of those entities that must be on for that simulation
only; this overrides both the default output and the direct values.
The direct option goes in the model, so it may be hidden in an include file of a component that is usedin different models; its value should not be modified directly. On the contrary, the output statement canappear anywhere inside the node/element blocks, so the same subcomponents can have different output
behavior by using different output statements.
Example.
# ...
begin: control data;
default output: none, joints;
structural nodes: 2;
joints: 2;
end: control data;
begin: nodes;
structural: 1, static,null, eye, null, null,
output, no; # this is the ground; never output it341

structural: 2, dynamic,
null, eye, null, null;# defer decision about output# uncomment to output# output: structural, 2;
end: nodes;
begin: elements;
joint: 1, clamp, 1, node, node,
output, no; # this is the ground; never output it
joint: 2, revolute hinge,
1, null,hinge, eye,2, null,hinge, eye;# this is output by "default output"# make sure that no matter what "default output"# is set, this joint is output
output: joint, 2;
end: elements;
To reduce output in time, one can use the output meter statement (Section 5.2.7). It consists in adrive that causes output to be produced only when its value is not 0.
For example, to produce output only after a certain time, use
output meter: string, "Time > 10.";
to produce output every 5 time steps starting from 0., use
output meter: meter, 0., forever, steps, 5;
to produce output only when a certain variable reaches a certain value, use
output meter: string, "Omega > 99.";
if Omega is the third component of the angular velocity of a certain node (say, node 1000), later on, after
the node is defined, the related definition must appear:
set: "[dof,Omega,1000,structural,6,differential]
i.e. the sixth component of the derivative state of node 1000, the angular velocity about axis 3, is assigned
to the variable Omega. Any time Omega is evaluated in a string expression, its value gets updated.

F.3

Execution Debugging

F.3.1

How can I find out why the iterative solution of a nonlinear problem
does not converge?

One needs to:
1. find out the equations whose residual does not converge to zero.
The residual is printed using the statement342

output: residual;
in the problem control block described in Section 4.1.4 of Chapter 4. Each coefficient is precededby its number and followed by a brief description of which node/element instantiated the equation
and what its purpose is, if available; for example, the output
Eq
Eq
Eq
Eq
Eq
Eq
Eq
Eq
Eq
Eq
Eq
Eq

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:

0 ModalStructNode(1): linear velocity definition vx
0 ModalStructNode(1): linear velocity definition vy
0 ModalStructNode(1): linear velocity definition vz
0 ModalStructNode(1): angular velocity definition wx
0 ModalStructNode(1): angular velocity definition wy
0 ModalStructNode(1): angular velocity definition wz
0 ModalStructNode(1): force equilibrium Fx
0 ModalStructNode(1): force equilibrium Fy
0 ModalStructNode(1): force equilibrium Fz
0 ModalStructNode(1): moment equilibrium Mx
0 ModalStructNode(1): moment equilibrium My
0 ModalStructNode(1): moment equilibrium Mz

corresponds to a residual whose first 12 equations refer to a modal node labeled “1” (and the residualis exactly zero);
2. find out who instantiated the offending equation or equations.
If this is not already indicated in the previously mentioned description, one should look up theoffending equation index in the output originated by adding the statement
print: equation description;in the control data block, as described in Section 5.2.2. In the above example, it would generate
Structural(1): 12 1->12
1->3: linear velocity definition [vx,vy,vz]
4->6: angular velocity definition [wx,wy,wz]
7->9: force equilibrium [Fx,Fy,Fz]
10->12: moment equilibrium [Mx,My,Mz]
3. find out who could contribute to that equation or equations.
If the equation was instantiated by a node, one should look at the elements connected to that node.
This information is obtained by adding the statement
print: node connection;in the control data block, as described in Section 5.2.2. In the above example, it would generate
Structural(1) connected to
Joint(1)Joint(2)so one should try to find out which of the connected elements is generating the offending contribution to that equation.
If the equation was instantiated by an element, usually the element itself is the sole contributor tothat equation.

343

Bibliography[1] David J. Laino and A. Craig Hansen. User’s guide to the wind turbine aerodynamics computer
software AeroDyn. Technical report, NREL, 2002. Version 12.50.
[2] Pierre Dupont, Vincent Hayward, Brian Armstrong, and Friedhelm Altpeter. Single state elastoplastic friction models. IEEE Transactions on Automatic Control, June 2002.
[3] John C. Houbolt and George W. Brooks. Differential equations of motion for combined flapwise
bending, chordwise bending, and torsion of twisted nonuniform rotor blades. TN 3905, NACA, 1957.
Updated in 1975.
[4] Marco Borri and Teodoro Merlini. A large displacement formulation for anisotropic beam analysis.
Meccanica, 21:30–37, 1986.
[5] Pierangelo Masarati, Massimiliano Lanz, and Paolo Mantegazza. Multistep integration of ordinary,
stiff and differential-algebraic problems for multibody dynamics applications. In XVI Congresso
Nazionale AIDAA, pages 71.1–10, Palermo, 24–28 Settembre 2001.
[6] William H. Press, Saul A. Teukolsky, William T. Vetterling, and Brian P. Flannery. Numerical
Recipes in C. Cambridge University Press, second edition, 1992.
[7] C.T. Kelley. Iterative methods for linear and nonlinear equations. SIAM, Philadelphia, PA, 1995.
[8] P. Masarati. Direct eigenanalysis of constrained system dynamics. Proc. IMech. E Part K: J.
Multi-body Dynamics, 223(4):335–342, 2009. doi:10.1243/14644193JMBD211.
[9] Marco Morandini and Paolo Mantegazza. Using dense storage to solve small sparse linear systems.
ACM Trans. Math. Softw., 33(1, Article 5), March 2007. doi:10.1145/1206040.1206045.
[10] G. Pasinetti and Paolo Mantegazza. A single finite states modeling of the unsteady aerodynamic
forces related to structural motions and gusts. AIAA Journal, 37(5):604–612, May 1999.
[11] I.C. Cheeseman and N.E. Bennett. The effect of ground on a helicopter rotor in forward flight. TR
3021, NASA, 1955.
[12] Dale M. Pitt and David A. Peters. Theoretical prediction of dynamic-inflow derivatives. Vertica,
5:21–34, 1981.
[13] Gian Luca Ghiringhelli, Pierangelo Masarati, and Paolo Mantegazza. A multi-body implementationof finite volume beams. AIAA Journal, 38(1):131–138, January 2000.
[14] Dewey H. Hodges. Review of composite rotor blade modeling. AIAA Journal, 28(3):561–565, March
1990.

344

[15] Vittorio Giavotto, Marco Borri, Paolo Mantegazza, Gian Luca Ghiringhelli, V. Caramaschi, G. C.
Maffioli, and F. Mussi. Anisotropic beam theory and applications. Computers & Structures, 16(1–4):403–413, 1983.
[16] Pierangelo Masarati. On the semi-analytical solution of beams subjected to distributed loads. In
XVI Congresso Nazionale AIDAA, pages 72.1–10, Palermo, 24–28 Settembre 2001.
[17] David A. Peters, Mnaouar ChouChane, and Mark Fulton. Helicopter trim with flap-lag-torsion andstall by an optimized controller. J. of Guidance, Control, and Dynamics, 13(5):824–834, SeptemberOctober 1990.
[18] Stefania Gualdi, Marco Morandini, and Pierangelo Masarati. A deformable slider joint for multibody applications. In XVII Congresso Nazionale AIDAA, Rome, Italy, September 15–19 2003.
http://mbdyn.aero.polimi.it/˜masarati/Publications/SliderAIDA A2003.pdf.
[19] Pierangelo Masarati and Marco Morandini. An ideal homokinetic joint formulation for generalpurpose multibody real-time simulation. Multibody System Dynamics, 20(3):251–270, October 2008.
doi:10.1007/s11044-008-9112-8.
[20] A. Fumagalli, P. Masarati, M. Morandini, and P. Mantegazza. Control constraint realization for
multibody systems. J. of Computational and Nonlinear Dynamics, 6(1):011002 (8 pages), January
2011. doi:10.1115/1.4002087.
[21] Pierangelo Masarati. A formulation of kinematic constraints imposed by kinematic pairs using
relative pose in vector form. Multibody System Dynamics, 29(2):119–137, 2013. doi:10.1007/s11044012-9320-0.
[22] Wojciech Witkowski. 4-node combined shell element with semi-EAS-ANS strain interpolations in 6parameter shell theories with drilling degrees of freedom. Computational Mechanics, 43(2):307–319,
2009. doi:10.1007/s00466-008-0307-x.
[23] P. Flores, M. Machado, M. T. Silva, and J. M. Martins. On the continuous contact force models
for soft materials in multibody dynamics. Multibody System Dynamics, 25(3):357–375, March 2011.
doi:10.1007/s11044-010-9237-4.
[24] K. H. Hunt and F. R. E. Crossley. Coefficient of restitution interpreted as damping in vibroimpact.
Journal of Applied Mechanics, Transactions ASME, 42(2):440–445, 1975. doi:10.1115/1.3423596.
[25] Hamid M. Lankarani and Parviz E. Nikravesh. Continuous contact force models for impact analysis
in multibody systems. Nonlinear Dynamics, 5(2):193–207, 1994. doi:10.1007/BF00045676.
[26] E. Pennestrı̀, R. Stefanelli, P. P. Valentini, and L. Vita. Virtual musculo-skeletal model forthe biomechanical analysis of the upper limb. Journal of Biomechanics, 40(6):1350–1361, 2007.
doi:10.1016/j.jbiomech.2006.05.013.
[27] The NetCDF Users Guide, June 2006. NetCDF Version 3.6.1.

345