OMBackend.jl is one component of OMJL, the Modelica compiler infrastructure
for Julia. It takes a model in its own intermediate representation, OMJLIR
(src/IR), runs its passes there (src/Backend/Passes), generates the
simulation code (src/SimCode) and from it a system that can be simulated with
DifferentialEquations.jl and ModelingToolkit.jl (src/CodeGeneration).
The flat model of OMFrontend.jl is lowered to OMJLIR by the package extension
OMBackendOMFrontendExt (ext/OMBackendOMFrontendExt), which Julia loads when
OMFrontend is loaded: the lowering, translate(fm) and the other entry points
on the frontend's flat model, the frontend's part of a recompilation at a
structural change, and the translate precompile workload. omc's flat model goes
through OMBackendOMCompilerExt (with OMCompiler.jl). Without either,
OMBackend.translate takes an OMJLIR.Model.
- Julia 1.13
- Git
- A checkout of the sibling OM*.jl packages next to this repository (see below)
The main runtime dependencies are pulled in by Project.toml. The most
relevant ones are:
- DifferentialEquations.jl, OrdinaryDiffEq.jl, DiffEqBase.jl, DiffEqCallbacks.jl, Sundials.jl
- ModelingToolkit.jl, Symbolics.jl, SymbolicUtils.jl
- Graphs.jl, DataStructures.jl, MacroTools.jl, Setfield.jl
- ExportAll.jl
Weak dependencies, each with a package extension that Julia loads when the package is loaded (they keep the
precompilation of OMBackend alone short; OM loads the first two itself):
- Plots.jl:
OMBackend.plot(OMBackendPlotsExt). On Windows load Plots before OMBackend: Glib's gettext runtime must be loaded before OMRuntimeExternalC's (OMBackend.jl#101). - JuliaFormatter.jl: the formatted generated code of
printModel,modelToStringandwriteModelToFile; without it the code is written as it is (OMBackendJuliaFormatterExt). - OMFrontend.jl with OMParser.jl and MetaModelica.jl: the lowering of the frontend's flat model (
OMBackendOMFrontendExt).
The OMJL ecosystem packages are developed from sibling checkouts next to
OMBackend.jl, as the CI does (Pkg.develop of each, .github/workflows/CI.yml).
OMBackend depends on OMRuntimeExternalC; OMFrontend (with its SCode module), OMParser (its Absyn module)
and MetaModelica are weak dependencies, the triggers of OMBackendOMFrontendExt, and the tests use OMFrontend;
ImmutableList is OMFrontend's (ArrayUtil and ListUtil are modules of OMFrontend):
- ImmutableList.jl
- MetaModelica.jl
- OMFrontend.jl
- OMParser.jl
- OMRuntimeExternalC.jl
Layout:
OMJL-workspace/
├── ImmutableList.jl/
├── MetaModelica.jl/
├── OMBackend.jl/ <-- this repository
├── OMFrontend.jl/
├── OMParser.jl/
└── OMRuntimeExternalC.jl/
OMRuntimeExternalC.jl is not in the General registry. The others are served
by the OpenModelica Julia registry, but the developed checkouts take precedence
and are used for development.
Add the OpenModelica Julia registry once per Julia depot:
julia> import Pkg
julia> Pkg.Registry.add("General")
julia> Pkg.Registry.add(Pkg.RegistrySpec(url = "https://github.com/OpenModelica/OpenModelicaRegistry.git"))From the OMBackend.jl directory, activate the project and develop the sibling
checkouts (nothing is built: the parser is written in Julia):
julia> import Pkg
julia> Pkg.activate(".")
julia> Pkg.develop([Pkg.PackageSpec(path = joinpath("..", p)) for p in
("ImmutableList.jl", "MetaModelica.jl", "OMFrontend.jl",
"OMParser.jl", "OMRuntimeExternalC.jl")])Then load the package:
julia> using OMBackendFrom the OMBackend.jl directory:
julia> import Pkg
julia> Pkg.activate(".")
julia> Pkg.test()Or directly:
julia> include("test/runtests.jl")utilities/ holds scripts for work on the package. They are not part of the
package or its tests, and not of the test coverage (CI measures src only).
lowerCheck.jl: whether every definition of a source file lowers. Revise applies a changed file only if all of it lowers; run this on edited files beforeRevise.revise().lowerCheck("src/CodeGeneration/mtkExternals.jl", OMBackend.CodeGeneration)in a session, orjulia utilities/lowerCheck.jl files...from the shell.aliasStartValueAB.jl: compares the alias start value resolution with a reference implementation on every candidate equation of the models built (aliasStartValueAB(models), in a session with OM loaded).
Given a Modelica model flattened by OMFrontend.jl (loading OMFrontend loads the
extension), pass the flat model and its functions to OMBackend.translate and
then simulate (examples/ has more).
model BouncingBallReals
parameter Real e = 0.7;
parameter Real g = 9.81;
Real h(start = 1);
Real v;
equation
der(h) = v;
der(v) = -g;
when h <= 0 then
reinit(v, -e * pre(v));
end when;
end BouncingBallReals;julia> import OMFrontend
julia> scode = OMFrontend.translateToSCode(OMFrontend.parseFile("BouncingBallReals.mo"))
julia> (fm, cache) = OMFrontend.instantiateSCodeToFM("BouncingBallReals", scode)
julia> OMBackend.translate(fm; functionList = OMFrontend.cacheToFunctionList(cache))
julia> OMBackend.simulateModel("BouncingBallReals"; tspan = (0.0, 2.5))The documentation is built with Documenter.jl from docs/: the home page, getting started and the API
reference.
- Online: https://OpenModelica.github.io/OMBackend.jl/ (the development version under
/dev/, a release under/stable/and/vX.Y.Z/). - In Julia: the docstring of every function is in the help mode, for example
?OMBackend.simulateModel. - Locally, from the repository root (the HTML is written to
docs/build/):
julia> import Pkg
julia> Pkg.activate("docs")
julia> Pkg.develop(path = ".") # and the sibling packages, as in the Installation section
julia> include("docs/make.jl")If you use OMBackend.jl in academic work, please cite the entries in CITATION.bib.
OMBackend.jl is distributed under the OSMC Public License 1.8 or the GNU Affero General Public License version 3, at the recipient's choice. See LICENSE.md, which holds both.
