fz-modelica

A Funz plugin for OpenModelica - simulate and analyze Modelica models through parametric studies.

Features

Input Syntax

• Variable syntax: ${variable_name~default_value}
• Formula syntax: @{formula}
• Comment character: //

Supported Output Variables

The Modelica model extracts simulation results:

• res: JSON dictionary containing all simulation output CSV data

Installation

This plugin requires the Funz/fz framework and OpenModelica.

pip install git+https://github.com/Funz/fz.git

See INSTALL_OPENMODELICA.md for detailed OpenModelica installation instructions.

Usage

With fz Python API

import fz

# Example: Run simulation with varying parameters
results = fz.fzr(
    input_path="examples/Modelica/NewtonCooling.mo",
    input_variables={
        "convection": [0.5, 0.7, 0.9]
    },
    model="Modelica",
    calculators="localhost_Modelica",
    results_dir="my_results"
)

print(results[['convection', 'res']])

Directory Structure

your_project/
├── examples/
│   └── Modelica/
│       ├── NewtonCooling.mo       # Example Modelica model
│       └── ProjectileMotion.mo    # Example physics model
├── .fz/
│   ├── models/
│   │   └── Modelica.json          # Model configuration
│   └── calculators/
│       ├── Modelica.sh            # Calculator script
│       └── localhost_Modelica.json
├── tests/
│   └── test_plugin.py             # Test suite
├── *.ipynb                        # Jupyter notebook examples
└── results/                       # Generated by fz

Example Notebooks

Comprehensive Jupyter notebooks demonstrating the plugin:

📓 01_NewtonCooling_Parametric.ipynb

• Introduction to Funz-Modelica workflow
• Single and parametric simulations
• Visualization of cooling curves
• Analysis of convection effects

📓 02_ProjectileMotion_Parametric.ipynb

• Projectile motion physics
• Effect of launch angle and velocity
• Range and height calculations
• Classical mechanics validation

📓 03_ProjectileMotion_Advanced.ipynb

• 2D parameter space exploration
• Contour plots and heatmaps
• Target hitting optimization
• Result caching for efficiency

Run the Notebooks

# Install dependencies
pip install jupyter matplotlib scipy pandas

# Start Jupyter
jupyter notebook

Example Input File

model NewtonCooling "An example of Newton's law of cooling"
  parameter Real T_inf=25 "Ambient temperature";
  parameter Real T0=90 "Initial temperature";
  parameter Real h=${convection~0.7} "Convective cooling coefficient";
  // ... rest of model
end NewtonCooling;

In this example:

• ${convection~0.7} is a variable parameter with default value 0.7 that will be substituted by fz
• Lines starting with // are comments

Creating Your Own Plugin

To create a custom plugin based on this template:

1. Clone this repository as a starting point
2. Customize the calculator script:
   • Edit .fz/calculators/Modelica.sh for your specific needs
   • Implement actual calls to your simulation code
3. Update output parsing:
   • Edit the output section in your model JSON
   • Add shell commands that extract values from your output files
4. Add examples:
   • Create example input files for your simulation code

Model Configuration

The model JSON file defines variable syntax and output parsing:

{
    "id": "Modelica",
    "varprefix": "$",
    "formulaprefix": "@",
    "delim": "{}",
    "commentline": "//",
    "output": {
        "res": "python -c '...'"
    }
}

Fields:

• id: Unique identifier for the model
• varprefix: Character prefix for variables (e.g., $ for ${x})
• formulaprefix: Character prefix for formulas
• delim: Delimiter characters around variable names
• commentline: Character(s) that start a comment line
• output: Mapping of output variable names to shell commands that extract their values

Calculator Configuration

The calculator JSON files define how to execute your code:

{
    "uri": "sh://",
    "models": {
        "Modelica": "bash .fz/calculators/Modelica.sh"
    }
}

• uri: Execution method (sh:// for local shell, ssh:// for remote)
• models: Mapping of model names to execution commands

Remote Execution

To run calculations on a remote server:

results = fz.fzr(
    input_path="model.mo",
    input_variables={"x": [1.0, 2.0, 3.0]},
    model="Modelica",
    calculators="ssh://[email protected]/bash /path/to/calculators/Modelica.sh",
    results_dir="remote_results"
)

Troubleshooting

OpenModelica not found

Error: omc command not found

Install OpenModelica from https://openmodelica.org/ or see INSTALL_OPENMODELICA.md

Calculator script not found

Ensure the calculator script is executable:

chmod +x .fz/calculators/Modelica.sh

Output variable not found

Check the output section in your model JSON file. The shell commands must correctly parse your output files.

Running Tests

python tests/test_plugin.py

License

BSD 3-Clause License. See LICENSE file.

Related Links

• Funz/fz - Main framework
• Funz/fz-Model - Template repository
• INSTALL_OPENMODELICA.md - OpenModelica installation
• CONTRIBUTING.md - Contribution guidelines