Add Python ZMQ server with SSP/SSD API for OMS3 GUI

doc/UsersGuide/source/OMEdit.rst

@@ -4,84 +4,87 @@
 Graphical Modelling
 ===================
 
-OMSimulator has an optional dependency to OpenModelica in order to
-utilize the graphical modelling editor OMEdit. This feature requires
-to install the full OpenModelica tool suite, which includes
-OMSimulator. The independent stand-alone version doesn't provide any
-graphical modelling editor.
+OMSimulator provides a graphical modelling environment through OMEdit, the
+OpenModelica Connection Editor. This feature requires a full OpenModelica
+installation that includes OMSimulator.
 
-Composite models are imported and exported in the System Structure Description (SSD) format,
-which is part of the System Structure and Parameterization (SSP) standard.
+Composite models are imported and exported in the System Structure Description
+(SSD) format, which is part of the System Structure and Parameterization (SSP)
+standard.
 
 See also `FMI documentation <https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/fmitlm.html>`_
 and `SSP documentation <https://ssp-standard.org/>`_.
 
-.. figure :: images/omedit_01.png
-  :name: oms-omedit-mainwindow-browsers
+Architecture
+------------
+
+OMEdit communicates with OMSimulator through a Python-based ZMQ server:
 
-  OMEdit MainWindow and Browsers.
+- **OMSimulatorGuiServer.py** — handles all GUI-driven requests (model
+  management, element queries, solver settings, connections, etc.)
+- **OMSimulatorSimulationServer.py** — handles simulation execution and
+  result streaming
+
+The GUI server is started automatically when the first SSP model is opened
+or created. A notification in the Messages Browser confirms the server is
+running, including the script path and ZMQ endpoint.
 
 New SSP Model
----------------------
+-------------
 
-A new and empty SSP model can be created from `File->New->SSP` menu item.
+A new and empty SSP model can be created from ``File -> New -> SSP`` menu item.
 
 .. figure :: images/omedit_02.png
 
   OMEdit: New SSP Model
 
-That will open a dialog to enter the names of the model and the root
-system and to choose the root systems type.
-
-There are three types available:
-  - TLM - Transmission Line Modeling System
-  - Weakly Coupled - Connected Co-Simulation FMUs System
-  - Strongly Coupled - Connected Model-Exchange FMUs System
+A dialog opens to enter the model name and the name of the root system.
 
 .. figure :: images/omedit_03.png
 
   OMEdit: New SSP Model Dialog
 
-.. figure :: images/omedit_04.png
+.. figure :: images/omedit_01.png
 
   OMEdit: Newly created empty root system of SSP model
 
-Add System
-----------
+Open SSP Model
+--------------
 
-When a new model is created a root system is always generated.
-If you need to have another system in your root system you can
-add it with `SSP->Add System`.
+An existing SSP file (``.ssp``) can be opened from ``File -> Open Model/Library``.
+If a model with the same name is already loaded, an error is reported and the
+file is not loaded again.
 
-For example only a weakly coupled system (Co-Simulation) can integrate strongly coupled
-system (Model Exchange). Therefore, the weakly coupled system must
-be selected from the Libraries Browser and the respective menu item
-can be selected:
+Add System and Sub-Systems
+--------------------------
+
+A root system is always created together with the model. Additional subsystems
+can be added inside the root system via ``SSP -> Add System``.
 
 .. figure :: images/omedit_05.png
 
   OMEdit: Add System
 
-That will pop-up a dialog to enter the names of the new system.
+A dialog opens to enter the name of the new system.
 
 .. figure :: images/omedit_06.png
 
   OMEdit: Add System Dialog
 
+
 Add SubModel
 ------------
 
-A sub-model is typically an FMU, but it also can be result file. In
-order to import a sub-model, the respective system must be selected
-and the action can be selected from the menu bar:
+A sub-model is typically an FMU, but it can also be a result file (CSV). To
+add a sub-model, select the target system in the Libraries Browser and choose
+``SSP -> Add SubModel``.
 
 .. figure :: images/omedit_07.png
 
   OMEdit: Add SubModel
 
-The file browser will open to select an FMU (.fmu) or result file
-(.csv) as a subsmodel.
-Then a dialog opens to choose the name of the new sub-model.
+A file browser opens to select an FMU (``.fmu``) or result file (``.csv``).
+A dialog then opens to set the name for the new sub-model.
 
 .. figure :: images/omedit_08.png
 
@@ -91,26 +94,121 @@ Then a dialog opens to choose the name of the new sub-model.
 
   OMEdit: Root system with added FMU.
 
+Replace SubModel
+----------------
+
+An existing sub-model can be replaced with a different FMU by right-clicking
+on the component in the diagram view and selecting ``Replace SubModel`` from
+the context menu.
+
+.. figure :: images/omedit_replace_submodel.png
+
+  OMEdit: Replace SubModel Dialog.
+
+A file browser opens to select the new FMU. The replacement is performed in
+two steps:
+
+1. **Dry run** (``dryRun=true``) — OMEdit first performs a dry run without
+   making any changes to the model. It checks for interface differences between
+   the old and new FMU, such as added, removed, or modified connectors and
+   parameters. If any changes are detected, they are reported in the Messages
+   Browser and a warning dialog is shown. The model remains unchanged at this
+   stage, allowing the user to review the impact before deciding to proceed.
+
+2. **Replacement** (``dryRun=false``) — If the user confirms, the replacement
+   is carried out and all detected interface changes are applied to the model.
+   Existing connections to removed or renamed connectors are dropped, and new
+   connectors are available for connecting.
+
+.. figure :: images/omedit_replace_submodel_contextmenu.png
+
+  OMEdit: Replace SubModel context menu.
+
+
+
+Simulation Setup
+----------------
+
+Select ``Simulation -> Simulation Setup`` to configure simulation parameters
+before running. The dialog has two tabs: **General** and **Solver Settings**.
+
+The **General** tab covers start time, stop time, and result file settings.
+
+.. figure :: images/omedit_simulation_setup.png
+
+  OMEdit: Simulation Setup — Solver Settings tab with a solver configuration.
+
+The **Solver Settings** tab is divided into two parts:
+
+**Solver Configurations**
+
+This table lists the named solver configurations available in the model.
+Each configuration has a name and a method. Click **Add** to create a new
+solver configuration — a new row appears in the table with a default method
+of ``oms-ma``. The method can be changed using the combo box in the Method
+column.
+
+.. figure :: images/omedit_simulation_setup_solver_settings.png
+
+  OMEdit: Simulation Setup — Solver Settings tab with a solver configuration.
+
+To fine-tune a solver's numerical parameters, select the row and click
+**Edit**. This opens the Solver Settings dialog:
+
+.. figure :: images/omedit_simulation_setup_solver_edit.png
+
+  OMEdit: Solver Settings dialog.
+
+The available fields depend on the solver method:
+
+- **Fixed-step solvers** (``oms-ma``, ``euler``) — Fixed Step Size is editable;
+  Initial Step Size, Minimum Step Size, and Maximum Step Size are disabled.
+- **Variable-step solvers** (``oms-mav``, ``oms-mav-2``, ``cvode``) — Initial
+  Step Size, Minimum Step Size, Maximum Step Size, and Relative Tolerance are
+  editable; Fixed Step Size is disabled.
+
+Click **Remove** to delete the selected solver configuration.
+
+**Component Assignments**
+
+This table lists all FMU components in the model. Each component can be
+assigned one of the named solver configurations using the combo box in the
+Solver column. The available solvers are filtered by the FMI kind of each
+component:
+
+- **Co-Simulation FMUs** — only co-simulation masters are selectable
+  (``oms-ma``, ``oms-mav``, ``oms-mav-2``).
+- **Model-Exchange FMUs** — only ODE integrators are selectable
+  (``cvode``, ``euler``).
+- **me+cs FMUs** — all solvers are available.
+
+
+.. figure :: images/omedit_component_assignment_solver.png
+
+  OMEdit: Solver Assignments in Components
+
+Incompatible solvers are shown as disabled in the combo box with a tooltip
+explaining why. If no solver is assigned, ``(none)`` is used and the
+system default applies.
+
 Simulate
 --------
 
-Select the simulate button (symbol with green arrow) or select
-`Simulation->Simulate` from the menu in OMEdit to simulate the
-SSP model.
+Select the simulate button (green arrow) or ``Simulation -> Simulate`` to
+run the SSP model. Results are streamed back in real time via the simulation
+server.
+
 
 Dual Mass Oscillator Example
 ----------------------------
 
-The dual mass oscillator example from our testsuite is
-a simple example one can recreate using components from the
-Modelica Standard Library.
-After splitting the model into two models and exporting each
-as an Model-Exchange and Co-Simulation FMU.
+The dual mass oscillator example from the test suite demonstrates a typical
+SSP workflow. The model is split into two sub-models, each exported as an FMU,
+and then connected in an SSP.
 
 .. figure :: images/DualMassOscillator.png
 
-  Dual mass oscillator Modelica model (diagramm view) and FMUs
-
+  Dual mass oscillator Modelica model (diagram view) and FMUs
 
 .. figure :: images/omedit_10.png
 

doc/UsersGuide/source/OMSimulatorPython3.rst

@@ -158,6 +158,8 @@ The following example demonstrates how to
 
 .. include:: api/oms3/initialize.rst
 
+.. include:: api/oms3/setSolver.rst
+
 .. include:: api/oms3/simulate.rst
 
 .. include:: api/oms3/terminate.rst

doc/UsersGuide/source/api/oms3/setSolver.rst

@@ -0,0 +1,134 @@
+Solver
+------
+
+OMSimulator supports different solver methods depending on the FMI kind of the
+components in the system. Solvers are configured by name in the Simulation
+Setup dialog and assigned to individual FMU components.
+
+Available Solvers
+~~~~~~~~~~~~~~~~~
+
+**Co-Simulation (CS) Solvers**
+
+Co-simulation solvers act as masters that drive the co-simulation protocol.
+They are used for FMUs that implement the co-simulation interface (CS FMUs).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - Description
+   * - ``oms_ma``
+     - **Master Algorithm** — fixed-step co-simulation master. The step size
+       is controlled by the ``fixedStepSize`` setting.
+   * - ``oms_mav``
+     - **Master Algorithm with Variable Step** — variable-step co-simulation
+       master. Uses ``initialStepSize``, ``minimumStepSize``, and
+       ``maximumStepSize`` to control the step size, and ``relativeTolerance``
+       for error control.
+   * - ``oms_mav2``
+     - **Master Algorithm with Variable Step (v2)** — an improved variable-step
+       co-simulation master with enhanced error estimation. Supports the same
+       settings as ``oms_mav``.
+
+**Model-Exchange (ME) Solvers**
+
+Model-exchange solvers are ODE integrators used for FMUs that implement the
+model-exchange interface (ME FMUs). They integrate the continuous-time
+equations provided by the FMU.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Method
+     - Description
+   * - ``cvode``
+     - **CVODE** — variable-step, variable-order ODE solver from the SUNDIALS
+       suite. Suitable for stiff and non-stiff systems. Supports
+       ``initialStepSize``, ``minimumStepSize``, ``maximumStepSize``, and
+       ``relativeTolerance``.
+   * - ``euler``
+     - **Explicit Euler** — simple fixed-step explicit Euler integrator.
+       Suitable for non-stiff systems. Controlled by ``fixedStepSize``.
+
+Solver Settings
+~~~~~~~~~~~~~~~
+
+The following settings can be configured for each named solver:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Setting
+     - Applies to
+     - Description
+   * - ``relativeTolerance``
+     - ``oms_mav``, ``oms_mav2``, ``cvode``
+     - Relative error tolerance used for step-size control.
+   * - ``fixedStepSize``
+     - ``oms_ma``, ``euler``
+     - The fixed communication / integration step size.
+   * - ``initialStepSize``
+     - ``oms_mav``, ``oms_mav2``, ``cvode``
+     - The initial step size at the start of simulation.
+   * - ``minimumStepSize``
+     - ``oms_mav``, ``oms_mav2``, ``cvode``
+     - The minimum allowed step size.
+   * - ``maximumStepSize``
+     - ``oms_mav``, ``oms_mav2``, ``cvode``
+     - The maximum allowed step size.
+
+Solver Assignment
+~~~~~~~~~~~~~~~~~
+
+Each FMU component in a system can be assigned one named solver configuration.
+The available solvers are filtered based on the FMI kind of the component:
+
+- **CS FMUs** — only co-simulation solvers (``oms_ma``, ``oms_mav``,
+  ``oms_mav2``) are available.
+- **ME FMUs** — only model-exchange solvers (``cvode``, ``euler``) are
+  available.
+- **me+cs FMUs** — all solvers are available.
+
+If no solver is assigned to a component, the system default ``oms_ma`` is applied.
+
+**Example**
+
+The following example creates two named solver configurations — one using the
+fixed-step Euler method and one using the variable-step CVODE solver — and
+assigns them to individual components.
+
+.. code-block:: python
+
+   from OMSimulator import SSP, CRef, Settings
+
+   Settings.suppressPath = True
+
+   model = SSP()
+
+   # Add FMU resources
+   model.addResource('../resources/Modelica.Blocks.Math.Add.fmu', new_name='resources/Add.fmu')
+   model.addResource('../resources/Modelica.Blocks.Math.Gain.fmu', new_name='resources/Gain.fmu')
+
+   # Instantiate components
+   model.addComponent(CRef('default', 'Add1'), 'resources/Add.fmu')
+   model.addComponent(CRef('default', 'Add2'), 'resources/Add.fmu')
+   model.addComponent(CRef('default', 'Gain1'), 'resources/Gain.fmu')
+   model.addComponent(CRef('default', 'Gain2'), 'resources/Gain.fmu')
+
+   # Define solver configurations
+   solver1 = {'name': 'solver1', 'method': 'euler', 'fixedStepSize': 1e-3}
+   model.newSolver(solver1)
+
+   solver2 = {'name': 'solver2', 'method': 'cvode', 'relativeTolerance': 1e-4,
+              'initialStepSize': 1e-6, 'minimumStepSize': 1e-12, 'maximumStepSize': 0.001}
+   model.newSolver(solver2)
+
+   # Assign solvers to components
+   model.setSolver(CRef('default', 'Add1'), 'solver1')
+   model.setSolver(CRef('default', 'Add2'), 'solver2')
+   model.setSolver(CRef('default', 'Gain1'), 'solver1')
+   model.setSolver(CRef('default', 'Gain2'), 'solver2')