Skip to content

Mass-Spring-Damper

This is the introductory example: a mass-spring-damper (a linear 2nd-order system) tracking a constant position target. The same problem is implemented in both C++ and Python, so you can learn one workflow and choose the interface that best matches your application.

Example Files

  • examples/sim.cpp
  • examples/sim.py
  • examples/plot_sim.py

sim.cpp and sim.py were designed to be near-exact translations of each other; they both run the simple mass-spring-damper sim and print the location of the saved log file. The log file is saved to the same location, so running plot_sim.py works after running either the C++ or Python versions of the sim.

The C++ version of affine_mpc does not come with plotting capabilities. It is designed to log .npz files that can be loaded in Python with affine_mpc.load_log(). Since Python can natively plot the logged results, the only difference between the two sim versions is that sim.py can also plot the results (python examples/sim.py --plot, or affine-mpc-example-msd --plot when installed with pip).

What the Example Demonstrates

  • Building a linear interpolation parameterization
  • Configuring an MPC (condensed formulation)
  • Setting model, limits, weights, and references
  • Solving in a closed loop
  • Logging outputs with MPCLogger
  • Loading and plotting the resulting .npz log from Python

Run the Example

The simulation can be run from either interface, but visualization is currently supported from Python only.

Core Example Structure

The two implementations follow the same steps:

  1. Define the model dimensions
  2. Choose a Parameterization and Options
  3. Construct MPC with Formulation::Condensed (Formulation.Condensed in Python)
  4. Set model, limits, weights, and references
  5. Call initializeSolver()
  6. Solve in a loop
  7. Retrieve the next input and propagate the system
  8. Log the results

What the Example Produces

The example writes output into the system temp directory under ampc_example, replacing the log of any earlier run (from either interface).

The two outputs are:

  • log.npz
  • log_params.yaml

The controller tracks a constant position target for the mass-spring-damper system. The logger records both the realized trajectory and selected predictions. Logs produced by either interface can be visualized with the Python plotting workflow described in Python Getting Started.

The plot shows:

  • Actual state history
  • Reference state history
  • Applied input
  • Optional input reference if input cost is enabled
  • Selected prediction rollouts over time
  • Solve times

Suggested First Modifications

If you are new to the library, try changing:

  • Prediction horizon T
  • Number of control points
  • State weights Q_diag
  • Input cost weight R_diag
  • Input or state limits

This is the fastest way to build intuition for how the parameterization and optional constraints affect behavior.

Relationship to Tests

Many tests use the same small mass-spring-damper system because it is easy to understand and fast to run. The example therefore reflects the same style of problem setup exercised in the unit tests.