Overview

This document provides practical guidelines for configuring simulation parameters and structuring modular simulation models effectively in CDPSim. Proper configuration significantly impacts simulation accuracy and computational efficiency.

Choosing the Implementation Method: C++, Low-Code, or No-Code

When designing simulation models in CDPSim, selecting the right development method (C++, low-code, or no-code) significantly affects performance, ease of use, and reusability:

• C++ (Code-based)
  • High computational performance and fine-grained control.
  • Best for computationally intensive models or custom numerical integration methods.
  • Requires programming expertise but highly reusable once established. Good tools are provided for autogenerating the code skeleton.
• Low-code (Customizable standard components using scripts)
  • Good balance between ease of use and flexibility.
  • Suitable for moderately complex models composed of standard, reusable building blocks.
  • Easier setup compared to a code-based approach but has a performance overhead.
• No-code (Fully graphical/block-diagram approach)
  • Highest ease of use and accessibility, minimal programming knowledge required.
  • Quick model setup ideal for rapid prototyping or simpler dynamic simulations.
  • Limited performance and customization capability, as complexity grows overhead increases significantly.

General Guidelines

Start Simple

As a guideline, start with an explicit solver and moderate time step for simpler models, but if you observe missed real-time deadlines or wildly oscillating values (numerical instability), you likely need a smaller step or an implicit approach. Also, consider adaptive step solvers if available - they can step small when required by fast dynamics and step larger when things are slow, optimizing performance.

SimPorts - Bulk Connections

If two components exchange multiple signals, prefer grouping them in one SimPort rather than routing each signal individually. This reduces the visual clutter on the Block Diagram and helps keep a clean and consistent interface between components.

In addition, when using SimComponents as containers to structure the component in your project, it is often necessary to forward data from one component to another through multiple levels. In this case, it is recommended to use empty SimPorts as Proxy Ports (read more in the SimPort manual) that can pass data without any processing or delays. This helps to keep the project structure clean and maintainable while avoiding any unnecessary overhead.

Signal Overhead

Every connection in the model introduces some overhead for the simulator to pass data between components. Therefore, one should minimize unnecessary connections, e.g. don't split a component into too many small parts if one would do - for example, don't model a single physical shaft with several tiny sub-components each adding a connection unless performance is not critical and the modularity and reusability benefits outweigh the overhead.

Also, consider merging components if the interface between them is extremely fast or tight. For instance, if you have a tiny sub-component that always works together with another (say a sensor attached to a mass), combining them into one component might save the overhead of a connection without losing modularity in a meaningful way.

In summary, efficient models use compact interfaces and avoid an explosion of internal connections.

Optimize Component Complexity

Each modular component adds some computations (evaluation of differential equations, internal algebra, etc.). To scale up to large models, ensure each component's implementation is as simple as it can be while meeting requirements. Use analytical solutions or approximations where possible instead of extremely fine-grained physics if not needed. For example, if a gearbox's internal flexibility is not critical, don't model every gear tooth - just stick to an ideal ratio with an efficiency loss.

Support Variables and Physical Equivalents

Sometimes introducing support variables or pre-computed equivalents can boost performance. Reflected inertia is a good example: if a heavy load is attached to a motor through a gearbox, the motor "sees" an `"effective inertia" = ("load inertia") * ("gear ratio")^2`

Combine strongly coupled states into a single equivalent state when appropriate.

Balance Component Complexity

Maintain modularity for reusability, but not at the expense of an excessive number of very small components that each have overhead. Measure and optimize performance as you go, and don't hesitate to merge components or simplify the model if it's too slow.

Balance modularity and computational efficiency:

• Use simplified or analytical approximations if sufficient.
• Merge strongly coupled components to reduce overhead without sacrificing modularity.
• Use the SimulatorManager component ProcessTimer signal (see Measuring Performance for details) to monitor the simulation CPU usage and real-time performance as you build the model.

Explicit vs. Implicit Solver Trade-offs

• Explicit solvers require smaller time steps for stiff systems, increasing computational load.
• Implicit solvers allow larger time steps but add computational overhead per step.

Evaluate and select the simplest solver that accurately captures the system dynamics.

Determining the Highest Frequency Component

To select appropriate time step when system frequencies are unknown or variable:

• Use conservative time step estimates if exact values are unknown.
• Perform frequency-domain analysis (FFT) on similar systems if available.
• Document clearly the assumptions and acceptable deviations.

Key Simulation Parameters

The fs and TimeStep are configured in the SimulatorManager component while the tolerances are set in the selected Integration Method (if available). See the Tolerances section in the simulator manual for details.

Modular Component Structure

Each physical component should be encapsulated and parameterized:

• Encapsulate each physical element (motor, gearbox, cylinder) as a reusable CDPSim::DynamicSimComponent subclass.
• Clearly define tunable properties (e.g., motor torque constant, gearbox ratio, hydraulic cylinder dimensions).
• Follow a black-box abstraction approach, exposing only essential ports and interface signals.

Distributed Simulations and Performance Optimization

To manage large-scale simulations effectively:

• Distribute large models (1000+ states) across multiple computational nodes or applications.
• Keep tightly interacting modules (high-frequency state exchange) within the same application or machine to minimize latency and improve numerical stability.
• Regularly use CDPSim's diagnostics (real-time alarms, performance measuring) to guide optimization of solver settings and model structure.

Efficient modular modeling balances accuracy, complexity, and computational demands.

Solver Selection

Key considerations when selecting a solver:

• Solver concept
  • Explicit Solvers (e.g. RungeKutta4): Efficient for moderately complex, non-stiff systems.
  • Implicit Solvers (e.g. SUNDIALS CVODE): Better suited for stiff systems, allowing larger time steps but higher computational overhead per step.
• Adaptiveness: Some solvers can internally estimate the error and automatically adjust the time step for efficiency and accuracy - useful for variable or stiff dynamics.

Find the the full comparison of solvers in the Choosing an Integration Method manual.

Reusability

Best practices for reusable components:

• Model logical elements individually (e.g., separate Motor and Gearbox components).
• Define consistent naming and standard SI units for parameters.
• Avoid hard-coded values; use configurable properties.

Connecting Components with SimPorts

Use standardized port interfaces for seamless connection.

Recommended SimPort Types

• Linear Mechanical Port: Force, velocity, displacement signals.
• Rotational Mechanical Port: Angular velocity, torque, angle signals.
• Hydraulic Port: Pressure and volumetric flow rate.
• Electrical Port: Voltage and current signals.

SimPort Bulk Connections:

• Bundle multiple signals in a SimPort for cleaner connections.
• Group logically related signals for clarity.

Example modular setup (Rotational-Linear mechanical):

• Motor (Electrical & Rotational ports)
• Gearbox (Rotational ports, handles internal ratio)
• Rack & Pinion (Rotational port + Linear port)
• Linear Load (Linear mechanical port)

Example hydraulic setup:

• Accumulator (Hydraulic port)
• Valve (Hydraulic ports: Supply, Return, A, B)
• Cylinder (Two Hydraulic ports, One Linear mechanical port)
• Load (Linear mechanical port)

Units

Accurate simulations require consistent and correct units across all components, ports, and signals. Inconsistent units cause incorrect simulation outcomes, numerical instability, and reduced reusability of modules. Consistent units are essential for accuracy and maintainability. Make sure your components/modules have corresponding units.

Examples of units:

Best Practices for Unit Consistency

• Clearly define and document units within each component and SimPort.
• Avoid mixing units within the same simulation domain; for instance, use only m/s for velocity across all mechanical linear components.
• Perform explicit conversions at input or output interfaces if external data sources or sensors provide values in different units.
• Avoid implicit or undocumented unit conversions, as these often lead to errors or numerical instability.
• Standardize across your entire project or organization — use consistent units in SimPorts to ensure seamless plug-and-play compatibility.

FMI Models

The Functional Mock-up Interface (FMI) is a tool-independent standard for the exchange of simulation models. CDPSim supports importing FMI 2.0 Co-Simulation models, enabling interoperability with other simulation tools. FMI components offer the advantage of reusing validated models from suppliers or third parties. Therefore, consider using FMI models when available. See the FMI Co-Simulation manual for details.

Further Reading

• Nyquist Criterion & Sampling Theory:
  • Shannon, C. E. (1949). Communication in the Presence of Noise. Proceedings of the IRE.
  • Oppenheim, A. V., & Schafer, R. W. (2009). Discrete-Time Signal Processing. Prentice Hall.
• Numerical Integration & Solver Stability:
  • Hairer, E., Nørsett, S. P., & Wanner, G. (1993). Solving Ordinary Differential Equations I: Nonstiff Problems. Springer.
• Modular Modeling & System Decomposition:
  • Karnopp, D. C., Margolis, D. L., & Rosenberg, R. C. (2012). System Dynamics: Modeling, Simulation, and Control of Mechatronic Systems. Wiley.