Coming from FreeDyn¶

freedyn2 is the successor of the FreeDyn freeware. If you have worked with the legacy FreeDyn binaries, unpacked into a folder, this page says what changes, what stays, and how to run your existing .fds models in freedyn2.

What changes¶

legacy FreeDyn	freedyn2
binaries downloaded and unpacked into a folder	one installer (`freedyn2-setup.exe`), or `pip` / `uv` (Getting started)
model files in `.fds`	YAML model files (the model file); `.fds` files keep working
result files next to the model	one CSV file per run, one column per channel
	the app window and the viewer: 3D view, plots, checks, tuning, runs side by side
	the command line: `freedyn2 run`, `view`, `check`, `convert`
	an assistant can build, run and examine models
Euler-parameter bodies, the Negrut form of HHT	Lie group bodies, the Arnold–Brüls form of HHT; the legacy algorithms on request (`--profile legacy`)

Your .fds files keep working. freedyn2 run, freedyn2 view and freedyn2 check read them as they are. By default freedyn2 solves them with its own methods, with the step size control keeping the model's GlobalErrorTolerance and SolverMaxTimeStep. With --profile legacy it uses the legacy algorithms instead (Euler-parameter bodies, Negrut HHT, the legacy Newton rule and step size control): then both programs take the same steps and agree to round-off.

The importer reads the blocks freedyn2 supports: Body Rigid_EulerParameter_PAI, Constraint Generic, Constraint TimeMotion, Force Gravity, Force GenericForce and GenericTorque, Measure Translational and Rotational, DataObject Parameter and Spline_1D, Simulation Dynamic, Solver HHT and HHT_Negrut. Any other block is rejected with its name, so a model is never simulated with parts missing.

Side by side¶

freedyn2 and legacy FreeDyn can stay on the same machine. The installer installs for the current user into its own folder, with its own Python, and does not touch the folder of the legacy FreeDyn. The component associate .fds is off by default, so what opens .fds files now keeps opening them; switch it on if a double click should open freedyn2.

A first session with an existing model¶

Install freedyn2 (Getting started) and open freedyn2 Command Prompt from the start menu (or any prompt, if freedyn2 is on the PATH).
Go to the folder of your model. freedyn2 does not change the .fds file; run writes its results as a CSV next to it.
```
cd C:\models\crank
```
Check it. This reads the model, reports blocks the importer does not support, and lists what it finds: degrees of freedom, total mass, likely slips.
```
freedyn2 check crank.fds
```
Run it with the legacy algorithms; the results should be those of legacy FreeDyn.
```
freedyn2 run crank.fds --profile legacy -o crank_legacy.csv
```
Run it with freedyn2's methods (the default) and look at it:
```
freedyn2 run crank.fds -o crank_v2.csv
freedyn2 view crank.fds
```
The viewer (or freedyn2 gui crank.fds for the app window) shows the bodies as boxes of their mass and inertia, as an .fds has no geometry, plays the results and plots the channels. freedyn2 view crank.fds crank_legacy.csv shows the results of the legacy run.
Compare the two runs. They differ by the accuracy of the methods, usually little; where they differ much, read the findings (fast rotors, alpha = 0, angle measures).

Bodies and joints keep the names of the .fds (BodyName, Name of a constraint), so the channels are crank.R_x, crank.omega_z and so on.

Moving a model to YAML¶

freedyn2 convert writes an .fds model as a YAML model file:

freedyn2 convert crank.fds                     # crank.yaml, freedyn2 methods (profile v2)
freedyn2 convert crank.fds -o crank_legacy.yaml --profile legacy

The YAML file is the model the importer reads from the .fds, in the order of the .fds, with comments naming the blocks (BodyID, ConstraintID, …). It carries the solver settings of the profile – the step size control of legacy FreeDyn (adaptive, eps, step as the largest step) and, with --profile legacy, the Euler-parameter bodies, the Negrut form of HHT and the legacy Newton rule – so freedyn2 run crank.yaml gives the results of freedyn2 run crank.fds with that profile (bitwise or to round-off; checked for every comparison model). Spline data files stay where they are, referenced relative to the YAML file. Joints, named by their ConstraintID in an .fds, get names that are identifiers (joint_1), and so do their channels. Details: command line; from Python freedyn2.convert and Model.to_yaml (Python API).

From there the model is a YAML file like any other: add shapes for the viewer, replace expression forces by library forces, give points names, set solver to a fixed step (remove adaptive and eps, choose step) for real-time use. For reference, how the concepts map:

`.fds`	YAML
`Body Rigid_EulerParameter_PAI`: `Mass`, `Inertia`, `LocationCenterMass`, `OrientationPAI`	`bodies`: `mass`, `inertia`, `position`, `orientation` (a quaternion instead of the rotation matrix)
`InitialVelocityVector`, `InitialOmegaVector` (global)	`velocity`, `angular_velocity` of the body
`Constraint Generic` with `dxFixed` … `azFixed`	`joints`: `revolute`, `prismatic`, `spherical`, … or `generic` with the directions to fix
`Constraint TimeMotion`	`drivers`
`Measure Translational` / `Rotational`	`measures`
`Force GenericForce` / `GenericTorque` with `ForceExpression`	`expression_force`, `expression_torque`
`DataObject Parameter`	`parameters`, usable as `=formulas` in any field
`DataObject Spline_1D`	`splines`
`Simulation Dynamic`, `Solver HHT`	`solver`: `end_time`, `output_step`, `alpha`; the step size control as `adaptive`, `eps` (`GlobalErrorTolerance`), `step` (`SolverMaxTimeStep`), `h_min`
`RegardVelocityInertiaForcesInsideJacobian`, `ModifyNewmark`	`jacobian`, `newmark` of the bodies (`--profile legacy`)

What YAML adds: library forces (spring-damper, torsion spring, bushing) that need no C compiler, tires and roads, shapes for the viewer, named points and frames, references in a checks section, sensors and runtime inputs.

After changing the YAML, run it and the .fds and compare the channels of the two CSV files (in a script or a spreadsheet), or let an assistant compare them. A checks section in the YAML with values from the .fds run keeps the comparison with every later change.

Differences in results¶

freedyn2 solves the same physics with other methods, so its results differ from legacy FreeDyn by the accuracy of both. On the 14 comparison models freedyn2 is as accurate or more accurate, and its simulation 2.5 to 19 times faster. The largest differences:

Fast rotors: with Euler parameters, HHT damping slows a freely spinning body down (at 300 rad/s and h = 1 ms by more than half in one second); the legacy ModifyNewmark option removes most of that. freedyn2's Lie group body has no such loss.
alpha = 0 with joints is unstable in both programs; a little numerical damping (alpha = -0.01) removes it.
Line of sight forces between a body and the ground point the other way in legacy FreeDyn; the importer corrects the sign, so the forces are the same.
Angle measures count revolutions in both; they agree as long as an angle changes by less than π per step.

All of them, with numbers: Numerical findings. How the two programs were compared (two levels: equal to round-off with --profile legacy, against independent references with the default): the sections Comparison with legacy FreeDyn and Legacy FreeDyn against freedyn2 of the README.

`freedyn2 compare`¶

freedyn2 compare model.fds --legacy <path of the legacy FreeDyn solver> [--markdown report.md]

runs both programs on the same .fds and reports accuracy (against a converged solution both compute themselves) and times. It is a tool for verification: it needs a checkout of the freedyn2 repository (its legacy/ folder) and the command-line solver of legacy FreeDyn (on Linux built with legacy/build_legacy.py, see legacy/README.md). For running your models you do not need it.