API

moescape(s:: String)

Escapes string according to Modelica specification for string literals.

Escaped characters are: ['\\', '"', '?', '\a', '\b', '\f', '\n', '\r', '\t', '\v',]

moescape(s:: String)
moescape(io:: IO, s:: String)

Unescapes string that was escaped by moescape(s:: String) or that was returned from the OMC compiler. If io is given the string is printed to the IO object, otherwise it is returned directly.

setupOMCSession(outdir, modeldir; quiet=false, checkunits=true)

Creates an OMCSession and prepares it by preforming the following steps:

• create the directory outdir if it does not already exist
• change the working directory of the OMC to outdir
• add modeldir to the MODELICAPATH
• enable unit checking with the OMC command line option --unitChecking (unless checkunits is false)

If quiet is false, the resulting MODELICAPATH is printed to stdout.

Returns the newly created OMCSession.

closeOMCSession(omc:: OMCSession; quiet=false)

Closes the OMCSession given by omc, shutting down the OMC instance.

Due to a bug in the current release version of OMJulia the function may occasionally freeze. If this happens, you have to stop the execution with CTRL-C. You can tell that this is the case if the output Closing OMC session is printed to stdout, but it is not followed by Done. If desired, these outputs can be disabled by setting quiet=true.

If you want to use a MoST.jl script for continuous integration, you can use the following shell command to add a timeout to your script and treat the timeout as a successful test run (which is, of course, unsafe).

(timeout 2m julia myTestScript.jl; rc=$?; if [ ${rc} -eq 124 ]; then exit 0; else exit ${rc}; fi;)

withOMC(f:: Function, outdir, modeldir; quiet=false, checkunits=true)

Allows to use OMCSession with do-block syntax, automatically closing the session after the block has been executed. For the parameter definition see setupOMCSession(outdir, modeldir; quiet=false, checkunits=true).

Example:

withOMC("test/out", "test/res") do omc
    loadModel(omc, "Example")
end

installAndLoad(omc:: OMCSession, lib:: AbstractString; version="latest")

Loads the Modelica library lib in version version and also installs it if necessary.

loadModel(omc:: OMCSession, name:: String; check=true, instantiate=true)

Loads the model with fully qualified name name from a source file available from the model directory. Note that this refers to the model name, not the model file.

Example:

loadModel(omc, "Modelica.SIunits.Voltage")

This function will actually call several OM scripting functions to ensure that as many errors in the model are caught and thrown as MoSTErrors as possible:

• First, loadModel(name) is called to load the model if it exists. This call does only fail if the toplevel model does not exist. E.g., loadModel(Modelica.FooBar) would still return true, because Modelica could be loaded, although FooBar does not exist.
• We then check with getClassRestriction(name) if the model actually exists (which is the case when the return value is nonempty).
• With checkModel(name) we find errors such as missing or mistyped variables.
• Finally, we use instantiateModel(name) which can sometimes find additional errors in the model structure (e.g. since Modelica 1.16, unit consistency checks are performed here).

If check, or instantiate are false, the loading process is stopped at the respective steps.

getSimulationSettings(omc:: OMCSession, name:: String; override=Dict())

Reads simulation settings from the model name. Any content in override will override the setting with the respective key.

Returns a Dict with the keys "startTime", "stopTime", "tolerance", "numberOfIntervals", "outputFormat" and "variableFilter". If any of these settings are not defined in the model file, they will be filled with default values.

In override, an additional key "interval" is allowed to recalculate the "numberOfIntervals" based on the step size given as value to this key.

Throws a MoSTError if the model name was not loaded beforehand using loadModel(omc:: OMCSession, name:: String).

getVariableFilter(omc:: OMCSession, name:: String)

Reads the value for the variableFilter simulation setting from the model file if it has been defined. MoST assumes that this value will be given in a vendor-specific annotation of the form __MoST_experiment(variableFilter=".*"). If such an annotation is not found, the default filter ".*" is returned.

Throws a MoSTError if the model name does not exist.

simulate(omc:: OMCSession, name::String)
simulate(omc:: OMCSession, name::String, settings:: Dict{String, Any})

Simulates the model name which must have been loaded before with loadModel(omc:: OMCSession, name:: String). The keyword-parameters in settings are directly passed to the OpenModelica scripting function simulate(). If the parameter is not given, it is obtained using getSimulationSettings(omc:: OMCSession, name:: String; override=Dict()).

The simulation output will be written to the current working directory of the OMC that has been set by setupOMCSession(outdir, modeldir; quiet=false, checkunits=true).

The simulation result is checked for errors with the following methods:

• The messages returned by the OM scripting call are checked for the string Simulation execution failed. This will, e.g., be the case if there is an arithmetic error during simulation.
• The abovementioned messages are checked for the string | warning | which hints at missing initial values and other non-critical errors.
• The error string returned by the OM scripting function getErrorString() should be empty if the simulation was successful.

If any of the abovementioned methods reveals errors, a MoSTError is thrown.

testmodel(omc, name; override=Dict(), refdir="regRefData", regRelTol:: Real= 1e-6)

Performs a full test of the model named name with the following steps:

• Load the model using loadModel(omc:: OMCSession, name:: String) (called inside @test)
• Simulate the model using simulate(omc:: OMCSession, name::String, settings:: Dict{String, Any}) (called inside @test)
• If a reference file exists in refdir, perform a regression test with regressionTest(omc:: OMCSession, name:: String, refdir:: String; relTol:: Real = 1e-6, variableFilter:: String = "", outputFormat="csv").

regressionTest(
    omc:: OMCSession, name:: String, refdir:: String;
    relTol:: Real = 1e-6, variableFilter:: String = "", outputFormat="csv",
    resample=true
)

Performs a regression test that ensures that variable values in the simulation output are approximately equal to variables in the reference file in the directory given by refdir. Both the simulation output and the reference file must have the standard name "$(name)_res.$outputFormat". This function also assumes that the simulation a simulation of the model named name has already been run with simulate(omc:: OMCSession, name::String, settings:: Dict{String, Any}).

The test consists of the following checks performed with @test:

• Are there no variables in the simulation output that have no corresponding variable in the reference file? For this check, variables are ignored that occur in the simulation file but should not have been selected by the regex variableFilter. This can happen in OpenModelica, because sometimes alias variables are added to the output even though they do not match the variableFilter.
• Are there no variables in the reference file that have no corresponding variable in the simulation output?
• Is the intersection of common variables in both files nonempty?
• Is the length of the simulation output equal to the length of the reference file?
• If the length is not equal and resample is true, resample the data to equal length.
• Are there any variables in the simulation file that do not satisfy isapprox(act, ref, rtol=relTol) for all values?

NOTE: There is a OM scripting function compareSimulationResults() that could be used for this task, but it is not documented and does not react to changes of its relTol parameter in a predictable way.

MoSTError

Error class for OMJulia-related errors that contains the OMC error message.

MoSTError(omc:: OMCSession, msg:: String)

Creates MoSTError with message msg and current result of getErrorString() as OMC error message.

getDocAnnotation(omc:: OMCSession, name:: String)

Returns documentation string from model annotation and strips <html> tag if necessary.

getcode(omc:: OMCSession, model:: String)

Returns the code of the given model or class as a string.

getequations(omc:: OMCSession, model::String)

Returns all equations of the given model as a list of strings with presentation MathML syntax.

getvariables(omc:: OMCSession, model::String)

Returns an array of dictionaries that contain the following keys describing the variables and parameters of the given model.

• "name": the name of the variable
• "variability": is the variable a parameter, a constant, or a variable?
• "type": the data type of the variable (usually "Real")
• "label": the string label attached to the variable
• "quantity": the kind of physical quantity modeled by the variable
• "unit": the unit of the variable in Modelica unit syntax
• "initial": the initial value of the variable, if existent
• "bindExpression": the expression used to fix the variable value, if existent
• "aliasof": the name of the other variable of which this variable is an alias

An empty string is used as value for keys which are not applicable for the given variable.

mdescape(s:: String)

Escapes characters that have special meaning in Markdown with a backslash.

variabletable(vars:: Array{Dict{Any, Any},1})

Creates a Markdown table from an array of variable descriptions as returned by getvariables(omc:: OMCSession, model::String).