Skip to content

About

Backend for OMJL. A Modelica Compiler and environment written in Julia

Topics

Resources

Stars

4 stars

Watchers

8 watching

Forks

Latest commit

 

History

227 Commits

Folders and files

Repository files navigation

Github Action CI License: AGPL-3.0 or OSMC-PL Documentation

About OMBackend.jl

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.

Requirements

  • Julia 1.13
  • Git
  • A checkout of the sibling OM*.jl packages next to this repository (see below)

Dependencies

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, modelToString and writeModelToFile; 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.

Installation

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 OMBackend

Running tests

From the OMBackend.jl directory:

julia> import Pkg
julia> Pkg.activate(".")
julia> Pkg.test()

Or directly:

julia> include("test/runtests.jl")

Utilities

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 before Revise.revise(). lowerCheck("src/CodeGeneration/mtkExternals.jl", OMBackend.CodeGeneration) in a session, or julia 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).

Example use

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))

image

Documentation

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")

Citation

If you use OMBackend.jl in academic work, please cite the entries in CITATION.bib.

License

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.

About

Backend for OMJL. A Modelica Compiler and environment written in Julia

Topics

Resources

Stars

4 stars

Watchers

8 watching

Forks

Releases

Packages

Used by

Contributors

Languages