Skip to content

Home

Jump to bottom
Joaquin edited this page Mar 10, 2026 · 22 revisions

QSS Solver

Table of Contents

  1. Introduction
  2. Installation
  3. Quick Start
  4. MicroModelica Language
  5. Integration Methods
  6. Using the GUI
  7. Command Line Usage
  8. Advanced Features
  9. Troubleshooting
  10. Examples

Introduction

The QSS Solver is a modeling and simulation environment for continuous and hybrid systems, optimized for large-scale model simulation. It provides multiple integration methods and a user-friendly interface for working with models described in μ-Modelica (MicroModelica), a subset of the standard Modelica language.

Key Features

  • Multiple Integration Methods: QSS methods, DASSL, DOPRI, CVODE, IDA
  • Large-Scale Support: Optimized for simulating large models efficiently
  • Hybrid Systems: Handles both continuous and discrete events
  • User-Friendly GUI: Integrated development environment
  • C Code Generation: Automatic generation of optimized simulation code
  • Parallel Computing: Support for distributed simulations

Architecture Overview

The QSS Solver consists of three main components:

  1. MicroModelica Compiler (mmoc): Compiles μ-Modelica models to C code
  2. QSS Engine: Simulation engine with multiple integration methods
  3. QSS GUI: Graphical user interface for model development and simulation

Installation

System Requirements

  • Operating System: Linux (Ubuntu 24.04 recommended)
  • Compiler: GCC with C++ and Fortran support
  • Memory: Minimum 4GB RAM (8GB+ recommended for large models)

Dependencies

Install the required packages on Ubuntu 24.04:

sudo apt update
sudo apt install \
    bison++ cmake g++ gfortran gnuplot \
    libatlas-base-dev libboost1.83-dev libcln-dev \
    libconfig-dev libginac-dev libgsl-dev libmetis-dev \
    libsbml5-dev libscotch-dev libsuitesparse-dev \
    pkgconf python3 qtbase5-dev qtbase5-dev-tools \
    rapidjson-dev

# Install flex-old (required by the compiler)
sudo apt install ${QSS_SOLVER_ROOT}/src/mmoc/3rd-party/flex/flex-old.deb

Build Instructions

  1. Clone or extract the source code:

    cd /path/to/qss-solver/src

  2. Create build directory:

    mkdir build
cd build

  3. Configure with CMake:

    cmake ..

  4. Compile the project:

    make

  5. Install the software:

    sudo make install

The binaries will be installed in the bin directory and libraries in the lib directory.

Quick Start

Your First Model

Create a simple file named simple.mo:

model SimpleModel
  Real x(start = 1.0);
  Real y(start = 0.0);
parameter Real k = 0.1;
equation
  der(x) = -k * x;
  der(y) = x;
end SimpleModel;

Compile and Run

  1. Using the GUI:

    • Launch QSS Solver GUI: qss_solver
    • Open the model file
    • Click "Compile" then "Run"

  2. Using Command Line:

    mmoc simple.mo
make -f simple.make
./simple

View Results

The simulation results are saved in output files that can be plotted with GNUPlot or the built-in plotting tools.

MicroModelica Language

μ-Modelica is a subset of the standard Modelica language optimized for the QSS Solver. It supports:

Basic Model Structure

model ModelName
  // Declarations
  Real x(start = 1.0);        // Continuous variable
  parameter Real k = 0.1;     // Parameter
  discrete Real y;            // Discrete variable
  
equation
  // Equations
  der(x) = -k * x;           // Differential equation
  y = if x > 0 then 1 else 0; // Conditional expression
  
algorithm
  // Algorithms (when needed)
  when x < 0.1 then
    y := 2;
  end when;
end ModelName;

Supported Types

  • Real: Real numbers (continuous variables)
  • Integer: Integer values
  • Boolean: Boolean values
  • parameter: Compile-time constants

Supported Constructs

  • Differential equations (der(x) = ...)
  • Algebraic equations
  • Conditional expressions (if-then-else)
  • When statements for discrete events
  • For loops with constant bounds
  • Functions from standard libraries

Built-in Functions

  • Mathematical functions: sin, cos, exp, log, sqrt, etc.
  • Event functions: pre, edge, change
  • Time functions: time, sample

Integration Methods

QSS Methods (Quantized State Systems)

QSS methods are particularly efficient for large-scale systems and event-driven simulations.

QSS1 (First Order)

  • Best for: Systems with moderate accuracy requirements
  • Advantages: Fast, good for stiff systems
  • Limitations: Lower accuracy than higher-order methods

QSS2 (Second Order)

  • Best for: Systems requiring better accuracy
  • Advantages: Better accuracy than QSS1, still fast
  • Use case: Most general-purpose simulations

QSS3 (Third Order)

  • Best for: High-accuracy requirements
  • Advantages: Highest accuracy among QSS methods
  • Trade-offs: Slower than QSS1/QSS2

Classic Methods

DASSL

  • Type: Differential-Algebraic Equation solver
  • Best for: Stiff systems with algebraic constraints
  • Order: Variable order (1-5)

DOPRI5

  • Type: Explicit Runge-Kutta method
  • Best for: Non-stiff systems requiring high accuracy
  • Order: 5th order with adaptive step size

CVODE

  • Type: Variable-step ODE solver (part of SUNDIALS)
  • Best for: Non-stiff to moderately stiff systems
  • Features: Excellent for large systems

IDA

  • Type: Differential-Algebraic Equation solver (part of SUNDIALS)
  • Best for: Index-1 DAE systems
  • Features: Robust for stiff systems

Choosing the Right Method

System Type Recommended Method Reason
Large-scale, event-driven QSS2/QSS3 Efficient event handling
Stiff with constraints DASSL/IDA Designed for DAEs
Non-stiff, high accuracy DOPRI5 High-order accuracy
General purpose QSS2 Good balance of speed/accuracy
Very large, moderate accuracy QSS1 Fastest for large systems

Using the GUI

The QSS Solver GUI provides an integrated development environment (IDE) for model creation, compilation, simulation, and analysis. The interface is designed to streamline the workflow from model definition to result visualization.

Figure 1: QSS Solver Main Interface empty_gui

The main interface (Figure 1) shows the complete layout with all major components visible, including the menu bar, toolbar, model editor, compilation panel, and output areas.

Main Interface Overview

The GUI consists of several key panels and windows:

1. Menu Bar

Figure 2: File Menu Options file_menu

The menu bar provides access to all major functions:

  • File: New, Open, Save, Save As, Recent Files, Exit (see Figure 2)
  • Edit: Cut, Copy, Paste, Find, Replace, Preferences
  • View: Show/Hide panels, Zoom, Syntax highlighting options
  • Build: Compile, Clean, Rebuild
  • Run: Start simulation, Stop, Pause, Resume
  • Tools: Settings, Plugins, External tools
  • Help: Documentation, About, Check for updates

Figure 3: Help Menu help_menu

Figure 14: Model Menu model_menu

Figure 15: View Menu view_menu

Additional menu options (Figures 14-15):

  • Model: Model-specific operations and validation
  • View: Panel visibility and display options

2. Toolbar

Quick access to frequently used functions:

  • ![New] New model file
  • ![Open] Open existing model
  • ![Save] Save current model
  • ![Compile] Compile model
  • ![Run] Start simulation
  • ![Stop] Stop simulation
  • ![Plot] Open plot window
  • ![Settings] Simulation settings

3. Model Editor Panel

Figure 4: Empty Model Editor empty_model

Figure 5: Model Editor with Loaded Model loaded_model

The main text editor for writing μ-Modelica code with features (Figures 4-5):

  • Syntax Highlighting: Color-coded keywords, strings, comments
  • Auto-completion: Intelligent code completion for μ-Modelica constructs
  • Error Detection: Real-time syntax checking with underlined errors
  • Code Folding: Collapse/expand model sections
  • Line Numbers: Easy navigation and error reference
  • Search and Replace: Find/replace with regex support
  • Multiple Tabs: Work with multiple models simultaneously

4. Compilation Panel

Figure 6: Messages and Compilation Panel messages

Shows compilation progress and messages (Figure 6):

  • Output Console: Displays compiler output, warnings, and errors
  • Error List: Clickable error messages that jump to source line
  • Progress Bar: Visual compilation progress indicator
  • Compilation Log: Detailed compilation information

5. Simulation Control Panel

Figure 7: Application Settings settings

Figure 8: Simulation Settings sim_settings

Figure 9: Full Simulation Settings Dialog full_sim_settings

Configure and control simulation execution (Figures 7-9):

  • Integration Method Selection: Dropdown with all available methods
  • Time Settings: Start time, stop time, output interval
  • Tolerance Settings: Relative and absolute tolerances
  • Advanced Options: Step size limits, event detection settings
  • Run Controls: Start, pause, stop, resume buttons
  • Real-time Monitoring: Current simulation time display

6. Plot Window

Figure 10: Plot Dock Window plot_dock

Interactive visualization of simulation results (Figure 10):

  • Multiple Plot Types: Line plots, scatter plots, phase plots
  • Variable Selection: Checkboxes to select variables to plot
  • Zoom and Pan: Mouse-controlled navigation
  • Export Options: Save plots as PNG, SVG, PDF
  • Data Export: Export raw data to CSV, MATLAB format
  • Multiple Subplots: Compare different variables
  • Custom Styling: Colors, line styles, markers

7. Statistics Panel

Real-time simulation performance metrics:

  • Integration Steps: Number of steps taken
  • Simulation Time: Wall-clock time elapsed
  • Event Count: Number of events detected
  • Memory Usage: Current and peak memory consumption
  • CPU Usage: Processor utilization
  • Jacobian Evaluations: For methods requiring Jacobians

Detailed Workflow

Step 1: Creating a New Model

  1. Launch QSS Solver GUI:

    qss_solver

  2. Create New Model:

    • Click File → New or press Ctrl+N
    • Choose model location and name
    • Select template (optional):
      • Empty Model: Blank μ-Modelica file
      • Basic Template: Pre-filled with basic structure
      • Control System: Template for control models
      • Physical System: Template for physical modeling

  3. Write Model Code:

    model MyFirstModel
  // Define parameters
  parameter Real k = 0.1;
  parameter Real x0 = 1.0;
  
  // Define variables
  Real x(start = x0);
  Real y;
  
equation
  // Write equations
  der(x) = -k * x;
  y = x * x;
  
end MyFirstModel;

Step 2: Model Validation and Compilation

  1. Syntax Checking:

    • The editor provides real-time syntax highlighting
    • Errors are underlined in red
    • Hover over errors to see detailed messages

  2. Compile Model:

    • Click Build → Compile or press F5
    • Watch the compilation panel for progress
    • Check for compilation errors/warnings

  3. Handle Compilation Errors:

    • Click on error messages to jump to source line
    • Common errors include:
      • Undefined variables: Check variable declarations
      • Type mismatches: Ensure consistent types
      • Missing equations: All variables must be defined

Step 3: Simulation Configuration

  1. Open Simulation Settings:

    • Click Tools → Settings or use the settings button
    • Navigate to the Simulation tab

  2. Configure Basic Settings:

    Integration Method: QSS2
Start Time: 0.0
Stop Time: 10.0
Output Interval: 0.1
Relative Tolerance: 1e-4
Absolute Tolerance: 1e-6

  3. Advanced Configuration:

    • QSS Methods: Quantum size settings
    • Classic Methods: Step size limits
    • Event Detection: Zero-crossing tolerance
    • Output Options: Variable selection, file format

  4. Save Configuration:

    • Use File → Save Configuration to save settings
    • Load configurations for similar models

Step 4: Running Simulation

  1. Start Simulation:

    • Click Run → Start or press F6
    • Monitor progress in the simulation control panel

  2. Real-time Monitoring:

    • Watch current simulation time
    • Monitor integration step count
    • Check for event detections

  3. Pause/Resume:

    • Use pause button to temporarily stop
    • Resume from where you left off
    • Useful for long simulations

  4. Early Termination:

    • Stop button for early termination
    • Results up to stopping point are saved

Step 5: Analyzing Results

  1. Open Plot Window:

    • Click View → Plot Window or use plot button
    • Available variables appear in the variable list

  2. Create Plots:

    • Select variables to plot (checkboxes)
    • Choose plot type from dropdown
    • Click Plot to generate visualization

  3. Customize Plots:

    Plot Type: Line Plot
X-Axis: Time
Y-Axis: Selected Variables
Line Style: Solid
Colors: Auto-assign
Markers: None

  4. Export Results:

    • Plots: Save as PNG, SVG, PDF
    • Data: Export to CSV, MATLAB, or plain text

Advanced GUI Features

Project Management

  1. Project Files:

    • Create project files (.qssproj) to organize multiple models
    • Include dependencies and shared libraries
    • Set project-wide compilation settings

  2. Version Control Integration:

    • Git integration for model versioning
    • Diff view for model changes
    • Commit and push from within GUI

Debugging Tools

  1. Breakpoint Setting:

    • Set breakpoints in model equations
    • Inspect variable values at specific times
    • Step through simulation time

  2. Variable Watch:

    • Add variables to watch list
    • Real-time value monitoring
    • Export watch history

  3. Performance Profiling:

    • Identify bottlenecks in large models
    • Function call timing
    • Memory allocation tracking

Plugin System

  1. Available Plugins:

    • Model Libraries: Pre-built component libraries
    • Analysis Tools: Specialized analysis plugins
    • Export Formats: Additional export options

  2. Installing Plugins:

    • Download plugin files (.qssplugin)
    • Install via Tools → Plugins → Install
    • Restart GUI to activate

Customization Options

Figure 11: Application Settings Dialog app_settings

  1. Editor Preferences (Figure 11):

    Font: Consolas, 12pt
Tab Size: 4 spaces
Line Wrapping: Enabled
Auto-indent: Enabled
Color Scheme: Dark

  2. GUI Layout:

    • Drag panels to rearrange layout
    • Save custom layouts
    • Reset to default layout

  3. Shortcut Customization:

    • Assign custom keyboard shortcuts
    • Create macros for repetitive tasks
    • Export/import shortcut settings

GUI Tips and Tricks

Productivity Tips

  1. Keyboard Shortcuts:

    • Ctrl+N: New model
    • Ctrl+O: Open model
    • Ctrl+S: Save model
    • F5: Compile
    • F6: Run simulation
    • Ctrl+F: Find
    • Ctrl+H: Replace
    • F11: Fullscreen mode

  2. Auto-completion:

    • Press Ctrl+Space for completion suggestions
    • Type first few letters of keywords
    • Use arrow keys to navigate suggestions

  3. Error Navigation:

    • Double-click errors to jump to source
    • Use F4 to go to next error
    • Use Shift+F4 to go to previous error

Visualization Tips

  1. Multiple Plots:

    • Use subplot feature for multiple graphs
    • Link axes for synchronized zoom
    • Create phase plots (x vs y)

  2. Data Analysis:

    • Use built-in data analysis tools
    • Calculate statistics (mean, std, min, max)
    • Perform FFT analysis on time series

  3. Export Options:

    • Batch export multiple plots
    • Custom plot templates
    • Automated report generation

Performance Tips

  1. Large Models:

    • Enable parallel processing in settings
    • Use sparse matrix options
    • Reduce output frequency for faster simulation

  2. Memory Management:

    • Monitor memory usage in statistics panel
    • Use streaming output for very long simulations
    • Clear plot history periodically

Troubleshooting GUI Issues

Common Problems

  1. Compilation Errors in GUI:

    • Check syntax highlighting for obvious errors
    • Use error panel for detailed messages
    • Verify model structure and variable declarations

  2. Plot Window Issues:

    • Ensure simulation completed successfully
    • Check output file permissions
    • Verify variable names match exactly

  3. Performance Issues:

    • Reduce plot update frequency
    • Disable real-time plotting for large models
    • Use compiled output files instead of live plotting

GUI Configuration

  1. Reset Settings:

    • Delete configuration file: ~/.config/qss-solver/
    • Restart GUI to restore defaults
    • Reconfigure as needed

  2. Display Issues:

    • Check system DPI settings
    • Adjust font sizes in preferences
    • Update graphics drivers if needed

Integration with External Tools

GNUPlot Integration

  • Automatic GNUPlot launching for advanced plotting
  • Custom script support for specialized visualizations
  • Export to GNUPlot format for external processing

MATLAB/Octave Integration

  • Export data in MATLAB format
  • Generate MATLAB scripts for analysis
  • Interface with external toolboxes

Python Integration

Figure 12: Python Console Integration python_console

  • Python console widget for data analysis (Figure 12)
  • NumPy/Pandas integration for data manipulation
  • Matplotlib integration for custom plots

Command Line Integration

Figure 13: Linux Console Usage linux_console

For advanced users and automation (Figure 13):

  • Command-line interface for batch processing
  • Scriptable simulation workflows
  • Integration with external build systems

MicroModelica Compiler (mmoc)

The mmoc command compiles μ-Modelica models to C code:

# Basic compilation
mmoc model.mo

# With debug information
mmoc -d SD_DBG_All model.mo

# Specify output directory
mmoc -o output_dir model.mo

# Generate only IR (no C code)
mmoc --ir-only model.mo

# Enable parallel processing
mmoc --parallel model.mo

Debug Flags

Debug flags control the level of information logged during simulation:

# Enable all debug flags
mmoc -d SD_DBG_All model.mo

# Specific debug options
mmoc -d SD_DBG_Dt model.mo          # Log dt changes
mmoc -d SD_DBG_Log model.mo          # Enable logging
mmoc -d SD_DBG_Jacobian model.mo     # Log Jacobian computations

Makefile Integration

After compilation, a Makefile is generated for building the simulation:

# Build the simulation
make -f model.make

# Clean build files
make -f model.make clean

# Install (if applicable)
make -f model.make install

Running Simulations

# Run with default settings
./model

# Run with custom configuration
./model --config config.cfg

# Run with different time span
./model --start 0 --stop 10

# Enable output to specific file
./model --output results.dat

Advanced Features

Parallel Computing

For large models, QSS Solver supports parallel execution:

# Compile with parallel support
mmoc --parallel --threads 4 model.mo

# Run with specific number of threads
./model --threads 8

Custom Functions

You can extend μ-Modelica with custom C functions:

  1. Create header file (myfunctions.h):

    #ifndef MYFUNCTIONS_H
#define MYFUNCTIONS_H

double custom_function(double x);

#endif

  2. Create source file (myfunctions.c):

    #include "myfunctions.h"
#include <math.h>

double custom_function(double x) {
    return sin(x) * exp(-x);
}

  3. Use in Model:

    model MyModel
  Real x, y;
equation
  y = custom_function(x);
end MyModel;

External Libraries

Link external libraries for additional functionality:

# Compile with external library
mmoc --link-library mylib --include-path /usr/include/mylib model.mo

Event Handling

Advanced event handling in μ-Modelica:

model EventExample
  Real x(start = 1.0);
  Boolean event_occurred;
  
equation
  der(x) = -0.1 * x;
  
algorithm
  when x < 0.5 then
    event_occurred := true;
    x := 1.0;  // Reset
  elsewhen x > 0.9 then
    event_occurred := false;
  end when;
end EventExample;

Model Partitioning

For very large models, automatic partitioning can improve performance:

# Enable partitioning
mmoc --partition --method kway model.mo

# Specify partition size
mmoc --partition --size 1000 model.mo

Troubleshooting

Common Compilation Errors

"Undefined identifier"

  • Cause: Variable or function not declared
  • Solution: Check spelling and ensure proper declarations

"Type mismatch"

  • Cause: Incompatible types in equation
  • Solution: Ensure consistent types (Real vs Integer)

"Circular dependency"

  • Cause: Variables depend on each other
  • Solution: Restructure equations to break cycles

Runtime Issues

"Simulation diverged"

  • Cause: Numerical instability
  • Solution:
    • Try a different integration method
    • Reduce time step (for classic methods)
    • Check model equations

"Memory allocation failed"

  • Cause: Insufficient memory for large model
  • Solution:
    • Increase system memory
    • Enable parallel processing
    • Reduce model size

"Event detection failed"

  • Cause: Problem with zero-crossing detection
  • Solution:
    • Check event conditions
    • Adjust tolerance settings
    • Try different event detection method

Performance Optimization

Slow Simulation

  1. Try QSS methods for large-scale systems
  2. Enable parallel processing
  3. Optimize model equations
  4. Use appropriate integration method

Memory Issues

  1. Reduce output frequency
  2. Enable sparse matrix methods
  3. Use partitioning for large models

Debug Information

Enable detailed logging to diagnose issues:

# Comprehensive debug
mmoc -d SD_DBG_All model.mo

# Specific areas
mmoc -d SD_DBG_Jacobian -d SD_DBG_Events model.mo

Examples

Example 1: Simple Pendulum

model Pendulum
  // Parameters
  parameter Real g = 9.81;    // Gravity
  parameter Real L = 1.0;     // Length
  parameter Real m = 1.0;     // Mass
  
  // State variables
  Real theta(start = 0.5);   // Angle
  Real omega(start = 0.0);   // Angular velocity
  
equation
  // Equations of motion
  der(theta) = omega;
  der(omega) = -(g/L) * sin(theta);
end Pendulum;

Example 2: Bouncing Ball

model BouncingBall
  parameter Real g = 9.81;
  parameter Real e = 0.8;    // Coefficient of restitution
  
  Real h(start = 10.0);      // Height
  Real v(start = 0.0);       // Velocity
  
equation
  der(h) = v;
  der(v) = -g;
  
algorithm
  when h <= 0.0 then
    v := -e * pre(v);        // Bounce
  end when;
end BouncingBall;

Example 3: Van der Pol Oscillator

model VanDerPol
  parameter Real mu = 1.0;
  
  Real x(start = 2.0);
  Real y(start = 0.0);
  
equation
  der(x) = y;
  der(y) = mu * (1 - x*x) * y - x;
end VanDerPol;

Example 4: Heat Transfer

model HeatTransfer
  parameter Integer n = 10;           // Number of nodes
  parameter Real L = 1.0;              // Length
  parameter Real k = 0.1;              // Thermal diffusivity
  parameter Real dx = L/(n-1);         // Spatial step
  
  Real T[n];                          // Temperature at each node
  
initial equation
  for i in 1:n loop
    T[i] = 293.15;                    // Initial temperature (20°C)
  end for;
  
equation
  // Boundary conditions
  der(T[1]) = k * (T[2] - T[1]) / (dx*dx);
  der(T[n]) = k * (T[n-1] - T[n]) / (dx*dx);
  
  // Interior nodes
  for i in 2:n-1 loop
    der(T[i]) = k * (T[i+1] - 2*T[i] + T[i-1]) / (dx*dx);
  end for;
end HeatTransfer;

Example 5: Control System

model ControlSystem
  parameter Real Kp = 1.0;            // Proportional gain
  parameter Real Ki = 0.1;            // Integral gain
  parameter Real Kd = 0.05;           // Derivative gain
  
  Real setpoint = 1.0;
  Real output(start = 0.0);
  Real error;
  Real integral(start = 0.0);
  Real derivative;
  Real prev_error(start = 0.0);
  
equation
  error = setpoint - output;
  der(integral) = error;
  derivative = der(error);
  
  der(output) = Kp * error + Ki * integral + Kd * derivative;
end ControlSystem;

Additional Resources

Documentation

Support

Academic Papers

The framework is described in several academic publications. See the README.md file for a complete list of related papers covering the theoretical foundations and applications of QSS methods.

Version: 5.0.0
License: GNU General Public License v3.0
Last Updated: 2025

Clone this wiki locally