MachineModeling

The MachineModeling bundle provides a common foundation for modeling heavy machines such as excavators, bulldozers, wheel loaders and forestry machinery.

It defines reusable concepts like Components, Connections, Actuators, and Bearings, which together form the building blocks of machine models.

Core Concepts

A machine is composed of Components that are assembled using Connections.

• A Component can be either:
  • Primitive – a single physical entity
  • Composite – a higher-level component that internally contains other components and connections

This approach allows models to scale from simple mechanical parts to complete machines while reusing the same abstractions.

Components and Connections

Both Components and Connections can vary in complexity.

Examples

• Connections
  • Connections.Pivot.Hinge – a simple rotational joint
  • Specialized variants:
    • HingedAxle
    • Bearings
    • LockedAxleBearings
• Linear Actuators
  • DistanceMotor
  • Cylinder
  • CylinderBearings

For actuator variants that require specific attachment behavior, matching connections are provided.
For example:

• Actuators.Linear.CylinderBearings
• Actuators.Linear.Connections.CylinderBearings

These connections ensure the actuator is attached correctly to the mechanical system.

Naming Convention

Types are organized so their purpose is clear from the namespace alone.

Example:

• A linear cylinder actuator is located at: Actuators.Linear.Cylinder

Base Types

When multiple implementations exist within the same namespace, a common base type named Base is required.

Example:

Required attributes:

min_length is Real stroke_length is Real source is Physics.Interactions.Interaction

- `min_length` – the actuator’s minimum length  
- `stroke_length` – maximum extension from `min_length`  
- `source` – abstraction for the actuation mechanism (e.g. distance motor, force motor, or hydraulic system)

---

## Traits

Traits are used to share common attribute definitions between multiple models.

### Guidelines

- Traits should be placed in a `Traits` folder
- The `Traits` folder should be located alongside the models that use them

### Example: Bearings Trait

Namespace:

Connections.Pivot.Traits

trait Bearings: hinge.enabled: false bearing_collision_group is Simulation.CollisionGroup: systems: [from_bearings, to_bearings]

disable_bearings is Simulation.DisableCollisionPair:
    group1: bearing_collision_group
    group2: bearing_collision_group

from_bearings is MachineModeling.Bearings.Pair reference
to_bearings   is MachineModeling.Bearings.Pair reference ```

This trait is reused by:

• Connections.Pivot.Bearings
• Connections.Pivot.AxleBearings

Main Categories

The following categories are automatically inserted into the physics graph when defined in an owning model.
Each instance has a local transform relative to its owner.

Components

Component Types

• Primitive – single Body component
• Composite – component with an arbitrary number of bodies and internal connections

Primitive Components

Composite Components

Connections

The bundle includes a set of generic connections.
For example, pivot connections are located in the Connections.Pivot namespace.

Component-Specific Connections

For clarity and reuse, component-specific connections should be placed in the component’s namespace.

Example:

Actuators.Linear.Cylinder
Actuators.Linear.Connections.Cylinder

Pivot Connections

Pivot connections allow rotation about a single axis.

• Hinge
  • Simplest representation
  • Restricts non-rotation-axis rotation using a moment
• LockedAxleBearings
  • Models four bearings interacting with an axle
  • Produces realistic bearing forces and axle tension
  • Preferred for high-fidelity machine models

Bearings apply forces at physical contact points rather than constraining motion with moments, enabling more accurate simulation.

Bearings

Most heavy machinery uses axle-bearing connections for pivoting joints.
Bearing models capture this behavior and enable realistic load transfer and force computation.

Actuators

Linear Actuators

Actuation Source

Cylinders do not define their actuation source directly.

Instead, one of the following traits must be applied:

• Actuators.Linear.Traits.ForceMotor
• Actuators.Linear.Traits.VelocityMotor

These traits provide the required actuation behavior and can be applied to any cylinder variant.