The model file¶

A model is one YAML file. It names the model, lists bodies, joints and forces, and says how long and with which step to simulate. Everything else is optional.

model: oscillator             # the name of the model (results: oscillator.csv)
gravity: [0, 0, -9.81]
parameters: {k: 200.0, d: 4.0}
bodies:
  mass:
    mass: 1.0
    inertia: [0.01, 0.01, 0.01]
    position: [0, 0, -0.5]
joints:
  slider: {type: prismatic, body1: mass, location: [0, 0, -0.5]}
forces:
  spring:
    type: spring_damper
    body1: mass
    point2: [0, 0, 0]          # on the ground
    stiffness: =k
    damping: =d
solver: {type: HHT, end_time: 2.0, step: 0.001, output_step: 0.01}

Sections¶

key	value
`model` (required)	string
`checks`	object	References the results are checked against (freedyn2 check, the viewer, the MCP server); no effect on the simulation. Tolerances are absolute, in the unit of the channel.
`ground`	object	The fixed ground: shapes for the viewer (frame global).
`gravity`	[x, y, z]	Global gravity acceleration, acting at the centers of mass. Default [0, 0, 0].
`joints`	object
`parameters`	object	Named model parameters, used in force expressions and in formulas: any number of the model may be written as "=expression" of the parameters (e.g. stiffness: =k_susp, position: [0, 0, =h + 0.25]); a parameter may itself be a formula of others (fdgen.formulas).
`outputs`	object	Named output channels: expressions of measures, parameters and inputs (like a force law), written as the channel .value. Measures are not channels themselves; an output makes one (or any law of them) a channel, e.g. for a program that runs the model and reads its outputs. Each expression must use at least one measure.
`inputs`	object	Named runtime inputs with their default values, used in force expressions and driver motions like parameters. Unlike a parameter, the program that runs the model may change an input between two steps (fd::System::set_input; freedyn2_run --input, --inputs): a rider's steering torque, a throttle, a brake pressure. Inside a step an input is constant. Not allowed in formulas (they are evaluated when the model is generated).
`road`	object	Road surface of the tires: analytic (fdgen.tire: height = sum of harmonics + slope, friction mu0 with an optional patch) or an OpenCRG file (crg; evaluated by the runtime, fd::Road).
`splines`	object	Named cubic splines y(x), called like functions in force expressions: name(x).
`drivers`	object	Prescribed motion: the measure (displacement, distance or angle) follows motion(t), a constraint m(q) - f(t) = 0 (model plugin).
`measures`	object	Named scalar measures of the state used in force expressions.
`points`	object	Named points (hardpoints), global at t = 0: wherever a point is given (location, point, point1, point2, position) its name may stand instead of the numbers.
`frames`	object	Named frames, global at t = 0: their name may stand for an orientation (and, in a point field, for the origin).
`sensors`	object	Points whose motion is written as result channels: acceleration and specific force (a - g, what an accelerometer measures), angular velocity and acceleration, from the accelerations the solver computes (no difference quotients). For motion cueing and sensor models; no effect on the simulation.
`forces`	object
`bodies` (required)	object
`solver` (required)	solver

Conventions¶

Units are SI: m, kg, s, N, rad. The checks warn when gravity, lengths or masses look like another unit system.
Everything is given globally at t = 0: the positions of bodies (their centers of mass), joint locations and frames, the points of springs and forces, the shapes. FreeDyn computes where each sits on its body. You never write a point in a body frame. Points used more than once get a name: hardpoints and frames.
The ground is the fixed frame; it is named ground where a body is expected (body2 of a joint or spring defaults to it).
Names of bodies, joints, forces, measures, parameters, inputs and splines are identifiers (letters, digits, _); they are the prefixes of the result channels (rod.R_z).

Ids¶

Names are for people: the model refers to an element by its name (body1: rod). An element can also carry an id, its stable identity for tools:

bodies:
  upper_arm:
    id: onshape:MqRDHdI8Ht5vR9KbS/MLzm6Pj1fYoxiC1T6
    mass: 1.39
    ...

The id is optional and has no effect on the simulation. It is unique in the model: letters, digits and _ . : / + = -, starting with a letter or digit.
Bodies, joints, forces, measures, sensors, drivers, splines, frames and shapes have the key id. Parameters, inputs, outputs and points are a bare value; for an id they take the long form {value: ..., id: ...}, which means the same as the value alone:

parameters:
  k: {value: 5000, id: fds:parameter:3}       # the same as k: 5000
points:
  pivot: {value: [0, 0, 0], id: onshape:connector:M2}
  tip: {from: pivot, offset: [1, 0, 0], id: my:tip}   # the other forms of a point: id beside
outputs:
  angle: {value: phi * 180 / pi, id: my:angle}

- The importers write it: onshape:... (Coming from Onshape), fds:body:1 for the BodyID of a legacy model. The re-import finds an element by its id, so an element keeps its name in freedyn2 whatever it is called in the CAD system, and a renamed element keeps its id.

Orientations¶

Orientations – of bodies (their principal axes), joint frames, bushing frames, shapes – are unit quaternions [θ0, θ1, θ2, θ3] (Euler parameters, θ0 the scalar part), in global components. They are normalized when read. The ones you need most:

orientation	quaternion
identity (frame axes = global axes)	`[1, 0, 0, 0]`
z axis → global y (a hinge about y)	`[0.7071068, -0.7071068, 0, 0]`
z axis → global x	`[0.7071068, 0, 0.7071068, 0]`
90° about z	`[0.7071068, 0, 0, 0.7071068]`
angle φ about a unit axis n	`[cos(φ/2), n_x sin(φ/2), n_y sin(φ/2), n_z sin(φ/2)]`

With formulas the last row can be written directly, e.g. orientation: [=cos(phi / 2), 0, 0, =sin(phi / 2)] with a parameter phi.

Parameters and formulas¶

parameters are named numbers. Every number of the model may be a formula of them, written with = as in a spreadsheet – no quotes needed in YAML:

parameters: {k_front: 30000, k_rear: =0.8 * k_front, h_mount: 0.55}
forces:
  susp_fl:
    type: spring_damper
    stiffness: =k_front
    point2: [2.6, 0.8, =h_mount]

Formulas use the syntax of the force expressions: + - * / ^, parentheses, sqrt, sin, cos, exp, min, max, pi, …, with the parameters as names.
A parameter may be a formula of other parameters; the order does not matter, a cycle is reported.
A formula is a number fixed when the model is read – not a function of time. Laws in time and state are force expressions, written without =.
Parameters are used in force expressions and drivers by name (force: -k * z).
In the viewer every parameter is a slider; everything written as a formula of it follows.

# starts a comment

stiffness: #k is an empty value in YAML. Formulas start with =; the error message says so if you slip.

Runtime inputs¶

inputs are named numbers that the program running the model may change between two steps: a rider's steering torque, a throttle position, a brake pressure, a set point coming from outside. They are used in force expressions and driver motions by name, like parameters; their value in the model file is the default.

inputs: {T_steer: 0.0, p_brake: 0.0}
forces:
  rider_steering:
    type: expression_torque
    body1: front_frame
    body2: rear_frame
    axis: [-0.407, 0, 0.914]
    frame: body
    torque: T_steer - c_steer * steer_rate

An input is constant inside a step, also inside its Newton iterations; the derivatives of the laws are exact for every value. A step in an input is a step in the force, so the response is first order in the step size around it.
The runtime sets them with fd::System::set_input (C++, architecture); freedyn2 run with --input NAME=VALUE (a constant) or --inputs FILE.csv (over time, command line).
Inputs are not allowed in formulas: a formula is fixed when the model is read.
Names must differ from the parameters and measures. An input no law uses can be set, it has no effect.

Data files¶

Spline tables, .tir tire files, OpenCRG roads, meshes and reference curves are given as paths relative to the model file.