OMJulia.jl

https://openmodelica.github.io/OMJulia.jl/dev
Admin
OMJulia.jl is a free, open-source Julia API that provides an interactive session handler for...
Tokens:11,437
Snippets:82
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Execute OpenModelica Scripting Commands in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/quickstart

This snippet demonstrates how to start an OMJulia.jl session, send scripting API expressions to the OMC, and handle potential path-related issues on different operating systems. It covers loading models, simulating them, and retrieving simulation results.

```julia
using OMJulia
omc = OMJulia.OMCSession()
installDir = sendExpression(omc, "getInstallationDirectoryPath")
bouncingBallFile = joinpath(installDir, "share", "doc", "omc", "testmodels", "BouncingBall.mo")
if Sys.iswindows()
    bouncingBallFile = replace(bouncingBallFile, "\" => "/")
end
sendExpression(omc, "loadFile(\"$(bouncingBallFile)\")")
sendExpression(omc, "simulate(BouncingBall)")
OMJulia.quit(omc)
```

--------------------------------

### Install Package - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Installs a specified package with an optional version. If no version is provided, it attempts to install the most recent version. The `exactMatch` parameter controls whether to install the exact version specified, even if newer compatible versions exist.

```julia
installPackage(omc, pkg;
               version="",
               exactMatch=false)
```

--------------------------------

### Get Installation Directory Path - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Returns the installation directory path of OpenModelica. It prioritizes the OPENMODELICAHOME environment variable and provides a default path if the variable is not set.

```julia
getInstallationDirectoryPath(omc)
```

--------------------------------

### Simulate BouncingBall with OMJulia.API in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/quickstart

Illustrates simulating the 'BouncingBall' model using OMJulia.API in Julia. This approach directly calls scripting API functions for loading the model, executing simulation, and retrieving results for plotting.

```julia
using OMJulia  
using OMJulia.API: API  
using CSV, DataFrames, PlotlyJS  
omc = OMJulia.OMCSession();
installDir = API.getInstallationDirectoryPath(omc)
bouncingBallFile = joinpath(installDir, "share", "doc", "omc", "testmodels", "BouncingBall.mo")
API.loadFile(omc, bouncingBallFile)
res = API.simulate(omc, "BouncingBall"; stopTime=3.0, outputFormat = "csv")
resultfile = res["resultFile"]
df = DataFrame(CSV.File(resultfile));
plt = plot(df,
                  x=:time, y=:h,
                  mode="lines",
                  Layout(title="Bouncing Ball", height = 700))
OMJulia.quit(omc)
```

--------------------------------

### Define BouncingBall Modelica Model

Source: https://openmodelica.github.io/OMJulia.jl/dev/quickstart

Defines the 'BouncingBall' model in Modelica, specifying parameters for restitution, gravity, initial conditions, and equations governing the ball's motion and impact.

```modelica
model BouncingBall
  parameter Real e=0.7 "coefficient of restitution";
  parameter Real g=9.81 "gravity acceleration";
  Real h(fixed=true, start=1) "height of ball";
  Real v(fixed=true) "velocity of ball";
  Boolean flying(fixed=true, start=true) "true, if ball is flying";
  Boolean impact;
  Real v_new(fixed=true);
  Integer foo;
equation
  impact = h <= 0.0;
  foo = if impact then 1 else 2;
  der(v) = if flying then -g else 0;
  der(h) = v;

  when {h <= 0.0 and v <= 0.0,impact} then
    v_new = if edge(impact) then -e*pre(v) else 0;
    flying = v_new > 0;
    reinit(v, v_new);
  end when;
end BouncingBall;
```

--------------------------------

### Simulate BouncingBall with ModelicaSystem in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/quickstart

Demonstrates simulating the 'BouncingBall' model using OMJulia's ModelicaSystem API in Julia. It loads the model, runs the simulation, saves results to CSV, and plots the height over time using PlotlyJS.

```julia
using OMJulia  
using CSV, DataFrames, PlotlyJS  
mod = OMJulia.OMCSession();
installDir = sendExpression(mod, "getInstallationDirectoryPath()")
bouncingBallFile = joinpath(installDir, "share", "doc", "omc", "testmodels", "BouncingBall.mo")
ModelicaSystem(mod,
                  bouncingBallFile,
                  "BouncingBall")
simulate(mod,
                resultfile = "BouncingBall_ref.csv",
                simflags   = "-override=outputFormat=csv,stopTime=3")
resultfile = joinpath(getWorkDirectory(mod), "BouncingBall_ref.csv")
df = DataFrame(CSV.File(resultfile));
plt = plot(df,
                  x=:time, y=:h,
                  mode="lines",
                  Layout(title="Bouncing Ball", height = 700))
OMJulia.quit(mod)
```

--------------------------------

### Install OMJulia.jl Package

Source: https://openmodelica.github.io/OMJulia.jl/dev/index

This code snippet demonstrates how to install the OMJulia.jl package using Julia's package manager. It requires Julia to be installed.

```julia
import Pkg
Pkg.add("OMJulia")
```

--------------------------------

### Get Input Variables from XML with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves input variables from an XML file using OMJulia. It takes an OMCSession object and an optional name filter. Input variables without a start value are represented as 'None'.

```julia
getInputs(omc, name=nothing)
```

--------------------------------

### Upgrade Installed Packages - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Updates all currently installed Modelica packages to their latest available versions. This function is part of the package management system and helps maintain up-to-date libraries.

```Julia
upgradeInstalledPackages(omc; installNewestVersions=true)
```

--------------------------------

### Get Available Package Versions - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Retrieves a list of available versions for a specified package. It is particularly useful for managing library versions, such as the Buildings library, by querying the OSMC server.

```julia
getAvailablePackageVersions(omc, pkg; version="")
```

--------------------------------

### Get Version - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Retrieves the version string of the installed Modelica compiler. This is essential for checking compatibility and ensuring the correct compiler is being used.

```julia
getVersion(omc)
```

--------------------------------

### Get OMJulia Working Directory

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves the temporary working directory created by OMJulia for a given OMCSession. This directory contains simulation results and other generated files.

```julia
getWorkDirectory(omc)
```

--------------------------------

### Update Package Index - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Refreshes the locally stored list of available Modelica packages by contacting OpenModelica servers. This ensures that users have access to the latest package information for installation and management.

```Julia
updatePackageIndex(omc)
```

--------------------------------

### Get Parameters from XML with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Fetches parameter variables from an XML file using OMJulia. Requires an OMCSession object and supports filtering by parameter names. If no name is provided, all parameters are retrieved.

```julia
getParameters(omc, name=nothing)
```

--------------------------------

### Escaping Special Characters in MOS Commands for sendExpression

Source: https://openmodelica.github.io/OMJulia.jl/dev/quickstart

Illustrates how to correctly format a MOS (Modelica OpenModelica Script) command containing special characters, specifically file paths with backslashes, when passing it to the sendExpression function in Julia. This ensures proper execution within the OMC.

```julia
sendExpression(omc, "loadFile(\"/some/path/to/BouncingBall.mo\")")
```

--------------------------------

### Get Simulation Options in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves simulation options configured for the OpenModelica model. It can fetch all options or a specific subset by name. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`), optional list of option names (Vector{String}). Outputs: A dictionary of simulation options or a vector of their string representations.

```julia
getSimulationOptions(mod)
getSimulationOptions(mod, ["stepSize","tolerance"])
```

--------------------------------

### Get Simulation Solutions with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Reads simulation results from a result file using OMJulia. It requires an OMCSession object and can filter variables by name. An optional `resultfile` argument specifies the path to the result file.

```julia
getSolutions(omc::OMCSession, name=nothing; resultfile=nothing)
```

--------------------------------

### Get Input Variables in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves the input variables defined for the OpenModelica model. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`). Outputs: A dictionary mapping input variable names to their values.

```julia
getInputs(mod)
```

--------------------------------

### Get Simulation Options from XML with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves simulation option variables parsed from an XML file using OMJulia. It takes an OMCSession object and an optional name filter for parameters. All parameters are returned if no specific name is supplied.

```julia
getSimulationOptions(omc, name=nothing)
```

--------------------------------

### Get Error String - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Retrieves the current error message from the OpenModelica compiler. It can optionally treat warnings as errors, which is useful for stricter build processes.

```julia
getErrorString(omc, warningsAsErrors = false)
```

--------------------------------

### Get Model Quantities in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

This snippet demonstrates how to retrieve all quantities (variables, parameters, etc.) from an OpenModelica model loaded via OMJulia. The output is a vector of dictionaries, where each dictionary represents a quantity and its attributes like name, causality, and description. It's useful for understanding the structure and components of a loaded model.

```julia
getQuantities(mod)
```

--------------------------------

### Get Quantities from XML with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves a list of all variables parsed from an XML file using OMJulia. It takes an OMCSession object and an optional variable name or array of names. If no name is provided, all variables are returned.

```julia
getQuantities(omc, name=nothing)
```

--------------------------------

### Get Output Variables in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves the output variables defined for the OpenModelica model. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`). Outputs: A dictionary mapping output variable names to their values.

```julia
getOutputs(mod)
```

--------------------------------

### Get Simulation Result Size - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Retrieves the number of time intervals present in a simulation output file. This information is useful for understanding the temporal resolution of the simulation results.

```Julia
readSimulationResultSize(omc, fileName)
```

--------------------------------

### Get Model Parameters in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves model parameters from the OpenModelica model. It can fetch all parameters or a specific subset by name. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`), optional list of parameter names (Vector{String}). Outputs: A dictionary of parameters or a vector of their string representations.

```julia
getParameters(mod)
getParameters(mod, ["a","V"])
```

--------------------------------

### Get Model Quantities by Name in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves a list of dictionaries, where each dictionary represents a quantity (variable) in the model. It can fetch quantities by a single name or a list of names. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`), quantity name(s) (String or Vector{String}). Outputs: Vector of dictionaries describing the quantities.

```julia
getQuantities(mod, "T")
getQuantities(mod, ["T","cA"])
```

--------------------------------

### Get Continuous Variables from XML with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Fetches continuous variables parsed from an XML file via OMJulia. The function accepts an OMCSession object and an optional name filter. All continuous variables are returned if no specific name is given.

```julia
getContinuous(omc, name=nothing)
```

--------------------------------

### Get Class Names - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Returns a list of class names defined within a given class. This function provides options for recursive searching, qualified names, sorting, and including protected or built-in classes.

```julia
getClassNames(omc;
              class_ = "",
              recursive = false,
              qualified = false,
              sort = false,
              builtin = false,
              showProtected = false,
              includeConstants = false)
```

--------------------------------

### Get Continuous Variables in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves continuous variables from the OpenModelica model. It can fetch all continuous variables or a specific subset by name. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`), optional list of variable names (Vector{String}). Outputs: A dictionary of continuous variables or a vector of their values.

```julia
getContinuous(mod)
getContinuous(mod, ["Qd","Tc"])
```

--------------------------------

### Define and Load Modelica Model with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Demonstrates how to initialize an OMCSession, load a Modelica model file, and instantiate it as a ModelicaSystem. This involves setting up the communication with OpenModelica and specifying the model path and name.

```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod,
                  joinpath("docs", "testmodels", "ModSeborgCSTRorg.mo"),
                  "ModSeborgCSTRorg")
```

--------------------------------

### ModelicaSystem Function

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Constructs a ModelicaSystem object, which prepares a Modelica model for simulation by setting command-line options and building the model.

```APIDOC
## ModelicaSystem Function

### Description
Creates a `ModelicaSystem` object to set command-line options for an OMCSession and build a specified Modelica model for simulation.

### Method
```julia
ModelicaSystem(omc, fileName, modelName, library=nothing; commandLineOptions=nothing, variableFilter=nothing, customBuildDirectory=nothing)
```

### Parameters
#### Arguments
- **omc** (OMCSession) - Required - An OpenModelica compiler session.
- **fileName** (String) - Required - Path to the Modelica file.
- **modelName** (String) - Required - The name of the Modelica model to build, including its namespace if applicable.
- **library** (Union{String, Tuple, Array, Nothing}) - Optional - A list of dependent libraries or Modelica files. Can be a string, tuple, or array of strings/tuples.

#### Keyword Arguments
- **commandLineOptions** (String) - Optional - OpenModelica command-line options.
- **variableFilter** (String) - Optional - A regular expression to filter variables in the result file.
- **customBuildDirectory** (String) - Optional - Specifies a custom directory for building the model.

### Request Example
```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod, "BouncingBall.mo", "BouncingBall", ["Modelica", "SystemDynamics"], commandLineOptions="-d=newInst")
```

### See Also
- `OMCSession()`
- `OMJulia.quit`
```

```APIDOC
## ModelicaSystem Function (Keyword Arguments)

### Description
An alternative signature for `ModelicaSystem` that primarily uses keyword arguments for configuration.

### Method
```julia
ModelicaSystem(omc; modelName, library=nothing, commandLineOptions=nothing, variableFilter=nothing, customBuildDirectory=nothing)
```

### Parameters
#### Arguments
- **omc** (OMCSession) - Required - An OpenModelica compiler session.

#### Keyword Arguments
- **modelName** (String) - Required - The name of the Modelica model to build, including its namespace if applicable.
- **library** (Union{String, Tuple, Array, Nothing}) - Optional - A list of dependent libraries or Modelica files. Can be a string, tuple, or array of strings/tuples.
- **commandLineOptions** (String) - Optional - OpenModelica command-line options.
- **variableFilter** (String) - Optional - A regular expression to filter variables in the result file.
- **customBuildDirectory** (String) - Optional - Specifies a custom directory for building the model.

### Request Example
```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod, modelName="Modelica.Electrical.Analog.Examples.CauerLowPassAnalog", library="Modelica")
```

### See Also
- `OMCSession()`
- `OMJulia.quit`
```

--------------------------------

### Set Methods for Model Configuration

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

APIs for setting input variables, parameters, and simulation options for a Modelica model.

```APIDOC
## setInputs(omc, name)

### Description
Sets new values for input variables of the model.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **name** (Union{String, Array{String,1}}) - Required - A string in the format "Name=value" or a vector of strings like ["Name1=value1","Name2=value2"].

### Request Example
```julia
setInputs(mod, "cAi=100")
setInputs(mod, ["cAi=100","Ti=200","Vdi=300","Tc=250"])
```

### Response
#### Success Response (200)
- **Bool**: Indicates if the operation was successful.

## setParameters(omc, name; verbose=true)

### Description
Sets parameter values for user-defined parameter variables.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **name** (Union{String, Array{String,1}}) - Required - A string in the format "Name=value" or a vector of strings like ["Name1=value1","Name2=value2"].
#### Keyword Arguments
- **verbose** (Bool) - Optional - Displays additional information if setting parameters fails. Defaults to true.

### Request Example
```julia
setParameters(mod, "a=3")
setParameters(mod, ["a=4","V=200"])
```

### Response
#### Success Response (200)
- **String**: The value that was set for the parameter.

## setSimulationOptions(omc, name)

### Description
Sets simulation option values such as `stopTime` or `stepSize`.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **name** (Union{String, Array{String,1}}) - Required - A string in the format "Name=value" or a vector of strings like ["Name1=value1","Name2=value2"].

### Request Example
```julia
setSimulationOptions(mod, ["stopTime=2.0", "tolerance=1e-08"])
```

### Response
*Response details not provided in the source text.*

```

--------------------------------

### Create and Configure ModelicaSystem in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The ModelicaSystem function initializes an OpenModelica compilation session for a specified Modelica model. It allows setting command-line options, filtering variables, and defining custom build directories. Dependencies can be specified as strings, tuples, or arrays.

```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod, "BouncingBall.mo", "BouncingBall", ["Modelica", "SystemDynamics"], commandLineOptions="-d=newInst")
```

```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod, "BouncingBall.mo", "BouncingBall", ["Modelica", "SystemDynamics", "dcmotor.mo"])
```

```julia
using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod, modelName="Modelica.Electrical.Analog.Examples.CauerLowPassAnalog", library="Modelica")
```

--------------------------------

### OMCSession Type and Constructor

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Manages an OpenModelica compiler session. The constructor creates a new session, optionally specifying the path to the OpenModelica compiler executable.

```APIDOC
## OMCSession Type

### Description
Represents an OpenModelica compiler session.

### Type Definition
```julia
OMCSession <: Any
```

## OMCSession Constructor

### Description
Initializes a new OpenModelica compiler session.

### Method
```julia
OMCSession(omc::Union{String, Nothing}=nothing)
```

### Parameters
#### Arguments
- **omc** (Union{String, Nothing}) - Optional - The path to the OpenModelica compiler executable. If `nothing`, the compiler is searched for in the system's `PATH`.

### See Also
- `ModelicaSystem`
- `OMJulia.quit`
```

--------------------------------

### Perform Sensitivity Analysis in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

This code snippet demonstrates how to perform a sensitivity analysis using the OMJulia.jl package. It takes a model, parameters to vary, outputs to observe, and perturbation values as input. The output includes sensitivity matrices and values.

```julia
julia> (Sn, Sa) = sensitivity(mod, ["UA","EdR"], ["T","cA"], [1e-2,1e-4])stopTime=2.0

V=200

a=3.0

tolerance=1e-08

stopTime=2.0

V=200

UA=50500.0

a=3.0

tolerance=1e-08

stopTime=2.0

V=200

EdR=8750.875

UA=50000.0

a=3.0

tolerance=1e-08

([["Sensitivity.UA.T", "Sensitivity.UA.cA"], ["Sensitivity.EdR.T", "Sensitivity.EdR.cA"]], [[[0.0, -8.46484032376793e-6, -1.8798798871443978e-5, -4.054143004407251e-5, -0.00028025729756348027, -6.051659275703969e-5, -8.768568498362584e-5, -0.00011815583249176598, -0.0001516332132214302, -0.00018800934382238665  …  -0.03209010383710483, -0.03210104827926261, -0.03211190136089135, -0.03212267289974443, -0.03213335596196521, -0.03214394907919814, -0.032154454090326905, -0.03216487956045239, -0.032175218940616104, -0.032175218940616104], [0.0, 2.601676771352146e-9, 3.3445380127172794e-8, 2.2605955135546197e-7, 3.5318723430695085e-6, 8.329957789204867e-8, 7.168512584540543e-8, 6.345060944540349e-8, 5.638188856171844e-8, 5.040525208062363e-8  …  8.856962310426452e-9, 8.860592887278626e-9, 8.865492741881414e-9, 8.867668825999e-9, 8.86896148159181e-9, 8.86904980795973e-9, 8.868635808970993e-9, 8.870353771220884e-9, 8.872947805761873e-9, 8.872947805761873e-9]], [[0.0, -2.4135574026981236e-6, -1.316218634071577e-5, 0.00015636715482157473, 0.013177910234259928, 0.0042572811244099285, 0.0030510811233658125, 0.002350161991801412, 0.0018775321397177841, 0.0015375293686312424  …  0.00011258585228850799, 0.00011259551164195207, 0.00011268012895016, 0.00011274436006455549, 0.00011269701125066993, 0.0001126057852941033, 0.00011244580777461774, 0.00011218779504166118, 0.00011179777668855553, 0.00011179777668855553], [0.0, 3.464740799025938e-8, 1.8925106358226783e-7, -2.2433035995155544e-6, -0.00018911546028377302, -6.305955485789003e-5, -4.5964775551775106e-5, -3.606039447237982e-5, -2.9394320519000277e-5, -2.4605578297357384e-5  …  -1.5254439210011378e-6, -1.52539591180333e-6, -1.5253540044091085e-6, -1.5253116510930659e-6, -1.525262738660182e-6, -1.5252130899814126e-6, -1.5251617968122958e-6, -1.5251077768130085e-6, -1.5250497614154629e-6, -1.5250497614154629e-6]])
```

--------------------------------

### Simulate Modelica Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Initiates the simulation of a Modelica model. It handles the entire process from C code generation and compilation to running the simulation executable, with extensive options for controlling simulation parameters.

```Julia
simulate(omc, className;
        startTime = 0.0,
        stopTime = nothing,
        numberOfIntervals = 500,
        tolerance = 1e-6,
        method = "",
        fileNamePrefix=className,
        options = "",
        outputFormat = "mat",
        variableFilter = ".*",
        cflags = "",
        simflags = "")
```

--------------------------------

### Advanced Simulation

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

API for simulating a Modelica model with various configuration options.

```APIDOC
## simulate(omc; resultfile=nothing, simflags="", verbose=false)

### Description
Simulates a Modelica model with configurable options for result files, simulation flags, and verbosity.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **omc** (OMCSession) - Required - The OpenModelica compiler session.
#### Keyword Arguments
- **resultFile** (Union{String, Nothing}) - Optional - Specifies the file to write simulation results into. Defaults to nothing.
- **simflags** (String) - Optional - Simulation flags, refer to Simulation Runtime Flags documentation. Defaults to an empty string.
- **verbose** (Bool) - Optional - Enables debug logging to `log.txt` and `error.txt`. Defaults to false.

### Request Example
```julia
simulate(omc)
simulate(omc, resultfile="tmpresult.mat")
simulate(omc, simflags="-noEmitEvent -override=e=0.3,g=9.3")
```

### Response
*Response details not provided in the source text, but simulation output is logged.*

```

--------------------------------

### Load File - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Loads a Modelica file (*.mo) and merges its contents with the existing Abstract Syntax Tree (AST). Supports specifying file encoding and notification options. This is crucial for incorporating custom or library models into the compiler.

```julia
loadFile(omc, fileName;
         encoding = "",
         uses = true,
         notify = true,
         requireExactVersion = false)
```

--------------------------------

### Set Command Line Options - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Configures command-line flags for the OpenModelica Compiler (OMC). This allows fine-tuning of the compilation and simulation process, such as enabling debug traces.

```Julia
setCommandLineOptions(omc, option)
```

--------------------------------

### OMJulia Linearization Options Management

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Manages linearization options for OMJulia. `getLinearizationOptions` retrieves current settings, optionally for specific parameters. `setLinearizationOptions` updates these settings. Both require an OMCSession.

```Julia
getLinearizationOptions(omc)
getLinearizationOptions(omc, ["startTime", "stopTime"])
setLinearizationOptions(omc, ["stopTime=2.0", "tolerance=1e-06"])
```

--------------------------------

### String Escaping: OpenModelica vs OMJulia.API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Demonstrates how OMJulia.API simplifies string handling for file loading compared to direct OpenModelica scripting API calls. The API automatically escapes strings, making the code cleaner and less prone to errors.

```julia
sendExpression(omc, "loadFile(\"$(bouncingBallFile)\")")
```

```julia
API.loadFile(omc, bouncingBallFile)
```

--------------------------------

### Initialize OpenModelica Compiler Session in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The OMCSession function creates a new session for the OpenModelica compiler. It can optionally take a path to the OpenModelica compiler executable; otherwise, it defaults to using 'omc' found in the system's PATH.

```julia
using OMJulia
mod = OMJulia.OMCSession()
```

--------------------------------

### Instantiate Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Instantiates a Modelica class and returns its flattened Modelica code. This is useful for inspecting the structure of a compiled model or for further programmatic manipulation.

```julia
instantiateModel(omc, className)
```

--------------------------------

### Load Modelica Library - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Loads a specified Modelica library using the OpenModelica scripting API. This function is essential for making library components available within the OpenModelica environment.

```Julia
languageStandard = "",
requireExactVersion = false)
```

--------------------------------

### Reading Simulation Results

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

APIs for retrieving simulation results after a model has been simulated. Supports default result filenames and user-specified filenames.

```APIDOC
## getSolution()

### Description
Retrieves simulation results using the default result filename.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
*None*

### Request Example
```julia
getSolution(mod)
```

### Response
#### Success Response (200)
- **Vector{String}**: A list of variable names available in the simulation results.

#### Response Example
```json
["DrHt", "EdR", "Qd", "T", "T0", "Tc", "Ti", "UA", "V", "Vdi", "cph", "der(T)", "der(cA)", "k", "k0", "r", "rho", "time", "y_T"]
```

## getSolution(mod, variable_names)

### Description
Retrieves simulation results for specified variables.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **variable_names** (Array{String}) - Required - A list of variable names for which to retrieve results.

### Request Example
```julia
getSolutions(mod, ["time","a"])
```

### Response
#### Success Response (200)
- **Vector{Vector{Float64}}**: A list of arrays, where each array corresponds to the time series data for a requested variable.

#### Response Example
```json
[[0.0, 0.002, 0.004, ...], [1.0, 1.0, 1.0, ...]]
```

## getSolution(mod, resultfile="path/to/file.mat")

### Description
Retrieves simulation results from a user-specified result file.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Query Parameters
- **resultfile** (String) - Required - The path to the simulation result file.

### Request Example
```julia
getSolutions(mod, resultfile="C:/BouncingBal/tmpbouncingBall.mat")
```

### Response
#### Success Response (200)
- **Vector{String}**: A list of variable names available in the simulation results from the specified file.

## getSolution(mod, variable_names, resultfile="path/to/file.mat")

### Description
Retrieves simulation results for specified variables from a user-specified result file.

### Method
*Not explicitly defined, assumed to be a function call in Julia.*

### Endpoint
*Not applicable for function calls.*

### Parameters
#### Path Parameters
- **variable_names** (Array{String}) - Required - A list of variable names for which to retrieve results.
#### Query Parameters
- **resultfile** (String) - Required - The path to the simulation result file.

### Request Example
```julia
getSolutions(mod, ["time","h"], resultfile="C:/BouncingBal/tmpbouncingBall.mat")
```

### Response
#### Success Response (200)
- **Vector{Vector{Float64}}**: A list of arrays, where each array corresponds to the time series data for a requested variable from the specified file.

```

--------------------------------

### Load Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Loads a specified Modelica model into the compiler. It allows for prioritizing specific versions of the model using `priorityVersion` and controlling notification behavior.

```julia
loadModel(omc, className;
          priorityVersion = String[],
          notify = false)
```

--------------------------------

### Build Modelica Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Generates C code from a Modelica model and compiles it into an executable simulation. It does not run the simulation itself. This function is useful for creating standalone simulations from Modelica code.

```julia
buildModel(omc, className;
           startTime = 0.0,
           stopTime = 1.0,
           numberOfIntervals = 500,
           tolerance = 1e-6,
           method = "",
           fileNamePrefix = className,
           options = "",
           outputFormat = "mat",
           variableFilter = ".*",
           cflags = "",
           simflags = "")
```

--------------------------------

### Perform Model Simulation with simulate() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The simulate() function executes the model simulation. It can optionally take a result file name, simulation flags, and a verbose option for detailed logging.

```julia
simulate(omc)
```

```julia
simulate(omc, resultfile="tmpresult.mat")
```

```julia
simulate(omc, simflags="-noEmitEvent -override=e=0.3,g=9.3")
```

```julia
simulate(mod)
```

--------------------------------

### OMJulia Linearization Input/Output/State Retrieval

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Retrieves information about the linearized model. `getLinearInputs`, `getLinearOutputs`, and `getLinearStates` return the respective variable names after linearization. Requires an OMCSession and a previously linearized model.

```Julia
getLinearInputs(mod)
getLinearOutputs(mod)
getLinearStates(mod)
```

--------------------------------

### Compare Simulation Results - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Compares the results of two simulations. It allows for specifying tolerance levels and filtering variables for comparison. This is valuable for verifying simulation accuracy and consistency.

```julia
diffSimulationResults(omc, actualFile, expectedFile, diffPrefix;
                      relTol = 1e-3,
                      relTolDiffMinMax = 1e-4,
                      rangeDelta = 0.002,
                      vars = String[],
                      keepEqualResults = false)
```

--------------------------------

### Configure Simulation Options with setSimulationOptions() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

This function allows modification of simulation-specific options such as stop time and tolerance. It takes an array of strings, where each string specifies an option and its value.

```julia
setSimulationOptions(mod, ["stopTime=2.0", "tolerance=1e-08"])
```

--------------------------------

### OMJulia Sensitivity Analysis

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Computes the numeric sensitivity of an OpenModelica object. It requires an OMCSession, parameter names, variable names, and optional excitation values. Returns sensitivity names and the computed sensitivity arrays.

```Julia
sensitivity(omc::OMCSession, Vp::Array{<:AbstractString, 1}, Vv::Array{<:AbstractString, 1}, Ve=[1e-2])
```

--------------------------------

### Format String Vector - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Takes a vector of strings and adds quotes around each element, ensuring they are treated as individual string literals. This is useful for preparing string arguments for OpenModelica functions.

```Julia
makeVectorString(vec)
```

--------------------------------

### Read Simulation Variables - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Fetches the names of variables recorded in a simulation file. This enables users to identify and access specific data points for further analysis or plotting.

```Julia
readSimulationResultVars(omc, fileName; readParameters = true, openmodelicaStyle = false)
```

--------------------------------

### Change Directory - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Changes the current working directory for the OpenModelica compiler. It can accept both relative and absolute paths. If an empty string is provided, it returns the current directory.

```julia
cd(omc, newWorkingDirectory="")
```

--------------------------------

### OMJulia Linearization API

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Performs linearization of a Modelica model and returns the A, B, C, D matrices. It accepts an OMCSession and optional arguments for linearization time and simulation flags. Dependencies include an active OMCSession.

```Julia
linearize(omc)
linearize(omc, lintime="0.5")
linearize(omc, simflags="-noEmitEvent")
```

--------------------------------

### Show Quantities as DataFrame with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Returns a DataFrame of all variables parsed from an XML file using OMJulia. It requires an OMCSession object and can filter by specific variable names. If no name is specified, all variables are included.

```julia
showQuantities(omc, name=nothing)
```

--------------------------------

### Read Simulation Results with getSolution() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The getSolution() function in OMJulia.jl is used to retrieve simulation results after a model has been simulated. It can be called with default result filenames or with user-specified filenames.

```julia
simulate(mod)
getSolutions(mod)
getSolutions(mod, ["time","a"])
```

```julia
getSolutions(mod, resultfile="C:/BouncingBal/tmpbouncingBall.mat")
getSolutions(mod, ["time","h"], resultfile="C:/BouncingBal/tmpbouncingBall.mat")
```

--------------------------------

### Build FMU Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Translates a Modelica model into a Functional Mockup Unit (FMU). This is useful for interoperability with other simulation tools. The function supports various FMU versions and types.

```julia
buildModelFMU(omc, className;
              version = "2.0",
              fmuType = "me",
              fileNamePrefix=className,
              platforms=["static"],
              includeResources = false)
```

--------------------------------

### Build Modelica Model with OMJulia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Builds a loaded Modelica model using OMJulia. This function can be used to update the model or prepare it for simulation. An optional `variableFilter` can be provided as a regular expression to limit the variables included in the results.

```julia
buildModel(omc)
buildModel(omc, variableFilter="a|T")
```

--------------------------------

### Show All Model Quantities as DataFrame in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Displays all quantities within the loaded OpenModelica model as a formatted DataFrame. This function provides a comprehensive overview of all variables, their properties, and values. Dependencies: Requires a loaded OpenModelica model object (`mod`). Inputs: Model object (`mod`). Outputs: A DataFrames.jl DataFrame.

```julia
showQuantities(mod)
```

--------------------------------

### Set Parameter Values with setParameters() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The setParameters() function is used to set values for user-defined parameter variables in a model. Similar to setInputs(), it supports single or multiple parameter assignments.

```julia
setParameters(mod, "a=3")
```

```julia
setParameters(mod, ["a=4","V=200"])
```

```julia
setParameters(mod, "a=3.0")
```

--------------------------------

### quit Function

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

Terminates an existing OpenModelica compiler session.

```APIDOC
## quit Function

### Description
Closes and terminates an `OMCSession`.

### Method
```julia
quit(omc::OMCSession; timeout=4::Integer)
```

### Parameters
#### Arguments
- **omc** (OMCSession) - Required - The OMC session to quit.

#### Keywords
- **timeout** (Integer) - Optional - The timeout in seconds for quitting the session. Defaults to 4 seconds.

### See Also
- `OMJulia.OMCSession`
```

--------------------------------

### Retrieve Model Parameters with getParameters() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The getParameters() function retrieves the current values of all parameters defined in the model. This is useful for verifying parameter settings before or after simulation.

```julia
getParameters(mod)
```

--------------------------------

### Read Simulation Results - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Reads simulation output from a specified file. It allows filtering variables and setting the desired size of the result matrix. This function is crucial for analyzing simulation outcomes.

```Julia
readSimulationResult(omc, filename,
                     variables = String[],
                     size = 0)
```

--------------------------------

### Set Input Variables with setInputs() in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The setInputs() function allows users to set new values for input variables in a model. It accepts a single string in 'Name=value' format or an array of strings for multiple inputs.

```julia
setInputs(mod, "cAi=100")
```

```julia
setInputs(mod, ["cAi=100","Ti=200","Vdi=300","Tc=250"])
```

--------------------------------

### Linearize Model - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Creates a new model by performing symbolic linearization on an existing model. This function is useful in control systems design and analysis where linear approximations are needed.

```julia
linearize(omc)
```

--------------------------------

### Modelica Model Definition: ModSeborgCSTRorg

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

This is a Modelica model defining a Continuous Stirred Tank Reactor (CSTR) with heat transfer. It includes parameters for reactor volume, density, reaction kinetics, heat capacity, enthalpy, and heat transfer coefficients, as well as state variables for concentration and temperature, and input variables for flow rates and temperatures.

```modelica
model ModSeborgCSTRorg
  // Model of original Seborg CSTR in ode form
  // author: Bernt Lie, University of Southeast Norway,November 7, 2017

  // Parameters
  parameter Real V = 100 "Reactor volume, L";
  parameter Real rho = 1e3 "Liquid density, g/L";
  parameter Real a = 1 "Stoichiometric constant, - ";
  parameter Real EdR = 8750 "Activation temperature, K";
  parameter Real k0 = exp(EdR/350) "Pre-exponential factor, 1/min";
  parameter Real cph = 0.239 "Specific heat capacity of mixture, J.g-1.K-1";
  parameter Real DrHt = -5e4 "Molar enthalpy of reaction, J/mol";
  parameter Real UA = 5e4 "Heat transfer parameter, J/(min.K)";

  // Initial state parameters
  parameter Real cA0 = 0.5 "Initial concentration of A, mol/L";
  parameter Real T0 = 350 "Initial temperature, K";
  // Declaring variables
  // -- states
  Real cA(start = cA0, fixed = true) "Initializing concentration of A in reactor, mol/L";
  Real T(start = T0, fixed = true) "Initializing temperature in reactor, K";
  // -- auxiliary variables
  Real r "Rate of reaction, mol/(L.s)";
  Real k "Reaction 'constant', ...";
  Real Qd "Heat flow rate, J/min";
  // -- input variables
  input Real Vdi "Volumetric flow rate through reactor, L/min";
  input Real cAi "Influent molar concentration of A, mol/L";
  input Real Ti "Influent temperature, K";
  input Real Tc "Cooling temperature', K";
  // -- output variables
  output Real y_T "Reactor temperature, K";
  // Equations constituting the model
equation
  // Differential equations
  der(cA) = Vdi*(cAi-cA)/V- a*r;
  der(T) = Vdi*(Ti-T)/V + (-DrHt)*r/(rho*cph) + Qd/(rho*V*cph);
  // Algebraic equations
  r = k*cA^a;
  k = k0*exp(-EdR/T);
  Qd = UA*(Tc-T);
  // Outputs
  y_T = T;
end ModSeborgCSTRorg
```

--------------------------------

### Define Scripting Error Type - OMJulia API

Source: https://openmodelica.github.io/OMJulia.jl/dev/api

Defines a custom exception type for handling errors that occur during OpenModelica scripting operations. It captures the error message and additional details from the OpenModelica compiler.

```Julia
ScriptingError <: Exception
```

--------------------------------

### Send Scripting API Expression to OMC Session (Julia)

Source: https://openmodelica.github.io/OMJulia.jl/dev/sendExpression

The `sendExpression` function initiates a new `OMCSession` and sends scripting API expressions to the OMC session. It takes the OMC session object and the expression string as input. The `parsed` argument defaults to `true`. Special characters within the expression string, such as double quotes and backslashes in file paths, require proper escaping.

```Julia
using OMJulia
omc = OMJulia.OMCSession()
OMJulia.sendExpression(omc, "getVersion()")

# Example with file loading on Windows with escaped backslashes
OMJulia.sendExpression(omc, "loadFile(\"C:\\\\path\\\\to\\\\M.mo\")")

# Example with file loading on Windows using Unix-style paths
OMJulia.sendExpression(omc, "loadFile(\"/c/path/to/M.mo\")")
```

--------------------------------

### Quit OpenModelica Compiler Session in Julia

Source: https://openmodelica.github.io/OMJulia.jl/dev/modelicaSystem

The quit function terminates an active OMCSession. It accepts the OMCSession object and an optional timeout in seconds for the operation.

```julia
using OMJulia
quit(omc::OMCSession; timeout=4::Integer)
```
Tokens:
Raw